> ## Documentation Index
> Fetch the complete documentation index at: https://docs.orbitsearch.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Batch enrich profiles

> Apply one partial, full, or regenerate operation to as many as 20 known Orbit profile IDs or slugs.

Applies the same Enrich operation to 1–20 Orbit IDs or profile slugs. Each identifier resolves to its canonical Orbit ID before work starts.

```bash theme={"dark"}
curl -X POST "https://api.orbitsearch.com/v3/enrich" \
  -H "Authorization: Bearer $ORBIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "profile_ids": ["profile_123", "profile_456"],
    "operation": "full",
    "include_profile": true
  }'
```

## Request body

| Field             | Type                               | Default  | Description                                                                                                          |
| ----------------- | ---------------------------------- | -------- | -------------------------------------------------------------------------------------------------------------------- |
| `profile_ids`     | string\[]                          | Required | Between 1 and 20 Orbit profile IDs or slugs. Duplicate entries are normalized. The field name remains `profile_ids`. |
| `operation`       | `partial`, `full`, or `regenerate` | Required | Operation applied to every profile.                                                                                  |
| `include_profile` | boolean                            | `true`   | Embed available profiles in child results.                                                                           |

## Response

```json theme={"dark"}
{
  "request_id": "batch-full-001",
  "status": "running",
  "results": [
    {
      "request_id": "batch-full-001:profile_123",
      "profile_id": "profile_123",
      "status": "completed",
      "operation": "full",
      "include_profile": true,
      "generation_level": 3,
      "profile": {
        "id": "profile_123",
        "displayName": "Example Person",
        "generationLevel": 3
      },
      "links": {
        "profile": "/v3/enrich/profile_123"
      }
    },
    {
      "request_id": "batch-full-001:profile_456",
      "profile_id": "profile_456",
      "status": "running",
      "operation": "full",
      "include_profile": true,
      "generation_level": 2,
      "links": {
        "status": "/v3/enrich/requests/batch-full-001%3Aprofile_456",
        "profile": "/v3/enrich/profile_456"
      }
    }
  ]
}
```

The batch status is `running`, `completed`, or `completed_with_errors`. Each result has its own child `request_id` and status.

<Warning>
  There is no aggregate batch status endpoint. Poll each running child's `links.status` URL until it completes or fails.
</Warning>

The endpoint returns `202 Accepted` if any child is running and `200 OK` otherwise. It requires `search:read`; `include_profile: true` also requires `profile:read`. v3 Enrich does not consume credits.


## OpenAPI

````yaml openapi.json POST /v3/enrich
openapi: 3.1.0
info:
  title: Orbit API
  version: 3.0.0
  description: Search for people and enrich known Orbit profiles.
servers:
  - url: https://api.orbitsearch.com
    description: Production
security:
  - bearerAuth: []
tags:
  - name: Search
    description: Find people and poll search results.
  - name: Enrich
    description: Read or enrich known Orbit profiles.
  - name: Watchers
    description: Watch a profile on a schedule and read what each run found.
  - name: Webhooks
    description: Register endpoints that receive signed event deliveries.
paths:
  /v3/enrich:
    post:
      tags:
        - Enrich
      summary: Batch enrich profiles
      description: >-
        Apply one enrichment operation to between 1 and 20 known Orbit profile
        IDs. Requires the `search:read` scope. Requests that include profiles
        also require `profile:read`.
      operationId: batchEnrichProfiles
      parameters:
        - $ref: '#/components/parameters/IdempotencyKey'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BatchEnrichRequest'
      responses:
        '200':
          description: Every child request is terminal.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BatchEnrichSnapshot'
        '202':
          description: At least one child request is running.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BatchEnrichSnapshot'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '409':
          $ref: '#/components/responses/Conflict'
        '429':
          $ref: '#/components/responses/RateLimited'
