Skip to main content
POST
Upsert user
Upserts a user. Same call works for first-touch and updates — the backend deduplicates by external_user_id.

Request

Body

external_user_id
string
required
Your primary key for the user. Stable across re-identifies.
email
string
Email address. Stored in a dedicated column for fast lookup and PII access control.
traits
object
Trait bag. Known keys (name, plan, signupDate, company, role) are stored in dedicated columns; any other key flows into the traits JSON column.

Response

data.accepted
boolean
Always true on success. The upsert is enqueued and processed asynchronously — downstream views (audiences, etc.) reflect the new state within a few hundred milliseconds.

Examples

Common errors

Missing or malformed Authorization header.
API key valid but not authorised for this resource.
Body failed schema validation; errors[0].field indicates the offending field.
Wait Retry-After seconds.
Retry — the Idempotency-Key prevents duplicates.