Look up contacts from a file
- Save your records as CSV, JSON, JSONL or NDJSON.
- Upload the file to get a
file_id. - Start a Job with
input_file_id. - Poll the Job and read its items.
- Export the results and download the file.
Prepare the input records
Save this aspeople.csv:
custom_id to match each result to your records. Files support up to 100,000 rows.
Upload and start
ReplaceYOUR_API_KEY with your API key. Python uses requests; cURL uses jq; JavaScript uses Node.js 18 or later.
HTTP 200 (excerpt)
Check the Job
Continue with the Job from the start request:Read the items
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 asfrom.job_id.
Research records from a file
UsePOST /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
Usepeople 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.
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 whenstatus 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.
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.
Related
For the original bulk contact routes, see Legacy.