Skip to main content
POST
Upsert a customer

Authorizations

Authorization
string
header
required

Send your API key as Authorization: Bearer aw_live_…. Manage keys in the dashboard under Settings → API Keys.

Headers

Idempotency-Key
string

Opaque key that makes this POST safe to retry. Responses are cached for 24h per API key.

Maximum string length: 255

Body

application/json

At least one of external_id, email, or phone is required — it resolves (creates or updates) the customer.

external_id
string

Your own stable id for this customer. Strongest identity key.

email
string<email>
phone
string
name
string
custom_attributes
object

Org-defined attribute values, keyed by attribute key. Unknown keys are rejected.

Response

200 - application/json

Customer upserted

object
string
Allowed value: "customer"
id
string<uuid>
kind
enum<string>

lead = anonymous visitor; user = identified (has email / phone / external_id).

Available options:
lead,
user
external_id
string | null
email
string | null
name
string | null
phone
string | null
avatar_url
string | null
location
object
device
object
web_sessions
integer
first_seen_at
string<date-time>
last_seen_at
string<date-time>
signed_up_at
string<date-time> | null
last_conversation_at
string<date-time> | null
created_at
string<date-time>
custom_attributes
object

Org-defined attribute values, keyed by attribute key.