Start a contact import
Create a contact import session. Two modes, selected by source:
upload— returns a presigned S3PUTURL. Upload the raw CSV bytes toupload_urlwith the returnedupload_headersbefore the URL expires (expires_in_seconds, 15 minutes). Source files up to 350 MB are supported. Only CSV content types are accepted (text/csv,application/csv,application/vnd.ms-excel,text/plain).rows— send rows inline as JSON objects (1–1,000 rows). Keys are column headers; the union of keys across all rows becomes the CSV header row. Values are stringified;nullbecomes an empty string. Inline request bodies are limited to 5 MB — larger bodies are rejected with413(this keeps requests below the platform’s 6 MB payload ceiling, so treat ~5 MB as the practical limit and useuploadmode for anything bigger).
After creating a session, call POST /v1/contacts/imports/{sessionId}/preview to get proposed column mappings, then POST /v1/contacts/imports/{sessionId}/execute to run the import. Sessions expire after 7 days and can each be executed once.
Authorizations
Workspace API key, e.g. Authorization: Bearer tented_.... Create keys in Workspace Settings → API Keys.
Body
- Upload mode
- Inline rows mode
Import mode: upload a CSV file via a presigned URL.
upload File name to associate with the import (shown in run details and used to name the results export).
1 - 255Content 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.
1 - 255Response
Import session created. upload mode returns a presigned upload URL; rows mode returns the stored row count.
- Upload session
- Rows session
Import session ID. Use it for the preview and execute calls.
File name associated with the import.
Presigned S3 PUT URL. Upload the raw CSV bytes here (no auth header needed — the URL is self-authorizing).
Headers to send with the PUT (currently the Content-Type the URL was signed for).
Seconds until upload_url expires (900 = 15 minutes).