Skip to main content

Endpoint

Use the people endpoint for lead/person rows:
Use the company endpoint for company rows:

People API Reference

Full request/response schema for POST /bulk-intelligence/people.

Company API Reference

Full request/response schema for POST /bulk-intelligence/company.

Tiers

Bulk jobs use the same tiers and access rules as the single-record endpoints: Atlas run options (graph, max_credits, max_minutes, investigation_id) are not accepted in config; each xhigh row runs one investigation on the default budget.

Request format

Both endpoints take multipart/form-data with two parts:

Limits

For the submission rate limit, see Rate Limits.

The config object

config takes the same options as the single-record request, minus the input record itself (each row is the input), plus three bulk-only fields. Unknown keys are rejected.
For struct value formats, supported types, and casting, see Struct & Type Casting. result_formats lists the output files. CSV is always produced; add "ndjson" for typed values (numbers, booleans and nested objects). Each format is its own results entry; pick by filename extension.

Submitting a job

The response includes the job handle and the cost estimate:

Polling for results

Poll GET /job-status/{task_id} until status is no longer running. A completed job carries results (signed links to the output files), results_url (the run in the Sixtyfour app) and charge_credits, and no inline result. See Async Jobs for statuses, polling and retention. The final enriched file is the results entry with the highest block_number. An entry for a file of at most 200 rows and 512 KB also holds the rows in its own results field. CSV downloads are escaped for spreadsheets by default, so a phone number +14155550123 downloads as '+14155550123. Append ?spreadsheet_safe=false to the download_url to get the file as stored, or read the NDJSON file. See Spreadsheet-safe CSV.

Tracking progress while running

While status is running, a bulk response includes a progress object with the number of rows enriched so far out of the total submitted:
Download links are signed URLs that expire after 15 minutes, poll again for fresh links, and require your x-api-key header when fetching.

Webhook callback

Pass webhook_url in the config to receive the result when the job completes. The callback’s run_id is the job’s task_id, and results_download_url links the enriched CSV for 15 minutes. See Outgoing Webhooks for the payload. With webhook_url, the final results file adds three columns: webhook_status_code, webhook_response and webhook_success.
Webhook URLs must use HTTPS and resolve to a public address. The URL is validated when you submit and again at delivery time.

Idempotency

Send an Idempotency-Key header (up to 255 characters) to make submissions retry-safe. The key is scoped to your organization and the endpoint, and kept for 24 hours. Resubmitting with the same key returns the original job instead of starting a new one, with status set to that job’s current status in uppercase, such as RUNNING or COMPLETED:
A replay omits row_count and the cost estimate.

Failure behavior

Rows that fail enrichment pass through un-enriched; one bad row does not fail the job. A file that cannot be parsed is rejected before anything runs. A job that fails as a whole reports failed with no error.

Pricing

The submit response carries estimated_cost_credits; a start your balance does not cover is refused with 402. See Credit Costs for the price of each tier.
For new integrations, see Bulk Intelligence.