Skip to main content
POST
Create or update contacts in bulk

Authorizations

Authorization
string
header
required

A workspace API token (sk_live_...) or an OAuth access token (oat_live_...). Create workspace tokens in Settings > API. Send either as Authorization: Bearer <token>.

Headers

Idempotency-Key
string

A unique value (a UUID works) that makes retrying this request safe. A repeat with the same key and body within 24 hours returns the original response instead of acting twice; the same key with a different body is a 409 idempotency_key_reused.

Maximum string length: 255

Query Parameters

expand
string | null

Comma-separated relationships to inline in the response, e.g. organization. Unexpanded relations are still identified by their *_id field.

Example:

"organization"

Body

application/json

Body for POST /v1/contacts/batch.

items
ContactUpsert · object[]
required

Up to 100 contacts, each matched and written exactly like POST /v1/contacts/upsert.

Required array length: 1 - 100 elements

Response

Successful Response

One result per item, in request order.

created
integer
required
data
ContactBatchItemResult · object[]
required
failed
integer
required
updated
integer
required
object
string
default:batch_result
Allowed value: "batch_result"