This is the documentation for our ingestion API's which are used by our client SDKs. They can be used to create additional clients or ingest data without a secret key.

Authentication#

Authentication to client endpoints is handled via public bearer API keys. These API keys allow for ingestion only of data and only on select endpoints. You can generate a new public key at any time in the portal and we recommend using a separate key per platform.

To authenticate requests, set the Authorization header to be Bearer YOUR_KEY where YOUR_KEY is the API key you generated.

Example#

{
    "Authorization": "Bearer pk_dbf68c87-e579-4dac-b083-77fed0294e67"
}

Endpoints#

Alias User#

Merge a previous identifier to the users new identifier. This action can only be performed once.

Endpoint#

POST/client/alias

Body#

anonymous_id string
external_id string

Responses#

204 - Success
422 - Validation error

Example#

Endpoint: POST /client/alias

Headers: {
    "Authorization": "Bearer pk_token_here"
}

Body: {
    "anonymous_id": "ANONYMOUS_ID",
    "external_id": "EXTERNAL_ID"
}

Identify User#

Create or update a user profile with associated traits.

Endpoint#

POST/client/identify

Body#

anonymous_id string (optional)
external_id string
email string (optional)
phone string (optional)
timezone string (optional)
locale string (optional)
data object (optional)

Responses#

204 - Success
422 - Validation error

Example#

Endpoint: POST /client/identify

Headers: {
    "Authorization": "Bearer pk_token_here"
}

Body: {
    "external_id": "EXTERNAL_ID",
    "email": "[email protected]",
    "timezone": "America/Chicago",
    "locale": "en",
    "data": {
        "first_name": "John",
        "last_name": "Smith",
        "has_completed_onboarding": true
    }
}

Register Device#

Ingest information about the users device including the push notification token used for sending push notifications.

Endpoint#

POST/devices

Body#

anonymous_id string
external_id string
device_id string - A UUID or other identifier that can be used to identify this device across requests
token string - The push notification token for that device
os string
model string
app_build string - i.e. 465
app_version string - i.e. 1.2.4

Responses#

204 - Success
422 - Validation error

Example#

Endpoint: POST /client/devices

Headers: {
    "Authorization": "Bearer pk_token_here"
}

Body: {
    "external_id": "EXTERNAL_ID",
    "device_id": "5e356e66-03aa-4926-a322-d7f5c89049c1",
    "token": "45d2e0c7bbb649679723a96d92d0fa305e356e6603aa4926a322d7f5c89",
    "os": "iOS 16.3",
    "model": "iPhone15,2",
    "app_build": "465",
    "app_version": "1.2.4"
}

Post Event#

Track and event or interaction.

Endpoint#

POST/events

Body#

An array containing at least one object with the following parameters:

name string (optional) - The name of the event
anonymous_id string
external_id string
data object (optional)

Either an anonymous or external ID is required in order to post an event.

Responses#

204 - Success
422 - Validation error

Example#

Endpoint: POST /client/events

Headers: {
    "Authorization": "Bearer pk_token_here"
}

Body: [{
    "external_id": "EXTERNAL_ID",
    "name": "Product Purchased",
    "data": {
        "product_id": 12345,
        "price": 49.99,
        "quantity": 4
    }
}]