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. Each field can be the target of only one column; mapping two columns to the same field returns 400. 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.

POST /v1/contacts/imports/{sessionId}/execute

Execute an import

cURL

curl --request POST \
  --url https://api.tented.ai/v1/contacts/imports/{sessionId}/execute \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "mappings": [
    {
      "header": "<string>",
      "target_field": "<string>"
    }
  ],
  "duplicate_strategy": "update",
  "overwrite_blank_only": false,
  "list_ids": [
    "3c90c3cc-0d44-4b50-8888-8dd25736052a"
  ],
  "created_field_definition_ids": [
    "3c90c3cc-0d44-4b50-8888-8dd25736052a"
  ]
}
'

202

{
  "import_run_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "import_session_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "status": "queued",
  "duplicate_strategy": "update",
  "list_ids": [
    "3c90c3cc-0d44-4b50-8888-8dd25736052a"
  ],
  "total_rows": 123,
  "correlation_id": "<string>"
}

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

Show child attributes

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

202

application/json

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