Upsert user
Users
Upsert user
POST /api/v1/users — identify or update a user.
POST
Upsert user
Upserts a user. Same call works for first-touch and updates — the backend deduplicates by
external_user_id.
Request
Body
Your primary key for the user. Stable across re-identifies.
Email address. Stored in a dedicated column for fast lookup and PII access control.
Trait bag. Known keys (
name, plan, signupDate, company, role) are stored in dedicated columns; any other key flows into the traits JSON column.Response
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
401 auth_required
401 auth_required
Missing or malformed
Authorization header.403 forbidden
403 forbidden
API key valid but not authorised for this resource.
422 validation_failed
422 validation_failed
Body failed schema validation;
errors[0].field indicates the offending field.429 rate_limited
429 rate_limited
Wait
Retry-After seconds.5xx server_error
5xx server_error
Retry — the
Idempotency-Key prevents duplicates.