Skip to main content
POST
Start a contact import

Authorizations

Authorization
string
header
required

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

Body

application/json
source
enum<string>
required

Import mode: upload a CSV file via a presigned URL.

Available options:
upload
file_name
string
default:contacts.csv

File name to associate with the import (shown in run details and used to name the results export).

Required string length: 1 - 255
content_type
string
default:text/csv

Content type of the upcoming upload. Must be one of text/csv, application/csv, application/vnd.ms-excel, or text/plain; anything else is rejected with 400. The presigned URL is bound to this content type — send the same Content-Type header on the PUT.

Required string length: 1 - 255

Response

Import session created. upload mode returns a presigned upload URL; rows mode returns the stored row count.

import_session_id
string<uuid>
required

Import session ID. Use it for the preview and execute calls.

file_name
string
required

File name associated with the import.

upload_url
string
required

Presigned S3 PUT URL. Upload the raw CSV bytes here (no auth header needed — the URL is self-authorizing).

upload_headers
object
required

Headers to send with the PUT (currently the Content-Type the URL was signed for).

expires_in_seconds
integer
required

Seconds until upload_url expires (900 = 15 minutes).