Docs
OverviewGuidesZero & MCPAPI referenceChangelog
Enrichment

Enrich Lead

Run the enrichment waterfall for the lead and its company now. Fills empty fields only; suppressed or opted-out contact data is never added. 404 missing lead, 422 mobile lookups disabled, 503 no provider configured. A workspace's own enrichment provider (Settings -> AI & providers, kind `enrichment`) replaces the server's providers; its request budget answers 429 with `Retry-After` when used up. With `ENRICHMENT_ASYNC=true` (off by default) the same checks run, the enrichment is queued as a background job and the response is 202 with the job. A repeated request for the same lead and options while that job is queued or running, or one with the same `Idempotency-Key`, returns it.

API key access

Needs the leads:write scope with an API key (ro_pat_...). A signed-in session uses the caller's role.
POST/api/v1/leads/{lead_id}/enrich

Authorization

AuthorizationBearer <token>

Access token from /api/v1/auth/login, or an API key (ro_pat_..., RO-176) from /api/v1/workspaces/current/api-keys: the key implies its workspace and needs the route's scope. MCP connectors (/api/v1/mcp only) may use an OAuth access token (ro_oat_..., RO-284).

In: header

Path Parameters

lead_idstring
Formatuuid

Header Parameters

X-Workspace-Id?string | null

Id of the workspace to act on (must be a member).

Idempotency-Key?string | null

With ENRICHMENT_ASYNC: a replay with the same key returns the first job.

Request Body

include_phone?boolean
Defaultfalse
force_refresh?boolean
Defaultfalse

Response Body

curl -X POST "http://localhost:8000/api/v1/leads/497f6eca-6276-4993-bfeb-53cbbbba6f08/enrich" \  -H "X-Workspace-Id: string" \  -H "Idempotency-Key: string" \  -H "Content-Type: application/json" \  -d '{}'
{
  "lead": {
    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    "workspace_id": "0967198e-ec7b-4c6b-b4d3-f71244cadbe9",
    "first_name": "string",
    "last_name": "string",
    "title": "string",
    "email": "string",
    "phone": "string",
    "phone_type": "mobile",
    "linkedin_url": "string",
    "timezone": "string",
    "language": "string",
    "status": "new",
    "source": "string",
    "custom_fields": {
      "property1": null,
      "property2": null
    },
    "company_id": "b2e6a1c3-1a5e-44ae-a8fd-81f76fd715cf",
    "company": {},
    "owner_id": "8826ee2e-7933-4665-aef2-2393f84a0d05",
    "created_at": "2019-08-24T14:15:22Z",
    "updated_at": "2019-08-24T14:15:22Z"
  },
  "groups_requested": [
    "string"
  ],
  "updated": [
    {
      "entity": "string",
      "field": "string",
      "provider": "string"
    }
  ],
  "skipped": [
    {
      "field": "string",
      "provider": "string",
      "reason": "string"
    }
  ],
  "steps": [
    {
      "group": "string",
      "provider": "string",
      "operation": "string",
      "outcome": "string",
      "cached": true,
      "units": 0.1,
      "error": "string"
    }
  ],
  "company_linked": true,
  "credits_used": "string",
  "cost_estimate_usd": "string"
}
{
  "job_id": "453bd7d7-5355-4d6d-a38e-d9e7eb218c3f",
  "lead_id": "9bddab70-98e6-43a9-8f32-c9788b9de0c0",
  "status": "string",
  "deduplicated": true
}
{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string",
      "input": null,
      "ctx": {}
    }
  ]
}

Reject Email Draft

Reject a pending or approved draft: it is never sent, and the runner stops the lead's enrollment (`draft_rejected`). With `regenerate: true` the AI rewrites it instead, using `reason` as feedback: a new `pending` revision, and the sequence keeps running (same errors as `/regenerate`).

Enrichment Usage

Credits ledger totals per provider and operation for the workspace.