Start a background contact import from a CSV/Excel file
POST/api/contacts/import
Header-mapped import: columns are matched by field key (first_name, last_name, email, phone, type + custom-field keys). The upload is parked and a queued job streams it (up to 50,000 rows), so large lists never block the request. Imported contacts are saved to the Contacts list; rows with a duplicate email/phone or no identity are skipped. Poll the returned import run for progress. Requires the contacts-manage permission.
Import-time options from the preview step ride along: tag_ids are
applied to EVERY row of the file (rows that matched an existing
contact included), and fields promotes unknown columns into new
contact custom fields before processing (requires
contact_fields.manage). Both decisions are persisted on the run as
its audit trail.
Request
Responses
- 202
- 401
- 403
- 422
The queued import run.
Not authenticated. code: account_disabled means the member's seat was deactivated in this workspace: the session is over even though the token was not revoked (clients sign out and clean up).
Authenticated but not allowed.
The request failed validation.