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 a saved workflow with an Upload Data (read_csv) source, upload the input and pass the returned file_id unchanged as source_overrides.resource_handle_id. Raw resource UUIDs are also accepted. The file’s columns must match the saved workflow’s source settings. These overrides apply to this run only. Replace WORKFLOW_ID with your saved workflow’s ID. Use people.csv from Prepare the input records, or a CSV, JSON, JSONL or NDJSON file that matches your workflow.
The response is a Job with operation: "workflows.run". Poll the Job until it finishes. A successful workflow Job’s result is a list of output files, not individual rows:
HTTP 200 (excerpt)

Download Workflow output

After polling, continue only when status is succeeded. Each file identifies its block with block_number. In a linear workflow, the highest block number is the last block; a branching workflow can have several output blocks. These examples download every CSV output to a separate local file. Both polling and downloading require your API key. Do not follow redirects when sending credentials.
To save other formats, send result_formats, such as ["csv", "ndjson"], when starting the Workflow run. Select the returned file with the content_type you need. Read the Job again to refresh expired download links. This download flow does not need /items or a separate export request. For batches run in the Workflow Editor, see Workflow Batches.
For the original bulk contact routes, see Legacy.