> ## Documentation Index
> Fetch the complete documentation index at: https://docs.emailx.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Import People from CSV or XLSX

> Preview a bounded CSV or XLSX file with an explicit field mapping, then confirm an import and inspect paginated row outcomes without enrolling contacts in a campaign.

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](https://docs.emailx.ai/en/api-reference/coverage.md), [API request limits](https://docs.emailx.ai/en/api-reference/rate-limits.md), and [idempotency and recovery](https://docs.emailx.ai/en/api-reference/idempotency.md).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.