components:
  parameters:
    IdempotencyKey:
      name: Idempotency-Key
      in: header
      required: false
      description: >-
        A client-generated key for a safe retry. If the body omits `request_id`,
        Orbit can use this value as the request ID.
      schema:
        type: string
        maxLength: 200
  schemas:
    BatchEnrichRequest:
      type: object
      additionalProperties: false
      required:
        - profile_ids
        - operation
      properties:
        request_id:
          type: string
          minLength: 1
          description: The parent idempotency key for the batch.
        profile_ids:
          type: array
          minItems: 1
          maxItems: 20
          description: >-
            Provide between 1 and 20 Orbit profile IDs or slugs. Duplicate
            entries within this list are normalized before work starts.
          items:
            type: string
            minLength: 1
        operation:
          $ref: '#/components/schemas/EnrichOperation'
        include_profile:
          type: boolean
          default: true
          description: Embed available profiles in child results.
      example:
        request_id: batch-full-001
        profile_ids:
          - profile_123
          - profile_456
        operation: full
        include_profile: true
    BatchEnrichSnapshot:
      type: object
      required:
        - request_id
        - status
        - results
      properties:
        request_id:
          type: string
        status:
          type: string
          enum:
            - running
            - completed
            - completed_with_errors
        results:
          type: array
          items:
            $ref: '#/components/schemas/EnrichSnapshot'
    EnrichOperation:
      type: string
      enum:
        - partial
        - full
        - regenerate
      description: >-
        Use `partial` for a useful profile, `full` for the deepest available
        profile, or `regenerate` to rebuild a fresh full profile.
    EnrichSnapshot:
      type: object
      required:
        - request_id
        - profile_id
        - status
        - operation
        - include_profile
        - generation_level
        - links
      properties:
        request_id:
          type: string
        profile_id:
          type: string
        status:
          type: string
          enum:
            - running
            - completed
            - failed
        operation:
          $ref: '#/components/schemas/EnrichOperation'
        include_profile:
          type: boolean
        generation_level:
          oneOf:
            - type: integer
              minimum: 1
            - type: 'null'
        profile:
          $ref: '#/components/schemas/PublicProfile'
        failure:
          $ref: '#/components/schemas/Failure'
        links:
          $ref: '#/components/schemas/EnrichLinks'
    ErrorResponse:
      type: object
      required:
        - status
        - error
      properties:
        status:
          type: string
          enum:
            - failed
        error:
          type: object
          required:
            - code
            - message
          properties:
            code:
              type: string
            message:
              type: string
    PublicProfile:
      type: object
      description: >-
        The public Orbit profile. Available fields depend on the profile
        generation level.
      required:
        - id
        - generationLevel
        - avatarUrl
        - verified
        - sections
        - sources
      additionalProperties: true
      properties:
        id:
          type: string
        displayName:
          type: string
        personName:
          type: string
        aliases:
          type: array
          items:
            type: string
        generationLevel:
          oneOf:
            - type: integer
              minimum: 1
              maximum: 3
            - type: 'null'
        avatarUrl:
          oneOf:
            - type: string
              format: uri
            - type: 'null'
        profileUrl:
          type: string
          format: uri
        slug:
          type: string
        category:
          type: object
          required:
            - id
            - label
          properties:
            id:
              type: string
            label:
              type: string
        verified:
          type: boolean
        location:
          type: object
          properties:
            city:
              type: string
            region:
              type: string
            country:
              type: string
        headline:
          type: object
          properties:
            jobTitle:
              type: string
            companyName:
              type: string
            schoolName:
              type: string
        emails:
          type: array
          items:
            type: string
            format: email
        phoneNumbers:
          type: array
          items:
            type: string
        addresses:
          type: array
          items:
            type: object
            additionalProperties: true
        sections:
          type: object
          description: >-
            Structured profile sections. Standard sections are objects with
            section-specific items, or null when no public data is available.
            Items can carry item-level sources that map each item to its
            supporting evidence.
          additionalProperties:
            oneOf:
              - type: 'null'
              - type: object
                description: >-
                  A content section: items plus an optional deduplicated
                  section-level sources union.
                required:
                  - items
                additionalProperties: true
                properties:
                  items:
                    type: array
                    items:
                      type: object
                      additionalProperties: true
                      properties:
                        sources:
                          type: array
                          description: >-
                            Public evidence for this item only. Each source can
                            include excerpt chunks that support the item.
                            Omitted when no evidence is attributed to the item.
                          items:
                            $ref: '#/components/schemas/Source'
                  sources:
                    type: array
                    description: Deduplicated union of the evidence for the whole section.
                    items:
                      $ref: '#/components/schemas/Source'
              - type: object
                description: >-
                  The bio section: a public profile summary with optional
                  sources instead of items.
                required:
                  - bio
                additionalProperties: true
                properties:
                  bio:
                    type: string
                  sources:
                    type: array
                    description: Deduplicated union of the evidence for the whole section.
                    items:
                      $ref: '#/components/schemas/Source'
        sources:
          type: array
          description: Deduplicated and sanitized public sources used across the profile.
          items:
            $ref: '#/components/schemas/Source'
    Failure:
      type: object
      required:
        - code
        - message
        - retryable
        - reason
      properties:
        code:
          type: string
        message:
          type: string
        retryable:
          type: boolean
        reason:
          type: string
        suggested_inputs:
          type: array
          items:
            type: string
    EnrichLinks:
      type: object
      required:
        - profile
      properties:
        status:
          type: string
          description: Relative URL for the enrichment status endpoint.
        profile:
          type: string
          description: Relative URL for the profile-read endpoint.
    Source:
      type: object
      description: >-
        A sanitized public source. Profile-level sources, section sources, item
        sources, and image sources share this shape.
      required:
        - link
      additionalProperties: true
      properties:
        link:
          type: string
          format: uri
        title:
          type: string
        summary:
          type: string
        caption:
          type: string
        images:
          type: array
          items:
            type: string
            format: uri
        sourceName:
          type: string
        sourceImage:
          type: string
          format: uri
        chunks:
          type: array
          description: Public evidence text extracted from the source.
          items:
            type: object
            required:
              - text
            properties:
              text:
                type: string
        sources:
          type: array
          description: >-
            Nested public sources when one source record contains additional
            sources.
          items:
            $ref: '#/components/schemas/Source'
  responses:
    BadRequest:
      description: The request is not valid.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    Unauthorized:
      description: The API key is missing or not valid.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    Forbidden:
      description: The API key does not have the required scope.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    Conflict:
      description: The request ID was already used with different inputs.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    RateLimited:
      description: The API key exceeded a rate limit.
      headers:
        Retry-After:
          description: Seconds to wait before another request.
          schema:
            type: integer
            minimum: 0
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: Orbit API key
      description: Use an Orbit API key from the developer dashboard.

````