Error

A valid request URL is required to generate request examples

{
  "contact": {
    "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "name": "<string>",
    "email": "<string>",
    "avatar_url": "<string>",
    "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",
  "verified": true
}

{
  "contact": {
    "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "name": "<string>",
    "email": "<string>",
    "avatar_url": "<string>",
    "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",
  "verified": true
}

{
  "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"
  }
}

{
  "error": {
    "code": "forbidden",
    "message": "your role does not allow this action"
  }
}

Customer plane

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.

POST

boot

Error

A valid request URL is required to generate request examples

{
  "contact": {
    "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "name": "<string>",
    "email": "<string>",
    "avatar_url": "<string>",
    "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",
  "verified": true
}

{
  "contact": {
    "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "name": "<string>",
    "email": "<string>",
    "avatar_url": "<string>",
    "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",
  "verified": true
}

{
  "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"
  }
}

{
  "error": {
    "code": "forbidden",
    "message": "your role does not allow this action"
  }
}

Corpo

application/json

publishable_key

string

obrigatório

uk_pk_live_… or uk_pk_test_….

anonymous_id

string

Required unless external_id is present.

name

string

attribution

object

First touch, captured on the visitor at first load and preserved through a merge. All fields optional; empty means unknown.

Show child attributes

external_id

string

Federated mode only.

string<email>

Stored as an attribute. Never an identity edge on this route.

hash

string

hex(HMAC-SHA256(identity_secret, external_id)). Computed on the developer's server, never in the browser.

Resposta

The contact already existed.

contact

object

One of the developer's own users — anonymous or identified.

Show child attributes

token

string

Contact session token, uk_ct_….

expires_at

string<date-time>

environment

enum<string>

The publishable key's environment.

Opções disponíveis:

live,

test

verified

boolean

True only when a valid HMAC hash proved the external_id.

Read a contact Fetch an environment's public keys

⌘I

Visão geral

Endpoints

Boot the widget

Corpo

Resposta