Skip to main content
People import creates or reuses workspace contacts from a file after you inspect a read-only preview. It does not enroll contacts in campaigns, generate messages, or start outreach. Use a matching 0.8.0 API host, check workspace capabilities, and treat 503 feature_unavailable as unavailable on that host. Host availability is not guaranteed.

​
Preview before writing

Choose email or linkedin, map each supported contact field to an exact file header, and send the file to POST /workspaces/{workspace_id}/contacts/imports/preview. Preview requires contacts:read; it does not write contacts and works while import execution is disabled. Review row outcomes, blockers, totals, and the returned fingerprint. Files are limited to 64 KiB after base64 decoding and 1,000 data rows. The HTTP body limit is 256 KiB. Durable operation commands are limited to 128 KiB for People import and 64 KiB for other commands. CSV and XLSX are supported; other file formats are not.

​
Confirm the exact preview

Only after reviewing the preview, submit the same file and mapping with its exact expected_fingerprint and confirm_import: true to POST /contacts/imports. This requires contacts:write and an idempotency key, and returns 202 with an operation ID. If the source file, mapping, channel, or matching contact/suppression state changes, preview again and use the new fingerprint. A row can reuse an eligible matching contact or create a new one. Existing identity fields are not overwritten and suppressed contacts are blocked. LinkedIn-only rows can create canonical contacts without email. The direct legacy create-contact endpoint still requires an email address. Provider lookups are not performed by this People import.

​
Poll and inspect outcomes

Read the operation with operations:read and contacts:read. Then request /contacts/imports/{operation_id}/rows with contacts:read and operations:read; use offset and limit to page through bounded outcomes and contact IDs. The result does not return the uploaded file. Stop polling at awaiting_user_action, needs_reconciliation, or a terminal state. On a timeout or unknown outcome, read the original operation and inspect row results; never automatically enqueue a second import. Resolve any known issue and preview again before starting a new logical import. Import completion only saves contacts. Add them to a campaign in a separate, explicitly reviewed workflow. See API coverage, API request limits, and idempotency and recovery.