Skip to main content
POST
Execute an import

Authorizations

Authorization
string
header
required

Workspace API key, e.g. Authorization: Bearer tented_.... Create keys in Workspace Settings → API Keys.

Path Parameters

sessionId
string<uuid>
required

Import session ID from POST /v1/contacts/imports.

Body

application/json
mappings
object[]
required

Approved column mappings. Start from the preview's proposed_mappings and adjust as needed.

Minimum array length: 1
duplicate_strategy
enum<string>
default:update

What 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.

Available options:
update,
skip
overwrite_blank_only
boolean
default:false

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.

list_ids
string<uuid>[]

Static contact list IDs every imported contact is added to (max 500).

Maximum array length: 500
created_field_definition_ids
string<uuid>[]

IDs 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.

import_run_id
string<uuid>
required

ID of the queued import run. Poll GET /v1/contacts/imports/{importRunId} with it.

import_session_id
string<uuid>
required

The import session the run was created from.

status
enum<string>
required

Initial run status — always queued.

Available options:
queued
duplicate_strategy
enum<string>
required

The duplicate strategy the run will use.

Available options:
update,
skip
list_ids
string<uuid>[]
required

Static list IDs every imported contact will be added to.

total_rows
integer | null
required

Total data rows to process, or null if not yet counted (counted during preprocessing for upload-mode imports).

correlation_id
string
required

Correlation ID of the queued background job (useful when contacting support).