> ## 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.

# Enrich a profile

> Read, upgrade, or regenerate one known Orbit profile ID or slug with a partial, full, or regenerate operation.

Enrich accepts either the canonical Orbit ID or the slug at the end of `profileUrl`. Both resolve to the same Orbit profile; choose the result you need and Orbit decides whether it can return the current profile immediately or must build more data.

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

## Request body

The `{profile_id}` path parameter accepts a canonical Orbit ID or profile slug. `profile_id` is the API field name for the canonical Orbit ID returned in responses; it is not a second kind of ID.

| Field             | Type                               | Default  | Description                              |
| ----------------- | ---------------------------------- | -------- | ---------------------------------------- |
| `operation`       | `partial`, `full`, or `regenerate` | Required | Desired profile result.                  |
| `include_profile` | boolean                            | `true`   | Embed the profile when one is available. |

## Operation behavior

| Existing profile | `partial`              | `full`                 | `regenerate`                 |
| ---------------- | ---------------------- | ---------------------- | ---------------------------- |
| Level 1          | Build partial          | Build full             | Build full                   |
| Level 2          | Return current profile | Build full             | Build full                   |
| Level 3          | Return current profile | Return current profile | Rebuild a fresh full profile |

Use `partial` when a useful profile is enough, `full` when you need the deepest available profile, and `regenerate` only when you want fresh work even if a full profile already exists.

## Response

Orbit returns `202 Accepted` when enrichment is running and `200 OK` when the requested result is already available or the operation is terminal.

```json theme={"dark"}
{
  "request_id": "enrich-profile-123-full",
  "profile_id": "profile_123",
  "status": "running",
  "operation": "full",
  "include_profile": true,
  "generation_level": 2,
  "profile": {
    "id": "profile_123",
    "displayName": "Example Person",
    "generationLevel": 2,
    "emails": ["person@example.com"],
    "phoneNumbers": ["+14155550123"]
  },
  "links": {
    "status": "/v3/enrich/requests/enrich-profile-123-full",
    "profile": "/v3/enrich/profile_123"
  }
}
```

Status is `running`, `completed`, or `failed`. A failed response includes `failure.code`, `failure.message`, and `failure.retryable`.

When `include_profile` is `true`, the embedded profile includes deduplicated `emails` and `phoneNumbers` when available.

## Authentication and cost

This endpoint requires `search:read`. Requests with `include_profile: true` also require `profile:read`. v3 Enrich does not consume credits; [rate limits](/concepts/rate-limits) still apply.

## Idempotency

Orbit generates and returns `request_id` for status polling; callers do not need to supply one. For safe POST retries after a lost response, advanced clients may send an optional `Idempotency-Key` header and reuse it only with the same profile, operation, and `include_profile` value.


## OpenAPI

````yaml openapi.json POST /v3/enrich/{profile_id}
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/{profile_id}:
    post:
      tags:
        - Enrich
      summary: Enrich a profile
      description: >-
        Read, upgrade, or regenerate one known Orbit profile. Requires the
        `search:read` scope. Requests that include the profile also require
        `profile:read`.
      operationId: enrichProfile
      parameters:
        - $ref: '#/components/parameters/ProfileId'
        - $ref: '#/components/parameters/IdempotencyKey'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EnrichRequest'
      responses:
        '200':
          description: >-
            The requested result is already available or the operation is
            terminal.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EnrichSnapshot'
        '202':
          description: Enrichment is running.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EnrichSnapshot'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
        '429':
          $ref: '#/components/responses/RateLimited'
components:
  parameters:
    ProfileId:
      name: profile_id
      in: path
      required: true
      description: >-
        An Orbit profile ID or public profile slug. Profile reads also accept
        known alias IDs.
      schema:
        type: string
        minLength: 1
    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:
    EnrichRequest:
      type: object
      additionalProperties: false
      required:
        - operation
      properties:
        request_id:
          type: string
          minLength: 1
          description: >-
            Your idempotency key. Keep it stable across retries of the same
            operation.
        operation:
          $ref: '#/components/schemas/EnrichOperation'
        include_profile:
          type: boolean
          default: true
          description: Embed the profile when it is available.
      example:
        request_id: enrich-profile-123-full
        operation: full
        include_profile: true
    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'
    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.
    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.
    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
    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'
    NotFound:
      description: The requested resource was not found.
      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.

````