A valid request URL is required to generate request examples{
"contact": {
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"name": "<string>",
"email": "<string>",
"avatar_url": "<string>",
"locale": "en",
"identified": true,
"email_verified": true,
"attribution": {
"utm_source": "<string>",
"utm_medium": "<string>",
"utm_campaign": "<string>",
"utm_term": "<string>",
"utm_content": "<string>",
"referrer": "<string>",
"landing_page": "<string>"
},
"first_seen_at": "2023-11-07T05:31:56Z",
"last_seen_at": "2023-11-07T05:31:56Z",
"created_at": "2023-11-07T05:31:56Z"
},
"token": "<string>",
"expires_at": "2023-11-07T05:31:56Z",
"environment": "live",
"verified": true,
"flags": {}
}{
"contact": {
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"name": "<string>",
"email": "<string>",
"avatar_url": "<string>",
"locale": "en",
"identified": true,
"email_verified": true,
"attribution": {
"utm_source": "<string>",
"utm_medium": "<string>",
"utm_campaign": "<string>",
"utm_term": "<string>",
"utm_content": "<string>",
"referrer": "<string>",
"landing_page": "<string>"
},
"first_seen_at": "2023-11-07T05:31:56Z",
"last_seen_at": "2023-11-07T05:31:56Z",
"created_at": "2023-11-07T05:31:56Z"
},
"token": "<string>",
"expires_at": "2023-11-07T05:31:56Z",
"environment": "live",
"verified": true,
"flags": {}
}{
"error": {
"code": "forbidden",
"message": "your role does not allow this action"
}
}{
"error": {
"code": "forbidden",
"message": "your role does not allow this action"
}
}{
"error": {
"code": "forbidden",
"message": "your role does not allow this action"
}
}{
"error": {
"code": "forbidden",
"message": "your role does not allow this action"
}
}{
"error": {
"code": "forbidden",
"message": "your role does not allow this action"
}
}Boot the widget
The widget’s first call, from the developer’s own page. Two shapes share it.
Anonymous — a publishable key and the device’s anonymous_id go in; a visitor contact and an unverified session come back. First touch (UTMs, referrer, landing page) is captured here, on the anonymous contact, which is where attribution is born.
Federated — external_id alongside, optionally email and the HMAC hash. The hash proves the external_id and nothing else: an email arriving by boot is stored as an attribute and never resolves to or merges with an existing contact, because anyone can type an email and only a magic link proves one.
A valid hash makes the session verified. An absent hash leaves it unverified — usable in development, marked in the panel, barred from anything another person’s data could leak through. A wrong hash is refused outright, never downgraded, so a typo in the developer’s HMAC code cannot be invisible.
Rate limited to 240 requests per minute per IP, and 240 per minute per publishable key.
A valid request URL is required to generate request examples{
"contact": {
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"name": "<string>",
"email": "<string>",
"avatar_url": "<string>",
"locale": "en",
"identified": true,
"email_verified": true,
"attribution": {
"utm_source": "<string>",
"utm_medium": "<string>",
"utm_campaign": "<string>",
"utm_term": "<string>",
"utm_content": "<string>",
"referrer": "<string>",
"landing_page": "<string>"
},
"first_seen_at": "2023-11-07T05:31:56Z",
"last_seen_at": "2023-11-07T05:31:56Z",
"created_at": "2023-11-07T05:31:56Z"
},
"token": "<string>",
"expires_at": "2023-11-07T05:31:56Z",
"environment": "live",
"verified": true,
"flags": {}
}{
"contact": {
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"name": "<string>",
"email": "<string>",
"avatar_url": "<string>",
"locale": "en",
"identified": true,
"email_verified": true,
"attribution": {
"utm_source": "<string>",
"utm_medium": "<string>",
"utm_campaign": "<string>",
"utm_term": "<string>",
"utm_content": "<string>",
"referrer": "<string>",
"landing_page": "<string>"
},
"first_seen_at": "2023-11-07T05:31:56Z",
"last_seen_at": "2023-11-07T05:31:56Z",
"created_at": "2023-11-07T05:31:56Z"
},
"token": "<string>",
"expires_at": "2023-11-07T05:31:56Z",
"environment": "live",
"verified": true,
"flags": {}
}{
"error": {
"code": "forbidden",
"message": "your role does not allow this action"
}
}{
"error": {
"code": "forbidden",
"message": "your role does not allow this action"
}
}{
"error": {
"code": "forbidden",
"message": "your role does not allow this action"
}
}{
"error": {
"code": "forbidden",
"message": "your role does not allow this action"
}
}{
"error": {
"code": "forbidden",
"message": "your role does not allow this action"
}
}Body
uk_pk_live_… or uk_pk_test_….
Required unless external_id is present.
The language this person reads, as a BCP 47 tag (pt-BR, en). Sent when your page knows it — navigator.language is the usual source. Omitting it is not a claim: the environment's default_locale answers instead, and a tag this platform does not render falls through the same way. Never overwrites what is already on a contact this call did not create.
"en"
First touch, captured on the visitor at first load and preserved through a merge. All fields optional; empty means unknown.
Show child attributes
Show child attributes
Your own user id for this person. Proven by hash; without one the session is minted unverified.
Stored as an attribute. Never an identity edge on this route.
hex(HMAC-SHA256(identity_secret, external_id)). Computed on the developer's server, never in the browser.
Response
The contact already existed.
One of the developer's own users — anonymous or identified.
Show child attributes
Show child attributes
Contact session token, uk_ct_….
The publishable key's environment.
live, test True only when a valid HMAC hash proved the external_id.
The feature flags evaluated for this contact at the mint, keyed by flag key — the first read the page would otherwise make. Present when the environment has flags.