Docs / API Reference / Enrichment

Enrichment

Find and verify email addresses for your extracted leads. Enrichment runs asynchronously — preview the credit cost, start the job, then poll for completion and retrieve results per lead.

Enrichment costs credits. Use POST /preview to check the cost before committing. See Credits for your current balance.

Preview Enrichment Cost

POST/api/v1/enrichment/previewauth

Calculate how many credits enriching a set of leads will cost, without starting the job.

Body parameters

queryId
string

Enrich all leads from this search query. Provide either queryId or leadIds, not both.

leadIds
string[]

Enrich specific leads by their IDs. Provide either this or queryId.

Example response

json
{
  "success": true,
  "data": {
    "totalLeads": 47,
    "alreadyEnriched": 12,
    "toEnrich": 35,
    "estimatedCredits": 35,
    "availableCredits": 88
  }
}
curl
curl -X POST https://leadsapi.postorbit.io/api/v1/enrichment/preview \
  -H "Authorization: Bearer $LOCALLEADS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"queryId": "cm9search123"}'

Start Enrichment Job

POST/api/v1/enrichment/startauth

Start an enrichment job. Credits are reserved immediately. Returns a job ID to poll.

Body parameters

queryId
string

Enrich all leads from a query. Provide either this or leadIds.

leadIds
string[]

Enrich specific leads by ID.

maxCredits
number

Safety cap — the job will not exceed this many credits. Defaults to your full available balance.

json
{
  "success": true,
  "data": {
    "jobId": "enrich_abc123",
    "leadsQueued": 35,
    "creditsReserved": 35
  }
}
curl
curl -X POST https://leadsapi.postorbit.io/api/v1/enrichment/start \
  -H "Authorization: Bearer $LOCALLEADS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"queryId": "cm9search123", "maxCredits": 50}'

Poll Job Status

GET/api/v1/enrichment/status/:jobIdauth

Check the progress of a running enrichment job. Poll until status is COMPLETED or FAILED.

Path parameters

:jobId*
string

The job ID returned by POST /start.

json
{
  "success": true,
  "data": {
    "jobId": "enrich_abc123",
    "status": "PROCESSING",     // PENDING | PROCESSING | COMPLETED | FAILED
    "progress": 62,             // 0–100
    "processedLeads": 22,
    "totalLeads": 35,
    "foundEmails": 18
  }
}
javascript
async function waitForEnrichment(jobId) {
  const url = `https://leadsapi.postorbit.io/api/v1/enrichment/status/${jobId}`;
  const headers = { Authorization: `Bearer ${process.env.LOCALLEADS_API_KEY}` };
  while (true) {
    const { data } = await fetch(url, { headers }).then((r) => r.json());
    console.log(`Progress: ${data.progress}%`);
    if (data.status === "COMPLETED") return data;
    if (data.status === "FAILED") throw new Error("Enrichment failed");
    await new Promise((r) => setTimeout(r, 3000));
  }
}

Get Lead Enrichment Data

GET/api/v1/enrichment/lead/:leadIdauth

Retrieve enrichment data (emails, confidence scores) for a single lead.

Path parameters

:leadId*
string

The lead ID from a search result.

json
{
  "success": true,
  "data": {
    "leadId": "cm9lead001",
    "emails": [
      {
        "email": "[email protected]",
        "confidence": 0.94,
        "source": "website"
      }
    ],
    "enrichedAt": "2026-05-05T11:23:00.000Z"
  }
}

List Active Jobs

GET/api/v1/enrichment/jobsauth

List all currently running enrichment (and search) jobs for your organisation.

json
{
  "success": true,
  "data": [
    {
      "jobId": "enrich_abc123",
      "progress": 62,
      "leadCount": 35,
      "type": "enrichment"
    },
    {
      "jobId": "cm9search456",
      "progress": 50,
      "leadCount": 100,
      "type": "search",
      "query": "Lawyers"
    }
  ]
}
Use this endpoint to check whether a previous job is still running before starting a new one, and to avoid duplicate jobs in automation pipelines.
←LeadsCredits→