Importing contacts
'import_contacts' bulk-imports contacts from JSON, raw CSV text, a CSV URL, or a stored file. Every contact needs a LinkedIn URL, that is the dedupe key.
Input options
- contacts: a JSON array of contact objects, up to 1,000 per call
- csv_content: raw CSV or TSV text, headers parsed automatically, no row limit
- csv_url: an HTTPS URL to a CSV or TSV file, fetched server-side with no size limit. Works with signed storage URLs and Google Sheets export URLs.
- storage_path: a path inside the imports storage bucket
Field names are auto-mapped from common conventions (camelCase, snake_case, Title Case), so an export from another outreach tool usually imports without renaming columns. Set source (e.g. 'csv', 'heyreach', 'expandi') to track where contacts came from.
Duplicates
Contacts are deduplicated by LinkedIn URL. Control what happens on a match with merge_strategy:
- 'merge' (default): tags are unioned, custom attributes deep-merged
- 'replace': the new row overwrites the existing contact
- 'skip': duplicates are left untouched
Every skipped row comes back in a skipped array with a reason (missing LinkedIn URL, duplicate within the batch, duplicate existing contact, invalid URL), so nothing disappears silently.
Importing into a list
Pass list_id and imported contacts are added to that list automatically. The response includes list_size, the total count in the list after the import.
Previewing first
Set preview to true to project the import without persisting anything. You get would_import, would_merge, would_replace, and would_skip counts plus a confirm_token. Re-run the call with that token to commit exactly what you previewed.