Skip to main content
A Job saves an operation’s ID, status and results so you can follow work after your request returns. Save its job_id to check progress and read results without starting the work again. The Quick Start finds one work email. Batch Processing covers files and lists.

Start and wait

Search, Find Contacts, Reverse Lookup and Intelligence requests accept wait_seconds from 0 to 20 (default 5). Age Verification and Workflow runs accept it too; a Workflow run defaults to 0. It sets how long your request waits for the Job to finish. It does not limit how long the Job runs. Use 0 to skip waiting for completion. A positive value gives short Jobs time to finish before the request returns. Reaching the wait limit does not cancel work; the Job continues in the background. Polling GET /v1/jobs/{job_id} returns HTTP 200 when you read the Job successfully, even while it is running. Check status, not the HTTP status, to decide whether to keep polling.
Store IDs exactly as returned. Do not extract parts or rebuild them. Jobs use job_, files use file_, and lists use list_.

Polling

Set JOB_ID to the ID returned by a start request. Replace YOUR_API_KEY with your API key. cURL also requires jq.

Job status and item status

A succeeded Job can contain failed items. A failed Job can still have successful items; keep those results before deciding whether to submit replacement work. Contact fields such as email_status describe the answer, not execution: NOT_FOUND does not mean the lookup Job failed.

Counts

counts reports input size, progress or saved item counts when available. Contacts and Intelligence know the input count when you send records directly. File-based requests and Search do not always know it at the start. Finished Jobs include counts when their saved items are readable. A missing or null counts means unavailable, not zero. Contacts and Intelligence count input records; Search counts retained profiles, not the requested max_results. Counts do not measure credits. For an export’s row count or a list’s size, read the file’s row_count or the list’s size rather than assuming every Job counts data rows.

Read every item

GET /v1/jobs/{job_id}/items accepts page_size from 1 to 1,000, default 100, and an opaque cursor. Pass each next_cursor unchanged to the next request; stop when it is null.
Contacts and Intelligence items use the zero-based input-record position as index and echo the record’s custom_id for matching. Search uses the result position, not an input-record position. Failed items carry status: "failed" and an error. Reading items does not start new research.

Browse Job history

GET /v1/jobs returns {items, next_cursor} for Jobs you can access. It accepts status, operation, page_size from 1 to 100, default 100, and cursor. Jobs appear from newest to oldest. Keep filters unchanged between pages and stop when next_cursor is null.

Captured charges

Every Job includes charge_credits: the credits charged so far, after refunds, when you read the Job. Credits held but not yet charged are not counted. The value can change after the Job finishes, so a finished Job does not mean billing is final. A null value means the charge is unknown or your team permissions withhold it. Legacy Jobs do not include this field.
Verify Email bills in the background after its response and is unaffected by this field.

Cancel work

POST /v1/jobs/{job_id}/cancel returns the Job with cancel_requested_at. Poll until the Job finishes. A finished Job is unchanged, and completed work remains billed.

Export results

Send exactly one source to POST /v1/exports: from.job_id for a finished Job with item results or from.list_id for a ready list. Set format to csv, json or ndjson. Exports contain successful item results. Empty results produce an empty export. Limits are 100 MB and 100,000 rows. CSV objects and lists use JSON text, booleans use true or false, and spreadsheet formulas are escaped. For Workflow output, download the files in result directly, as shown in Run a workflow batch. Item results are not available for every Workflow. To save other formats, send result_formats when starting the Workflow run. For a Job with item results, set SOURCE_JOB_ID to the finished source Job’s ID.
1

Start an export

2

Poll the export Job

The export request returns 202. Run the polling loop with the export’s job_id, not the source Job’s ID. Continue only if the export reaches succeeded; otherwise inspect its error. Read the file ID from result.output_file_id.
3

Download the file

Call GET /v1/files/{file_id} to read the file’s metadata. Then download its signed download_url with the same API key. Both requests require authentication. Do not follow redirects when sending credentials. The URL is valid for 15 minutes. Read the same file resource again to refresh an expired URL instead of rerunning research.

Try it

Open the Export Results API Reference playground.

Idempotency keys

Send Idempotency-Key on start requests to retry without starting duplicate work. Generate a UUID v4 for each new operation. Save it with the request body before sending the request. The maximum key length is 255 characters.
  1. The first request starts the work.
  2. The same key and body return the same Job, without another charge. The response includes Idempotent-Replayed: true.
  3. The same key with a different body returns HTTP 409 and idempotency_key_reused.
Keys are scoped to your organization and the action you start. JSON keys are remembered as long as the Job is available. CSV keys are remembered for 24 hours; the filename and contents must match. See Handling Errors for retries.

Records, items and rows

  • A record is the person or company you send for processing.
  • An item is an entry returned by /items, with an input, status, result and error.
  • A row is an entry in an uploaded or downloaded data file.

Results by Job type

Webhooks

Set webhook_url on a Search, Contacts or Intelligence start request to receive callbacks. Verify signatures and deduplicate deliveries using Outgoing Webhooks. Keep the returned job_id to poll or read items.

Retention

Save results you need to keep. Reading items does not start research again; expired results return items_not_available. File download URLs expire; read the file resource again for a fresh URL.
For older Job status and callbacks, see Legacy.