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

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

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

Contacts (server)

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.

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

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.

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

Body

Response