Enrich a Profile

POST

enrich

{profile_id}

Enrich a Profile

curl --request POST \
  --url https://api.orbitsearch.com/v3/enrich/{profile_id} \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "request_id": "enrich-profile-123-full",
  "operation": "full",
  "include_profile": true
}
'

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    request_id: 'enrich-profile-123-full',
    operation: 'full',
    include_profile: true
  })
};

fetch('https://api.orbitsearch.com/v3/enrich/{profile_id}', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://api.orbitsearch.com/v3/enrich/{profile_id}"

payload = {
    "request_id": "enrich-profile-123-full",
    "operation": "full",
    "include_profile": True
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

{
  "request_id": "<string>",
  "profile_id": "<string>",
  "status": "running",
  "operation": "partial",
  "include_profile": true,
  "generation_level": 2,
  "links": {
    "profile": "<string>",
    "status": "<string>"
  },
  "profile": {
    "id": "<string>",
    "generationLevel": 2,
    "avatarUrl": "<string>",
    "verified": true,
    "sections": {},
    "sources": [
      {
        "link": "<string>",
        "title": "<string>",
        "summary": "<string>",
        "caption": "<string>",
        "images": [
          "<string>"
        ],
        "sourceName": "<string>",
        "sourceImage": "<string>",
        "chunks": [
          {
            "text": "<string>"
          }
        ],
        "sources": "<array>"
      }
    ],
    "displayName": "<string>",
    "personName": "<string>",
    "aliases": [
      "<string>"
    ],
    "profileUrl": "<string>",
    "slug": "<string>",
    "category": {
      "id": "<string>",
      "label": "<string>"
    },
    "location": {
      "city": "<string>",
      "region": "<string>",
      "country": "<string>"
    },
    "headline": {
      "jobTitle": "<string>",
      "companyName": "<string>",
      "schoolName": "<string>"
    },
    "emails": [
      "jsmith@example.com"
    ],
    "phoneNumbers": [
      "<string>"
    ],
    "addresses": [
      {}
    ]
  },
  "failure": {
    "code": "<string>",
    "message": "<string>",
    "retryable": true,
    "reason": "<string>",
    "suggested_inputs": [
      "<string>"
    ]
  },
  "billing": {
    "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "pricingVersion": "<string>",
    "reservedCredits": 1,
    "consumedCredits": 1,
    "releasedCredits": 1,
    "heldCredits": 1,
    "status": "open"
  }
}

{
  "request_id": "<string>",
  "profile_id": "<string>",
  "status": "running",
  "operation": "partial",
  "include_profile": true,
  "generation_level": 2,
  "links": {
    "profile": "<string>",
    "status": "<string>"
  },
  "profile": {
    "id": "<string>",
    "generationLevel": 2,
    "avatarUrl": "<string>",
    "verified": true,
    "sections": {},
    "sources": [
      {
        "link": "<string>",
        "title": "<string>",
        "summary": "<string>",
        "caption": "<string>",
        "images": [
          "<string>"
        ],
        "sourceName": "<string>",
        "sourceImage": "<string>",
        "chunks": [
          {
            "text": "<string>"
          }
        ],
        "sources": "<array>"
      }
    ],
    "displayName": "<string>",
    "personName": "<string>",
    "aliases": [
      "<string>"
    ],
    "profileUrl": "<string>",
    "slug": "<string>",
    "category": {
      "id": "<string>",
      "label": "<string>"
    },
    "location": {
      "city": "<string>",
      "region": "<string>",
      "country": "<string>"
    },
    "headline": {
      "jobTitle": "<string>",
      "companyName": "<string>",
      "schoolName": "<string>"
    },
    "emails": [
      "jsmith@example.com"
    ],
    "phoneNumbers": [
      "<string>"
    ],
    "addresses": [
      {}
    ]
  },
  "failure": {
    "code": "<string>",
    "message": "<string>",
    "retryable": true,
    "reason": "<string>",
    "suggested_inputs": [
      "<string>"
    ]
  },
  "billing": {
    "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "pricingVersion": "<string>",
    "reservedCredits": 1,
    "consumedCredits": 1,
    "releasedCredits": 1,
    "heldCredits": 1,
    "status": "open"
  }
}

{
  "status": "failed",
  "error": {
    "code": "<string>",
    "message": "<string>",
    "requiredCredits": 1,
    "remainingCredits": 1
  }
}

{
  "status": "failed",
  "error": {
    "code": "<string>",
    "message": "<string>",
    "requiredCredits": 1,
    "remainingCredits": 1
  }
}

{
  "status": "failed",
  "error": {
    "code": "<string>",
    "message": "<string>",
    "requiredCredits": 1,
    "remainingCredits": 1
  }
}

{
  "status": "failed",
  "error": {
    "code": "<string>",
    "message": "<string>",
    "requiredCredits": 1,
    "remainingCredits": 1
  }
}

{
  "status": "failed",
  "error": {
    "code": "<string>",
    "message": "<string>",
    "requiredCredits": 1,
    "remainingCredits": 1
  }
}

{
  "status": "failed",
  "error": {
    "code": "<string>",
    "message": "<string>",
    "requiredCredits": 1,
    "remainingCredits": 1
  }
}

{
  "status": "failed",
  "error": {
    "code": "<string>",
    "message": "<string>",
    "requiredCredits": 1,
    "remainingCredits": 1
  }
}

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.

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 full public 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 operation is terminal. A request for a profile already at the requested depth can return 202. It completes in a few seconds and its billing.consumedCredits is 0. Read billing on the terminal response for the final charge; the HTTP status code carries the progress of the work.

{
  "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"]
  },
  "billing": {
    "id": "9b1f6c2e-4d3a-4f8e-9c21-7a5e0d2b6f13",
    "pricingVersion": "2026-09-17",
    "reservedCredits": 10,
    "consumedCredits": 0,
    "releasedCredits": 0,
    "heldCredits": 10,
    "status": "open"
  },
  "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 response embeds the full available public profile: its sections, sources, and deduplicated emails and phoneNumbers when available.

Timing

Operation	Typical time to complete
`partial`	Under two minutes
`full`	25 to 30 minutes
`regenerate`	25 to 30 minutes

Poll links.status every few seconds for a partial build. For full and regenerate, a 15-second interval is sufficient. Keep polling for more than 30 minutes for full-depth work. Orbit completes and charges a build even when the client stops polling.

Authentication and Cost

This endpoint requires search:read. Requests with include_profile: true also require profile:read. See API credits for profile-generation and read charges, and rate limits for request limits.

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.

Authorizations

Authorization

string

header

required

Use an Orbit API key from the Developer Dashboard.

Headers

Idempotency-Key

string

A client-generated key for a safe retry. If the body omits request_id, Orbit can use this value as the request ID.

Maximum string length: 200

Path Parameters

profile_id

string

required

An Orbit profile ID or public profile slug. Profile reads also accept known alias IDs.

Minimum string length: 1

Body

application/json

operation

enum<string>

required

Use partial for a useful profile, full for the deepest available profile, or regenerate to rebuild a fresh full profile.

Available options:

partial,

full,

regenerate

request_id

string

Your idempotency key. Keep it stable across retries of the same operation.

Minimum string length: 1

include_profile

boolean

default:true

Embed the full public profile when one is available.

Response

The requested result is already available or the operation is terminal.

request_id

string

required

profile_id

string

required

status

enum<string>

required

Available options:

running,

completed,

failed

operation

enum<string>

required

Use partial for a useful profile, full for the deepest available profile, or regenerate to rebuild a fresh full profile.

Available options:

partial,

full,

regenerate

include_profile

boolean

required

generation_level

integer | null

required

Required range: x >= 1

links

object

required

Show child attributes

profile

object

The public Orbit profile. Available fields depend on the profile generation level.

Show child attributes

failure

object

Show child attributes

billing

object

Credits held and spent for this request. Omitted when Orbit served the request from the stored profile. The final consumedCredits is the full charge once status is settled.

Show child attributes

Enrich a Profile

curl --request POST \
  --url https://api.orbitsearch.com/v3/enrich/{profile_id} \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "request_id": "enrich-profile-123-full",
  "operation": "full",
  "include_profile": true
}
'

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    request_id: 'enrich-profile-123-full',
    operation: 'full',
    include_profile: true
  })
};

