Execute an import
Approve the final column mappings and start the import. The import runs asynchronously in chunks — this endpoint returns 202 with an import_run_id; poll GET /v1/contacts/imports/{importRunId} until status is completed or failed.
Every mapping’s header must be a column from the session’s CSV. Map a column to null (target_field: null, target_kind: null) to skip it. At least one column must map to the email or phone standard field — contacts are matched (deduplicated) by normalized email or phone.
Each session can be executed once: re-executing a session whose latest run is queued, running, or completed returns 400. A session whose only runs failed can be executed again.
Authorizations
Workspace API key, e.g. Authorization: Bearer tented_.... Create keys in Workspace Settings → API Keys.
Path Parameters
Import session ID from POST /v1/contacts/imports.
Body
Approved column mappings. Start from the preview's proposed_mappings and adjust as needed.
1What to do when a row matches an existing contact (by normalized email or phone): update merges the mapped values into the existing contact; skip leaves the existing contact untouched and counts the row as skipped.
update, skip When true, imported values only fill fields that are currently empty on the matched contact (the default overwrite_behavior for every mapping becomes skip_if_filled). Per-mapping overwrite_behavior overrides this default.
Static contact list IDs every imported contact is added to (max 500).
500IDs of custom fields you bulk-created for this import (from the preview's field_creation_candidates). Each ID must reference a field created via POST /v1/contact-fields against this same import session — unrelated fields are rejected with 400.
Response
Import accepted and queued. Poll GET /v1/contacts/imports/{importRunId} for progress.
Acknowledgement that an import run was queued.
ID of the queued import run. Poll GET /v1/contacts/imports/{importRunId} with it.
The import session the run was created from.
Initial run status — always queued.
queued The duplicate strategy the run will use.
update, skip Static list IDs every imported contact will be added to.
Total data rows to process, or null if not yet counted (counted during preprocessing for upload-mode imports).
Correlation ID of the queued background job (useful when contacting support).