Skip to main content

Look up contacts from a file

  1. Save your records as CSV, JSON, JSONL or NDJSON.
  2. Upload the file to get a file_id.
  3. Start a Job with input_file_id.
  4. Poll the Job and read its items.
  5. Export the results and download the file.

Prepare the input records

Save this as people.csv:
Keep custom_id to match each result to your records. Files support up to 100,000 rows.

Upload and start

Replace YOUR_API_KEY with your API key. Python uses requests; cURL uses jq; JavaScript uses Node.js 18 or later.
Files over 45 MiB need the two-step upload. The maximum file size is 100 MB. A finished batch returns a Job:
HTTP 200 (excerpt)

Check the Job

Continue with the Job from the start request:
See Async Jobs for status meanings and polling.

Read the items

Pass next_cursor unchanged for more pages. See Read every item.

Download the results

Use the shared export and download flow with the completed Job’s ID as from.job_id.

Research records from a file

Use POST /v1/people/intelligence or POST /v1/companies/intelligence with input_file_id, tier and fields to research each record. See Bulk Intelligence.

Send inline records

Use people for Contacts or People Intelligence and companies for Company Intelligence instead of uploading a file.

Run a workflow batch

For editor batches, rows from your own systems and custom processing, see Workflow Batches.
For older bulk contact requests, see Legacy.