fetch('https://api.orbitsearch.com/v3/enrich/{profile_id}', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://api.orbitsearch.com/v3/enrich/{profile_id}"

payload = {
    "request_id": "enrich-profile-123-full",
    "operation": "full",
    "include_profile": True
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

{
  "request_id": "<string>",
  "profile_id": "<string>",
  "status": "running",
  "operation": "partial",
  "include_profile": true,
  "generation_level": 2,
  "links": {
    "profile": "<string>",
    "status": "<string>"
  },
  "profile": {
    "id": "<string>",
    "generationLevel": 2,
    "avatarUrl": "<string>",
    "verified": true,
    "sections": {},
    "sources": [
      {
        "link": "<string>",
        "title": "<string>",
        "summary": "<string>",
        "caption": "<string>",
        "images": [
          "<string>"
        ],
        "sourceName": "<string>",
        "sourceImage": "<string>",
        "chunks": [
          {
            "text": "<string>"
          }
        ],
        "sources": "<array>"
      }
    ],
    "displayName": "<string>",
    "personName": "<string>",
    "aliases": [
      "<string>"
    ],
    "profileUrl": "<string>",
    "slug": "<string>",
    "category": {
      "id": "<string>",
      "label": "<string>"
    },
    "location": {
      "city": "<string>",
      "region": "<string>",
      "country": "<string>"
    },
    "headline": {
      "jobTitle": "<string>",
      "companyName": "<string>",
      "schoolName": "<string>"
    },
    "emails": [
      "jsmith@example.com"
    ],
    "phoneNumbers": [
      "<string>"
    ],
    "addresses": [
      {}
    ]
  },
  "failure": {
    "code": "<string>",
    "message": "<string>",
    "retryable": true,
    "reason": "<string>",
    "suggested_inputs": [
      "<string>"
    ]
  },
  "billing": {
    "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "pricingVersion": "<string>",
    "reservedCredits": 1,
    "consumedCredits": 1,
    "releasedCredits": 1,
    "heldCredits": 1,
    "status": "open"
  }
}

{
  "request_id": "<string>",
  "profile_id": "<string>",
  "status": "running",
  "operation": "partial",
  "include_profile": true,
  "generation_level": 2,
  "links": {
    "profile": "<string>",
    "status": "<string>"
  },
  "profile": {
    "id": "<string>",
    "generationLevel": 2,
    "avatarUrl": "<string>",
    "verified": true,
    "sections": {},
    "sources": [
      {
        "link": "<string>",
        "title": "<string>",
        "summary": "<string>",
        "caption": "<string>",
        "images": [
          "<string>"
        ],
        "sourceName": "<string>",
        "sourceImage": "<string>",
        "chunks": [
          {
            "text": "<string>"
          }
        ],
        "sources": "<array>"
      }
    ],
    "displayName": "<string>",
    "personName": "<string>",
    "aliases": [
      "<string>"
    ],
    "profileUrl": "<string>",
    "slug": "<string>",
    "category": {
      "id": "<string>",
      "label": "<string>"
    },
    "location": {
      "city": "<string>",
      "region": "<string>",
      "country": "<string>"
    },
    "headline": {
      "jobTitle": "<string>",
      "companyName": "<string>",
      "schoolName": "<string>"
    },
    "emails": [
      "jsmith@example.com"
    ],
    "phoneNumbers": [
      "<string>"
    ],
    "addresses": [
      {}
    ]
  },
  "failure": {
    "code": "<string>",
    "message": "<string>",
    "retryable": true,
    "reason": "<string>",
    "suggested_inputs": [
      "<string>"
    ]
  },
  "billing": {
    "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "pricingVersion": "<string>",
    "reservedCredits": 1,
    "consumedCredits": 1,
    "releasedCredits": 1,
    "heldCredits": 1,
    "status": "open"
  }
}

{
  "status": "failed",
  "error": {
    "code": "<string>",
    "message": "<string>",
    "requiredCredits": 1,
    "remainingCredits": 1
  }
}

{
  "status": "failed",
  "error": {
    "code": "<string>",
    "message": "<string>",
    "requiredCredits": 1,
    "remainingCredits": 1
  }
}

{
  "status": "failed",
  "error": {
    "code": "<string>",
    "message": "<string>",
    "requiredCredits": 1,
    "remainingCredits": 1
  }
}

{
  "status": "failed",
  "error": {
    "code": "<string>",
    "message": "<string>",
    "requiredCredits": 1,
    "remainingCredits": 1
  }
}

{
  "status": "failed",
  "error": {
    "code": "<string>",
    "message": "<string>",
    "requiredCredits": 1,
    "remainingCredits": 1
  }
}

{
  "status": "failed",
  "error": {
    "code": "<string>",
    "message": "<string>",
    "requiredCredits": 1,
    "remainingCredits": 1
  }
}

{
  "status": "failed",
  "error": {
    "code": "<string>",
    "message": "<string>",
    "requiredCredits": 1,
    "remainingCredits": 1
  }
}

Search

Enrich

Watchers

Webhooks

Keys

Request Body

Operation Behavior

Response

Timing

Authentication and Cost

Idempotency

Authorizations

Headers

Path Parameters

Body

Response

​Request Body

​Operation Behavior

​Response

​Timing

​Authentication and Cost

​Idempotency

Authorizations

Headers

Path Parameters

Body

Response

Request Body

Operation Behavior

Response

Timing

Authentication and Cost

Idempotency