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,
    "two_factor_enabled": true,
    "password_breached": 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"
  },
  "created": true
}

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

Contacts (API key)

Identify a contact

Server-side identity: create or update a contact from whatever identities the developer’s backend knows. At least one of external_id, email or anonymous_id is required.

Resolution order is external_id, then email — external_id is the developer’s own primary key and the stronger claim. When an anonymous_id arrives alongside an identifying kind, the visitor it belonged to is folded in, attribution and all. Everything runs in one transaction: an identify that half-merged a visitor would be worse than one that failed.

Answers 201 when the contact was created, 200 when it already existed. Send an Idempotency-Key if this call is retried by a client, a queue or a deploy: the retry then gets that same 201 back rather than the 200 the second call would otherwise produce.

POST

contacts

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,
    "two_factor_enabled": true,
    "password_breached": 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"
  },
  "created": true
}

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

Authorizations

Authorization

string

header

required

An organization API key, uk_sk_live_… or uk_sk_test_…. The environment is resolved from the stored key row on every request, never from a request parameter.

Every route behind this credential is rate limited per key — 1000 requests a minute — with a second ceiling of 3000 a minute across all the keys of one environment, so splitting your traffic across keys isolates it and minting more keys does not buy more of it. A test key can never spend a live key's allowance. Every response carries the current state in headers; see the rate-limits guide.

Headers

Idempotency-Key

string

A key you choose — a UUID, or your own identifier for the operation — that makes this write safe to retry. Send the same key again and you get the same response back: the same status, the same body, and Idempotent-Replay: true. The handler does not run a second time.

The key is scoped to your API key and the route, so keys never collide between environments or tenants. It is remembered for 24 hours. Reusing it for a different request is refused (422), and a second request arriving while the first is still running is refused too (409) — retry that one in a moment.

A request that failed with a 5xx or was rate limited leaves the key spendable: retry it with the same key.

Maximum string length: 255

Body

application/json

external_id

string

The developer's own primary key for this person.

string<email>

anonymous_id

string

The device id captured before this person was known.

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

Response

The contact already existed and was updated.

contact

object

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

Show child attributes

created

boolean

List contacts Read a contact

⌘I

Overview

Endpoints

Identify a contact

Authorizations

Headers

Body

Response