Data Pipelines API

Download OpenAPI specification:Download

This is a reference for the Data Pipelines API. In general, you'll consume this API through one of our source libraries—our JavaScript client library or any of our server packages. But you can also integrate directly with our REST API if you don't want to install one of our libraries or you want to support a source that we don't have a native integration with.

All endpoints begin with: https://cdp.customer.io/v1

You're looking at our US regional endpoints

The only difference in our US and European Union (EU) regions is the subdomain—e.g. cdp-eu for the EU region; there are no other differences between the two regions. If your account is based in the European Union (EU) data center, click here to show EU endpoints in our code samples and documentation below.

If you don't know your region, you can find your account region on your account's privacy page, or get your region using the API.

You're looking at our EU regional endpoints

The only difference in our US and European Union (EU) regions is the subdomain—e.g. cdp for our US region rather than cdp-eu for the EU; there are no other differences between the two regions. If your account is based in the European Union (EU) data center, you can click here to to show US endpoints in our code samples and documentation below.

If you don't know your region, you can find your account region on your account's privacy page, or get your region using the API.

API region

We host services in the United States (US) and European Union (EU, host subdomains are suffixed with -eu). Select the appropriate region for server addresses that apply to your region.

If you're in our EU region, you'll need to specify the EU URL when you initialize our server-side libraries. If you use our JavaScript client library, we'll set your region and route data/calls automatically.

Set up a REST API source

After you add a Rest API source, you'll use endpoints at https://cdp.customer.io/v1/{method}

  1. Go to the tab and click Sources.
  2. Click Add Source, pick HTTP, and click Next.
  3. Give the source a Name and copy your API Key. You'll use this key to authenticate with our API. If you don't copy the key now, you can always get it later from the Settings tab when you're done setting up your source.
  4. (Optional) Test your connection by sending a test call. You can copy your API key into an app like Postman or send a CURL request. If your request is successful, and then you click Test Connection we'll let you know if your request was successful and you've set up your HTTP implementation successfully.
  5. Click Submit.

Now you can connect your REST API source to destinations.

Try out our postman collection

We've generated a Postman collection with all of the endpoints organized as you'll find them on this page, with a starter environment (mainly to contain your API key). For our API endpoints, your API key is your username and your password is blank.

You'll notice that payloads on this page can contain significantly more information than the payloads that appear in our collection. We've limited our collections to the fields that you'll typically use when you send calls to our APIs and libraries, so it's easier to get started. But you can add additional fields to payloads—like context, integrations, and so on—if you want.

If you fork this collection, you might want to disable the Watch original collection option. We automatically update our Postman collection whenever we release changes to our documentation, even if we don't change our APIs—which happens daily! Rather than being flooded with Postman notifications, you can check out our Release Notes for updates to our APIs.

Authentication

Our API uses basic authorization with an API Key provided when you set up a source. If you use Postman or another platform that helps you send API calls, this API key is the Username, and the Password is blank.

Our sources are all authenticated using a API Key that we generate when you create a source.

Basic Auth

The Data Pipelines API uses a basic authentication scheme with your API key. Because basic authorization typically expects a username and password combination, you'll use the API Key as the username and leave the password blank—base64 encoding your credentials in the format API_key:.

Security Scheme Type HTTP
HTTP Authorization Scheme basic

API limits

A request is limited to 32KB. A batch request is limited to 500KB total and 32KB per call in the request. If a request exceeds these limits, you will receive a 200 response, but the request will not go through.

Backfilling data

By default, Customer.io records a timestamp when we receive requests. If you're sending data to Customer.io in real time, you don't need to worry about the timestamp.

If you want to backfill requests, you can send a timestamp—an ISO 8601 date-time string—telling us when the request occurred. This provides a way to log track and page calls when the activities actually took place.

Schemas

You only need to populate a few fields when you send data to Customer.io. Our JavaScript client and server libraries populate additional information for each call, which you'll see when you look at individual events in Customer.io.

The information below shows the complete list of information reported to Customer.io with each event.

See the endpoints below this section for the much smaller list of fields you'll actually set when you invoke methods in our client and server-side libraries.

Identify Schema

When you send an identify call, you'll typically include a userId and traits. Most other fields are populated by Customer.io—either by a source library or our servers.

If you provide an anonymousId, we'll attribute traits to an anonymous user. If you provide both an anonymousId and userId, we'll associate anonymous activity to the userId.

Traits are the same as Attributes in Customer.io. If Customer.io Messaging is your destination, you'll see that traits map 1-to-1 with attributes. But not all systems call the things you know about people traits or attributes. You'll need to check with your destination to understand what your destination calls people-data!

One of
userId
required
string

The unique identifier for a person. This value should be unique across systems, so you recognize the same person in your sources and destinations.

anonymousId
string

A unique substitute for a User ID in cases when you don’t have an absolutely unique identifier. Our libraries generate this value automatically to help you track people before they sign up, log in, provide their email, etc.

type
string
Value: "identify"

The event type. This is set automatically by the request method/endpoint.

object

Additional properties that you know about a person. We've listed some common/reserved traits below, but you can add any traits that you might use in another system.

object

Contains a list of booleans indicating the integrations that are enabled (true) or disabled (false). By default, all integrations are enabled (returning an empty object). Set "All": false to reverse this behavior.

messageId
string

A unique identifier for a Data Pipelines call, ensuring that each individual event is unique. This is set by Customer.io

receivedAt
string <date-time>

The ISO-8601 timestamp when Data Pipelines receives an event.

sentAt
string <date-time>

The ISO-8601 timestamp when a library sends an event to Data Pipelines.

originalTimestamp
string <date-time>

In general, you can use timestamp rather than this field if you want to back-date events. This is the timestamp on the client device you invoke a call or the timestamp value you manually passed in a server-side library call.

timestamp
string <date-time>

The ISO-8601 timestamp when the event originally took place. This is mostly useful when you backfill past events. If you're not backfilling data, you can leave this field empty and we'll use the current time or server time.

version
number

The version of the API that received the event, automatically set by Customer.io.

object

A dictionary of context about a source call/event, like the user’s IP address or locale. Context is automatically collected by our source libraries.

Example
{
  • "userId": "97980cfea0067",
  • "anonymousId": "c0e5cae6-6f04-46e4-97a8-25076e8bdc0b",
  • "type": "identify",
  • "traits": {
    • "email": "cool.person@example.com",
    • "createdAt": "2019-08-24T14:15:22Z",
    • "Additional Traits1": null,
    • "Additional Traits2": null,
    • "name": "Cool Person",
    • "likes_baseball": true,
    • "games_attended": 5
    },
  • "integrations": {
    • "All": true,
    • "Salesforce": false
    },
  • "messageId": "string",
  • "receivedAt": "2019-08-24T14:15:22Z",
  • "sentAt": "2019-08-24T14:15:22Z",
  • "originalTimestamp": "2019-08-24T14:15:22Z",
  • "timestamp": "2019-08-24T14:15:22Z",
  • "version": 0,
  • "context": {
    • "active": true,
    • "ip": "string",
    • "locale": "string",
    • "userAgent": "string",
    • "channel": "browser",
    • "campaign": {
      },
    • "page": {
      }
    }
}

Track Schema

When you send a track call, you'll typically include the event name and additional properties you want to track. You can provide either an anonymousId or a userId. If you provide both, we attribute the activity to the userId and ignore the anonymousId.

Most other fields are populated by Customer.io—either by a source library or our servers.

One of
userId
required
string

The unique identifier for a person. This value should be unique across systems, so you recognize the same person in your sources and destinations.

event
required
string

The name of the event

type
required
string
Value: "track"

The event type. This is set automatically by the request method/endpoint.

object

Additional properties for your event.

object

Contains a list of booleans indicating the integrations that are enabled (true) or disabled (false). By default, all integrations are enabled (returning an empty object). Set "All": false to reverse this behavior.

messageId
string

A unique identifier for a Data Pipelines call, ensuring that each individual event is unique. This is set by Customer.io

receivedAt
string <date-time>

The ISO-8601 timestamp when Data Pipelines receives an event.

sentAt
string <date-time>

The ISO-8601 timestamp when a library sends an event to Data Pipelines.

originalTimestamp
string <date-time>

In general, you can use timestamp rather than this field if you want to back-date events. This is the timestamp on the client device you invoke a call or the timestamp value you manually passed in a server-side library call.

timestamp
string <date-time>

The ISO-8601 timestamp when the event originally took place. This is mostly useful when you backfill past events. If you're not backfilling data, you can leave this field empty and we'll use the current time or server time.

version
number

The version of the API that received the event, automatically set by Customer.io.

object

A dictionary of context about a source call/event, like the user’s IP address or locale. Context is automatically collected by our source libraries.

Example
{
  • "userId": "AiUGstSDIg",
  • "type": "track",
  • "event": "Course Started",
  • "properties": {
    • "Event Properties1": null,
    • "Event Properties2": null,
    • "title": "Intro to Customer.io"
    },
  • "integrations": null,
  • "messageId": "ajs-f8ca1e4de5024d9430b3928bd8ac6b96",
  • "receivedAt": "2015-12-12T19:11:01.266Z",
  • "sentAt": "2015-12-12T19:11:01.169Z",
  • "originalTimestamp": "2015-12-12T19:11:01.152Z",
  • "timestamp": "2015-12-12T19:11:01.249Z",
  • "version": 0,
  • "context": {
    • "active": true,
    • "ip": "108.0.78.21",
    • "locale": "string",
    • "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_11_0) AppleWebKit/537.36 (KHTML like Gecko) Chrome/46.0.2490.86 Safari/537.36",
    • "channel": "browser",
    • "campaign": {
      },
    • "page": {},
    • "library": {
      }
    },
  • "anonymousId": "23adfd82-aa0f-45a7-a756-24f2a7a4c895"
}

Page Schema

A page call represents a pageview.

Page events are automatically sent whenever you load our JavaScript library, which is typically every page. Customer.io automatically gathers the page name and URL, but you can pass additional properties, like the category.

Most other fields are populated by Customer.io—either by a source library or our servers.

One of
userId
required
string

The unique identifier for a person. This value should be unique across systems, so you recognize the same person in your sources and destinations.

type
string
Value: "page"

The event type. This is set automatically by the request method/endpoint.

name
string

The name of the page.

object

Additional page properties. Analytics.js automatically collects url, title, referrer, path, and search properties. But, if you use our other sources or you write your own integration, you should consider sending these properties yourself. Destination actions that take page events often rely on the url and title properties.

object

Contains a list of booleans indicating the integrations that are enabled (true) or disabled (false). By default, all integrations are enabled (returning an empty object). Set "All": false to reverse this behavior.

messageId
string

A unique identifier for a Data Pipelines call, ensuring that each individual event is unique. This is set by Customer.io

receivedAt
string <date-time>

The ISO-8601 timestamp when Data Pipelines receives an event.

sentAt
string <date-time>

The ISO-8601 timestamp when a library sends an event to Data Pipelines.

originalTimestamp
string <date-time>

In general, you can use timestamp rather than this field if you want to back-date events. This is the timestamp on the client device you invoke a call or the timestamp value you manually passed in a server-side library call.

timestamp
string <date-time>

The ISO-8601 timestamp when the event originally took place. This is mostly useful when you backfill past events. If you're not backfilling data, you can leave this field empty and we'll use the current time or server time.

version
number

The version of the API that received the event, automatically set by Customer.io.

object

A dictionary of context about a source call/event, like the user’s IP address or locale. Context is automatically collected by our source libraries.

Example
{
  • "userId": "97980cfea0067",
  • "type": "page",
  • "name": "Home",
  • "properties": {},
  • "integrations": {
    • "All": true,
    • "Salesforce": false,
    • "Mixpanel": false
    },
  • "messageId": "022bb90c-bbac-11e4-8dfc-aa07a5b093db",
  • "receivedAt": "2015-02-23T22:28:55.387Z",
  • "sentAt": "2015-02-23T22:28:55.111Z",
  • "originalTimestamp": "2019-08-24T14:15:22Z",
  • "timestamp": "2015-02-23T22:28:55.111Z",
  • "version": 1.1,
  • "context": {
    • "active": true,
    • "ip": "8.8.8.8",
    • "locale": "string",
    • "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_9_5) AppleWebKit/537.36 (KHTML like Gecko) Chrome/40.0.2214.115 Safari/537.36",
    • "channel": "browser",
    • "campaign": {
      },
    • "page": {
      }
    },
  • "anonymousId": "507f191e810c19729de860ea",
  • "channel": "browser"
}

Screen Schema

A scren call indicates that someone went to a screen in your mobile app.

We don't have mobile libraries supporting the screen method just yet, but we'll still accept calls with type: "screen" if you want to set up your own calls.

One of
userId
required
string

The unique identifier for a person. This value should be unique across systems, so you recognize the same person in your sources and destinations.

type
string
Value: "screen"

The event type. This is set automatically by the request method/endpoint.

name
string

The name of the screen the person visited.

object

Additional properties for your screen.

object

Contains a list of booleans indicating the integrations that are enabled (true) or disabled (false). By default, all integrations are enabled (returning an empty object). Set "All": false to reverse this behavior.

messageId
string

A unique identifier for a Data Pipelines call, ensuring that each individual event is unique. This is set by Customer.io

receivedAt
string <date-time>

The ISO-8601 timestamp when Data Pipelines receives an event.

sentAt
string <date-time>

The ISO-8601 timestamp when a library sends an event to Data Pipelines.

originalTimestamp
string <date-time>

In general, you can use timestamp rather than this field if you want to back-date events. This is the timestamp on the client device you invoke a call or the timestamp value you manually passed in a server-side library call.

timestamp
string <date-time>

The ISO-8601 timestamp when the event originally took place. This is mostly useful when you backfill past events. If you're not backfilling data, you can leave this field empty and we'll use the current time or server time.

version
number

The version of the API that received the event, automatically set by Customer.io.

object

A dictionary of context about a source call/event, like the user’s IP address or locale. Context is automatically collected by our source libraries.

Example
{
  • "userId": "97980cfea0067",
  • "type": "screen",
  • "name": "feed",
  • "properties": {
    • "Screen Properties1": null,
    • "Screen Properties2": null,
    • "subscriptions": [
      ]
    },
  • "integrations": {
    • "All": true,
    • "Salesforce": false
    },
  • "messageId": "022bb90c-bbac-11e4-8dfc-aa07a5b093db",
  • "receivedAt": "2015-02-23T22:28:55.387Z",
  • "sentAt": "2015-02-23T22:28:55.111Z",
  • "originalTimestamp": "2019-08-24T14:15:22Z",
  • "timestamp": "2015-02-23T22:28:55.111Z",
  • "version": 1.1,
  • "context": {
    • "active": true,
    • "ip": "8.8.8.8",
    • "locale": "string",
    • "userAgent": "string",
    • "channel": "browser",
    • "app": {
      },
    • "device": {
      },
    • "network": {
      },
    • "os": {
      }
    },
  • "anonymousId": "507f191e810c19729de860ea"
}

Group Schema

Group events assign the identified person to a group. You'll typically pass the groupId that you want to associate a person with, and any traits that you want to assign to the group.

Most other fields are populated by Customer.io—either by a source library or our servers.

One of
userId
string

The unique identifier for a person. This value should be unique across systems, so you recognize the same person in your sources and destinations.

type
string
Value: "group"

The event type. This is set automatically by the request method/endpoint.

groupId
string

ID of the group

objectTypeId
string

If you use Customer.io Journeys as a destination, this value is the type of group/object your group belongs to; object type IDs are stringified integers. If you don't include this value, we assume the object type ID is 1. See objects in Customer.io Journeys for more information.

You can include this value as objectTypeId at the top level of your payload or as object_type_id in the traits object.

object

Additional information about the group.

object

Contains a list of booleans indicating the integrations that are enabled (true) or disabled (false). By default, all integrations are enabled (returning an empty object). Set "All": false to reverse this behavior.

messageId
string

A unique identifier for a Data Pipelines call, ensuring that each individual event is unique. This is set by Customer.io

receivedAt
string <date-time>

The ISO-8601 timestamp when Data Pipelines receives an event.

sentAt
string <date-time>

The ISO-8601 timestamp when a library sends an event to Data Pipelines.

originalTimestamp
string <date-time>

In general, you can use timestamp rather than this field if you want to back-date events. This is the timestamp on the client device you invoke a call or the timestamp value you manually passed in a server-side library call.

timestamp
string <date-time>

The ISO-8601 timestamp when the event originally took place. This is mostly useful when you backfill past events. If you're not backfilling data, you can leave this field empty and we'll use the current time or server time.

version
number

The version of the API that received the event, automatically set by Customer.io.

object

A dictionary of context about a source call/event, like the user’s IP address or locale. Context is automatically collected by our source libraries.

Example
{
  • "userId": "97980cfea0067",
  • "type": "group",
  • "groupId": "0e8c78ea9d97a7b8185e8632,",
  • "objectTypeId": "1",
  • "traits": {
    • "object_type_id": "1",
    • "Group Traits1": {
      },
    • "Group Traits2": {
      },
    • "name": "ACME, Inc.",
    • "industry": "Technology",
    • "employees": 329,
    • "plan": "enterprise",
    • "total billed": 830
    },
  • "integrations": {
    • "All": true,
    • "Salesforce": false,
    • "Mixpanel": false
    },
  • "messageId": "022bb90c-bbac-11e4-8dfc-aa07a5b093db,",
  • "receivedAt": "2015-02-23T22:28:55.387Z,",
  • "sentAt": "2015-02-23T22:28:55.111Z,",
  • "originalTimestamp": "2019-08-24T14:15:22Z",
  • "timestamp": "2015-02-23T22:28:55.111Z,",
  • "version": 1.1,
  • "context": {
    • "active": true,
    • "ip": "8.8.8.8",
    • "locale": "string",
    • "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_9_5) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/40.0.2214.115 Safari/537.36",
    • "channel": "browser",
    • "campaign": {
      },
    • "page": {
      }
    },
  • "anonymousId": "507f191e810c19729de860ea,",
  • "channel": "browser,"
}

Common fields

These are the fields that we augment incoming data with. The shape of this data may change depending on the type of call you make (identify, track, etc), and the source medium (client side javascript, mobile library, etc). We collect many of these values automatically, though you can override some of them. See individual methods below for information about which fields are accepted in requests.

object

Contains a list of booleans indicating the integrations that are enabled (true) or disabled (false). By default, all integrations are enabled (returning an empty object). Set "All": false to reverse this behavior.

messageId
string

A unique identifier for a Data Pipelines call, ensuring that each individual event is unique. This is set by Customer.io

receivedAt
string <date-time>

The ISO-8601 timestamp when Data Pipelines receives an event.

sentAt
string <date-time>

The ISO-8601 timestamp when a library sends an event to Data Pipelines.

originalTimestamp
string <date-time>

In general, you can use timestamp rather than this field if you want to back-date events. This is the timestamp on the client device you invoke a call or the timestamp value you manually passed in a server-side library call.

timestamp
string <date-time>

The ISO-8601 timestamp when the event originally took place. This is mostly useful when you backfill past events. If you're not backfilling data, you can leave this field empty and we'll use the current time or server time.

type
string
Enum: "identify" "group" "track" "page" "screen" "alias"

The type of source event. This is implicit and set by Customer.io based on the endpoint/method you use (e.g. identify).

version
number

The version of the API that received the event, automatically set by Customer.io.

object

A dictionary of context about a source call/event, like the user’s IP address or locale. Context is automatically collected by our source libraries.

{
  • "integrations": {
    • "All": true,
    • "Salesforce": false
    },
  • "messageId": "string",
  • "receivedAt": "2019-08-24T14:15:22Z",
  • "sentAt": "2019-08-24T14:15:22Z",
  • "originalTimestamp": "2019-08-24T14:15:22Z",
  • "timestamp": "2019-08-24T14:15:22Z",
  • "type": "identify",
  • "version": 0,
  • "context": {
    • "active": true,
    • "ip": "string",
    • "locale": "string",
    • "userAgent": "string",
    • "channel": "browser",
    • "campaign": {
      },
    • "page": {
      }
    }
}

The Context object

These are fields that we collect automatically with requests—context for the request—but you can override these values.

One of
active
boolean

Whether a user is active.

This is usually used when you send an .identify() call to update the traits independently of when you've “last seen” a user.

ip
string

The user's IP address. This isn't captured by our libraries, but by our servers when we receive client-side events (like from our JavaScript source).

locale
string

The locale string for the current user, e.g. en-US.

userAgent
string

The user agent of the device making the request

channel
string
Enum: "browser" "server" "mobile"

The channel the event originated from.

object

Contains information about the campaign that resulted in the API call, gathered from, or mapping to, UTM parameters (e.g. utm_source).

object

Contains information about the current page in the browser. This is automatically collected by our JavaScript source.

Example
{
  • "active": true,
  • "ip": "string",
  • "locale": "string",
  • "userAgent": "string",
  • "channel": "browser",
  • "campaign": {
    • "name": "string",
    • "source": "string",
    • "medium": "string",
    • "term": "string",
    • "content": "string",
    • "Additional UTM Parameters1": "string",
    • "Additional UTM Parameters2": "string"
    },
  • "page": {
    • "name": "string",
    • "path": "string",
    • "referrer": "string",
    • "search": "string",
    • "title": "string",
    • "url": "string",
    • "keywords": [
      ]
    }
}

Customer.io semantic event schemas

analytics.track("Device Created or Updated", {
  device: {
    token: "string",
    type: "ios"
  }
});

Journeys, our messaging automation tool, supports a number of actions that aren't immediately apparent from the API. For example, I can add a person using the identify function, but what if I want to remove a person?

That's what semantic events are for: they let you send track calls with a specific event name and payload to perform actions in Journeys. In general, the event names map directly to the thing you want to do: like Create Device or Delete Person.

Delete person

Remove a person from your Customer.io environment. You might do this when someone cancels their subscription with you or otherwise leaves your service.

event
required
string
Value: "User Deleted"

The event name.

userId
required
string

The user's unique identifier or their email address. If you provide an email address, we'll look up the person by their email address and delete them.

properties
object

Properties for the event. These aren't typically useful in Customer.io when deleting people, but you might use them in other places—like an analytics tool (e.g. Mixpanel).

{
  • "type": "track",
  • "event": "User Deleted",
  • "userId": "42",
  • "timestamp": "2021-07-14T19:10:25.000Z"
}

Create or Update a Device

Add or update a device. If a device (represented by the context.device.token) exists, does not exist, we'll create it. If the device token already exists, we'll update the it.

required
object

Properties for the event.

event
required
string
Value: "Device Created or Updated"

The event name.

userId
required
string

The user's unique identifier.

{
  • "type": "track",
  • "event": "Device Created or Updated",
  • "userId": "42",
  • "properties": {
    • "device": {
      }
    },
  • "timestamp": "2021-07-14T19:10:25.000Z"
}

Delete a Device

Delete a device. You might do this when someone logs out of your app or otherwise removes a device.

event
required
string
Value: "Device Deleted"

The event name.

userId
required
string

The user's unique identifier.

object

Properties for the event.

{
  • "type": "track",
  • "event": "Delete Device",
  • "userId": "42",
  • "properties": {
    • "device": {
      }
    },
  • "timestamp": "2021-07-14T19:10:25.000Z"
}

Delete a relationship

Remove a relationship between a person and an object in Customer.io. This is basically the opposite of a group operation. Where objects represent things like accounts, companies, or online classes, you might delete a relationship when a person is no longer on an account, leaves a company, or drops a class.

This event requires a groupId and an objectTypeId. If you don't provide an objectTypeId, we'll assume it's 1, but if the groupId with the associated objectTypeId` (defaulting to 1) does not exist, the event will not remove a person from the group.

event
required
string
Value: "Relationship Deleted"

The event name.

userId
required
string

The user's unique identifier or their email address. If you provide an email address, we'll look up the person by their email address.

required
object

Properties for the event. In this case, you'll need to provide the objectId. You should also provide the objectTypeId if you have more than 1 object type; if you don't include it, we'll assume it's 1.

{
  • "type": "track",
  • "name": "Relationship Deleted",
  • "userId": "1",
  • "properties": {
    • "objectId": "acme",
    • "objectTypeId": "1"
    }
}

Delete an object

Remove an object (sometimes called a "group") from Customer.io Journeys. Groups/objects represent things like accounts, companies, and online classes—non-people entities that people can be related to. You might delete a group when an account is closed, a company is acquired, or you stop offering a class.

This event requires a groupId and an objectTypeId. If you don't provide an objectTypeId, we'll assume it's 1, but if the groupId with the associated objectTypeId (defaulting to 1) does not exist, the event will not find and delete the groupId.

event
required
string
Value: "Object Deleted"

The event name.

object

Properties for the event. These aren't typically useful in Customer.io when deleting groups, but you might use them in other places—like an analytics tool (e.g. Mixpanel).

{
  • "type": "track",
  • "name": "Object Deleted",
  • "properties": {
    • "objectId": "acme",
    • "objectTypeId": "1"
    }
}

Suppress a person

Remove a person from your Customer.io workspace and prevent them from being added back to your workspace using the same identifier. In general you should only send this event for compliance reasons, like when someone invokes their right to be forgotten in accordance with GDPR or CAN-SPAM regulations.

event
required
string
Value: "User Suppressed"

The event name.

userId
required
string

The user's unique identifier.

timestamp
string <date-time>

The ISO-8601 timestamp when the event occurred.

object

Properties for the event. These aren't typically useful in Customer.io when suppressing people, but you might use them in other places—like an analytics tool (e.g. Mixpanel).

{
  • "type": "track",
  • "event": "User Suppressed",
  • "userId": "42",
  • "timestamp": "2021-07-14T19:10:25.000Z"
}

Unsuppress a person

Allow a userId to be added back to your Customer.io workspace. This does not restore information from a person you previously suppressed. It only allows you to add a person back to your workspace using the same identifier.

event
required
string
Value: "User Unsuppressed"

The event name.

userId
required
string

The user's unique identifier.

timestamp
string <date-time>

The ISO-8601 timestamp when the event occurred.

object

Properties for the event. These aren't typically useful in Customer.io when unsuppressing people, but you might use them in other places—like an analytics tool (e.g. Mixpanel).

{
  • "type": "track",
  • "event": "User Unsuppressed",
  • "userId": "42",
  • "timestamp": "2021-07-14T19:10:25.000Z"
}

Report a message delivery

Reports delivery events for messages. In general, we use this event with our JavaScript snippet to report delivery events for in-app messages back to your Customer.io workspace.

While Customer.io knows about messages that are sent, we use this event to determine when an in-app message is delivered, clicked, and so on. Each message contains a unique deliveryId that we trace back to the person, campaign/broadcast, and other items in your Customer.io workspace.

event
required
string
Value: "Report Delivery Event"

The event name.

required
object

Properties for the event. These aren't typically useful in Customer.io when suppressing people, but you might use them in other places—like an analytics tool (e.g. Mixpanel).

timestamp
string <date-time>

The ISO-8601 timestamp when the event occurred.

{
  • "type": "track",
  • "event": "Report Delivery Event",
  • "timestamp": "2021-07-14T19:10:25.000Z",
  • "properties": {
    • "deliveryId": "42",
    • "metric": "clicked",
    • "recipient": "device_token",
    • "actionValue": "enable_push",
    • "href": "myapp://settings/enable_push"
    }
}

A/B test event schemas

analytics.track('Experiment Viewed', {
  experiment_id: "12345",
  experiment_name: "Homepage Hero",
  variant_id: "67890",
  variant_name: "Hero B"
})

If you track A/B tests, we recommend that you use the event name Experiment Viewed and properties listed below. Sending uniform events that conform to the schema defined here helps ensure that you can use any default actions that we set up for destinations that rely on A/B test events—now or with destinations we add in the future.

experiment_id
string

The ID of the A/B test.

experiment_name
string

The A/B test’s human-readable name.

variation_id
string

The ID of the individual test variant.

variation_name
string

The A/B test variant's human-readable name.

{
  • "experiment_id": "string",
  • "experiment_name": "string",
  • "variation_id": "string",
  • "variation_name": "string"
}

Ecommerce event schemas

analytics.track('Product Viewed', {
  product_id: "coolshoes-123"
  sku: "abc-123-xyz"
  category: "shoes"
  name: "Cool Shoes"
  brand: "A Shoe Brand"
  variant: "red"
  price: 139.99
  quantity: 1
  coupon: "NEWUSER20"
  position: 3
  url: "https://www.example.com/product/123"
  image_url: "https://www.example.com/product/123.jpg"
  currency: "USD"
  value: 119.99
})

We've defined a set of track events that you can use to send ecommerce activity from your sources. Our default actions and data structures assume that you send ecommerce events in the shapes below. Learn more about our ecommerce specification.

If you send an event with a matching name and structure defined below (where the schemas below represents the properties object), destinations that rely on ecommerce events (like "ad" destinations) will already be set up with actions to handle your ecommerce source events. For example, sending the following Product Viewed event would automatically trigger an action in most of our "ad" destinations and handle all the fields in the event.

The title of each schema below is the name of the event you should pass in a track call.

While you can map ecommerce events however you want, we recommend that you use the events below to take advantage of our default actions and data structures. These events make it easy to send uniform data through data pipelines to your destinations.

Products Searched

Send Products Searched when a user searches for products.

query
string

The search query the customer entered.

{
  • "query": "pepperoni pizza"
}

Product List Viewed

Send the Product List Viewed event when a user views a product.

product_id
string

The product ID.

sku
string

The stock keeping unit (SKU) of the product a person viewed.

category
string

The product category a person viewed.

name
string

The name of the product a person viewed.

brand
string

The brand associated with the product.

variant
string

The variant of the product a person viewed, if applicable.

price
number

The price of the product.

quantity
integer

The quantity of the product.

coupon
string

The coupon code associated with the product (like NEWUSER20).

position
number

The position of the product in the list.

url
string

The URL of the product page.

image_url
string

The URL of the product image.

currency
string

The currency of the transaction.

value
number

The total value of the product, after multiplying by quantity.

{}

Product List Filtered

Send the Product List Filtered event when a user filters a list of products.

list_id
string

The product list a person viewed.

category
string

The product category a person viewed.

Array of objects

The products displayed in the product list. Each object in the array represents a product.

Array of objects

The filters a person applied to the product list, where each object in the array is a different filter.

Array of objects

The sorts a person applied to the product list, where each object in the array is a different sort.

{
  • "list_id": "all_shoes",
  • "category": "shoes",
  • "products": [],
  • "filters": [
    • {
      }
    ],
  • "sorts": [
    • {
      }
    ]
}

Product Clicked

Send the Product Clicked event when a user clicks a product.

product_id
string

The product ID.

sku
string

The stock keeping unit (SKU) of the product a person viewed.

category
string

The product category a person viewed.

name
string

The name of the product a person viewed.

brand
string

The brand associated with the product.

variant
string

The variant of the product a person viewed, if applicable.

price
number

The price of the product.

quantity
integer

The quantity of the product.

coupon
string

The coupon code associated with the product (like NEWUSER20).

position
number

The position of the product in the list.

url
string

The URL of the product page.

image_url
string

The URL of the product image.

currency
string

The currency of the transaction.

value
number

The total value of the product, after multiplying by quantity.

{}

Product Viewed

Send the Product Viewed event when a user viewed a product. This might happen on a page, in a modal window, etc.

product_id
string

The product ID.

sku
string

The stock keeping unit (SKU) of the product a person viewed.

category
string

The product category a person viewed.

name
string

The name of the product a person viewed.

brand
string

The brand associated with the product.

variant
string

The variant of the product a person viewed, if applicable.

price
number

The price of the product.

quantity
integer

The quantity of the product.

coupon
string

The coupon code associated with the product (like NEWUSER20).

position
number

The position of the product in the list.

url
string

The URL of the product page.

image_url
string

The URL of the product image.

currency
string

The currency of the transaction.

value
number

The total value of the product, after multiplying by quantity.

{}

Product Added

Send the Product Added event when a user adds a product to their cart.

product_id
string

The product ID.

sku
string

The stock keeping unit (SKU) of the product a person viewed.

category
string

The product category a person viewed.

name
string

The name of the product a person viewed.

brand
string

The brand associated with the product.

variant
string

The variant of the product a person viewed, if applicable.

price
number

The price of the product.

quantity
integer

The quantity of the product.

coupon
string

The coupon code associated with the product (like NEWUSER20).

position
number

The position of the product in the list.

url
string

The URL of the product page.

image_url
string

The URL of the product image.

cart_id
string

The cart ID the product was added to.

{}

Product Removed

Send the Product Removed event when a user removes a product from their cart.

product_id
string

The product ID.

sku
string

The stock keeping unit (SKU) of the product a person viewed.

category
string

The product category a person viewed.

name
string

The name of the product a person viewed.

brand
string

The brand associated with the product.

variant
string

The variant of the product a person viewed, if applicable.

price
number

The price of the product.

quantity
integer

The quantity of the product.

coupon
string

The coupon code associated with the product (like NEWUSER20).

position
number

The position of the product in the list.

url
string

The URL of the product page.

image_url
string

The URL of the product image.

cart_id
string

The cart ID the product was removed from.

{}

Cart Viewed

Send the Cart Viewed event when a user views their cart.

cart_id
string

The cart ID a person viewed.

Array of objects

The products in the cart. Each object in the array represents a product.

{}

Checkout Started

Send the Checkout Started event when a user starts the checkout process.

order_id
string

The cart ID a person viewed.

affiliation
string

The store or affiliation from the transaction occurred from, like "Google Play Store".

revenue
number

The total revenue of the transaction without discounts, coupons, shipping, and tax.

shipping
number

The total shipping cost of the transaction.

tax
number

The tax associated with the the transaction.

discount
number

The total discount applied to the transaction.

coupon
string

The coupon code associated with the transaction.

currency
string

The currency of the transaction.

Array of objects

The products in the cart. Each object in the array represents a product.

value
number

The expected total revenue of the transaction calculated with discounts/coupons.

{
  • "order_id": "cool_persons_cart_123",
  • "affiliation": "Shopify",
  • "revenue": 139.99,
  • "shipping": 5,
  • "tax": 10,
  • "discount": 20,
  • "coupon": "NEWUSER20",
  • "currency": "USD",
  • "products": [],
  • "value": 119.99
}

Checkout Step Viewed

Send the Checkout Step Viewed event when a user views a step in the checkout process.

checkout_id
string

The checkout/transaction ID.

step
integer

The step number of the checkout process.

shipping_method
string

The shipping method selected by the user.

payment_method
string

The payment method selected by the user.

{
  • "checkout_id": "string",
  • "step": 2,
  • "shipping_method": "ground",
  • "payment_method": "Visa"
}

Checkout Step Completed

Send the Checkout Step Completed event when a user completes a step in the checkout process.

checkout_id
string

The checkout/transaction ID.

step
integer

The step number of the checkout process.

shipping_method
string

The shipping method selected by the user.

payment_method
string

The payment method selected by the user.

{
  • "checkout_id": "cool_persons_checkout_123",
  • "step": 2,
  • "shipping_method": "ground",
  • "payment_method": "Visa"
}

Payment Info Entered

Send the Payment Info Entered event when a user enters their payment information.

checkout_id
string

The checkout/transaction ID.

step
integer

The step number of the checkout process.

shipping_method
string

The shipping method selected by the user.

payment_method
string

The payment method selected by the user.

order_id
string

The order ID.

{
  • "checkout_id": "string",
  • "step": 2,
  • "shipping_method": "ground",
  • "payment_method": "Visa",
  • "order_id": "order123"
}

Order Completed

Send the Order Completed event when a user completes an order.

subtotal
number

The order total after discounts but before taxes and shipping.

Array of objects

The products displayed in the product list. Each object in the array represents a product.

order_id
string

The order ID.

checkout_id
string

The checkout/transaction ID.

total
number

The total amount of the order.

affiliation
string

The store or affiliation from the transaction occurred from, like "Google Play Store".

revenue
number

The total revenue of the transaction without discounts, coupons, shipping, and tax.

shipping
number

The total shipping cost of the transaction.

tax
number

The tax associated with the the transaction.

discount
number

The total discount applied to the transaction.

coupon
string

The coupon code associated with the transaction.

currency
string

The currency of the transaction.

{
  • "subtotal": 119.99,
  • "products": [],
  • "order_id": "cool_persons_cart_123",
  • "checkout_id": "checkout123",
  • "total": 119.99,
  • "affiliation": "Shopify",
  • "revenue": 139.99,
  • "shipping": 5,
  • "tax": 10,
  • "discount": 20,
  • "coupon": "NEWUSER20",
  • "currency": "USD"
}

Order Updated

Send the Order Updated event when a user updates an order.

order_id
string

The cart ID a person viewed.

affiliation
string

The store or affiliation from the transaction occurred from, like "Google Play Store".

revenue
number

The total revenue of the transaction without discounts, coupons, shipping, and tax.

shipping
number

The total shipping cost of the transaction.

tax
number

The tax associated with the the transaction.

discount
number

The total discount applied to the transaction.

coupon
string

The coupon code associated with the transaction.

currency
string

The currency of the transaction.

Array of objects

The products in the cart. Each object in the array represents a product.

{
  • "order_id": "cool_persons_cart_123",
  • "affiliation": "Shopify",
  • "revenue": 139.99,
  • "shipping": 5,
  • "tax": 10,
  • "discount": 20,
  • "coupon": "NEWUSER20",
  • "currency": "USD",
  • "products": []
}

Order Refunded

Send the Order Refunded event when you refund an order.

order_id
string

The cart ID a person viewed.

affiliation
string

The store or affiliation from the transaction occurred from, like "Google Play Store".

revenue
number

The total revenue of the transaction without discounts, coupons, shipping, and tax.

shipping
number

The total shipping cost of the transaction.

tax
number

The tax associated with the the transaction.

discount
number

The total discount applied to the transaction.

coupon
string

The coupon code associated with the transaction.

currency
string

The currency of the transaction.

Array of objects

The products in the cart. Each object in the array represents a product.

total
number

The total amount refunded.

subtotal
number

The order total after discounts but before taxes and shipping.

checkout_id
string

The checkout/transaction ID.

{
  • "order_id": "order123",
  • "affiliation": "Shopify",
  • "revenue": 139.99,
  • "shipping": 5,
  • "tax": 10,
  • "discount": 20,
  • "coupon": "NEWUSER20",
  • "currency": "USD",
  • "products": [],
  • "total": 119.99,
  • "subtotal": 119.99,
  • "checkout_id": "checkout123"
}

Order Cancelled

Send the Order Cancelled event when a customer cancels an order.

order_id
string

The cart ID a person viewed.

affiliation
string

The store or affiliation from the transaction occurred from, like "Google Play Store".

revenue
number

The total revenue of the transaction without discounts, coupons, shipping, and tax.

shipping
number

The total shipping cost of the transaction.

tax
number

The tax associated with the the transaction.

discount
number

The total discount applied to the transaction.

coupon
string

The coupon code associated with the transaction.

currency
string

The currency of the transaction.

Array of objects

The products in the cart. Each object in the array represents a product.

total
number

The total amount of the order.

{
  • "order_id": "order123",
  • "affiliation": "Shopify",
  • "revenue": 139.99,
  • "shipping": 5,
  • "tax": 10,
  • "discount": 20,
  • "coupon": "NEWUSER20",
  • "currency": "USD",
  • "products": [],
  • "total": 119.99
}

Promotion Viewed

Send the Promotion Viewed event when a user views a promotion.

promotion_id
string

The ID of the promotion a person viewed.

creative
string

The creative content ID associated with the promotion.

name
string

The name of the promotion a person viewed.

position
string

The position of the promotion a person viewed.

{
  • "promotion_id": "promo_123",
  • "creative": "top_banner_2",
  • "name": "summer_sale",
  • "position": "banner_slot_1"
}

Promotion Clicked

Send the Promotion Clicked event when a user clicks a promotion.

promotion_id
string

The ID of the promotion a person viewed.

creative
string

The creative content ID associated with the promotion.

name
string

The name of the promotion a person viewed.

position
string

The position of the promotion a person viewed.

{
  • "promotion_id": "promo_123",
  • "creative": "top_banner_2",
  • "name": "summer_sale",
  • "position": "banner_slot_1"
}

Coupon Entered

Send the Coupon Entered event when a user enters a coupon.

order_id
string

The order/transaction the coupon applies to (if applicable).

cart_id
string

The ID of the cart that the coupon applies to (if applicable).

coupon_id
string

the coupon ID the person entered.

{
  • "order_id": "order123",
  • "cart_id": "cool_persons_cart_123",
  • "coupon_id": "NEWUSER20"
}

Coupon Applied

Send the Coupon Applied event when you apply a coupon the customer entered to their order/transaction.

order_id
string

The order/transaction the coupon applies to (if applicable).

cart_id
string

The ID of the cart that the coupon applies to (if applicable).

coupon_id
string

the coupon ID the person entered.

coupon_name
string

The name of the coupon, if applicable.

discount
number

The discount applied through the coupon. This is the ammount subtracted from the total in other transaction events.

{
  • "order_id": "order123",
  • "cart_id": "cool_persons_cart_123",
  • "coupon_id": "NEWUSER20",
  • "coupon_name": "NEWUSER20",
  • "discount": 20
}

Coupon Denied

Send the Coupon Denied event when you deny a user's coupon. This might happen because the coupon code is invalid, expired, etc.

order_id
string

The order/transaction the coupon applies to (if applicable).

cart_id
string

The ID of the cart that the coupon applies to (if applicable).

coupon_id
string

the coupon ID the person entered.

coupon_name
string

The name of the coupon, if applicable.

reason
string

The reason the coupon was denied.

{
  • "order_id": "order123",
  • "cart_id": "cool_persons_cart_123",
  • "coupon_id": "NEWUSER20",
  • "coupon_name": "NEWUSER20",
  • "reason": "Coupon expired"
}

Coupon Removed

Send the Coupon Removed event when a user revmoes a coupon from their cart or order.

order_id
string

The order/transaction the coupon applies to (if applicable).

cart_id
string

The ID of the cart that the coupon applies to (if applicable).

coupon_id
string

the coupon ID the person entered.

coupon_name
string

The name of the coupon, if applicable.

discount
number

The discount applied through the coupon. This is the ammount subtracted from the total in other transaction events.

{
  • "order_id": "order123",
  • "cart_id": "cool_persons_cart_123",
  • "coupon_id": "NEWUSER20",
  • "coupon_name": "NEWUSER20",
  • "discount": 20
}

Product Added to Wishlist

Send the Product Added to Wishlist event when a user adds a product to their wishlist.

wishlist_id
string

The ID of the wishlist that the product applies to.

wishlist_name
string

The name of the wishlist that the product applies to.

product_id
string

The product ID.

sku
string

The stock keeping unit (SKU) of the product a person viewed.

category
string

The product category a person viewed.

name
string

The name of the product a person viewed.

brand
string

The brand associated with the product.

variant
string

The variant of the product a person viewed, if applicable.

price
number

The price of the product.

quantity
integer

The quantity of the product.

coupon
string

The coupon code associated with the product (like NEWUSER20).

position
number

The position of the product in the list.

url
string

The URL of the product page.

image_url
string

The URL of the product image.

{}

Product Removed from Wishlist

Send the Product Removed from Wishlist event when a user removes a product from their wishlist.

wishlist_id
string

The ID of the wishlist that the product applies to.

wishlist_name
string

The name of the wishlist that the product applies to.

product_id
string

The product ID.

sku
string

The stock keeping unit (SKU) of the product a person viewed.

category
string

The product category a person viewed.

name
string

The name of the product a person viewed.

brand
string

The brand associated with the product.

variant
string

The variant of the product a person viewed, if applicable.

price
number

The price of the product.

quantity
integer

The quantity of the product.

coupon
string

The coupon code associated with the product (like NEWUSER20).

position
number

The position of the product in the list.

url
string

The URL of the product page.

image_url
string

The URL of the product image.

{}

Wishlist Product Added to Cart

Send the Wishlist Product Added to Cart event when a user adds a product from their wishlist to their cart.

wishlist_id
string

The ID of the wishlist that the product applies to.

wishlist_name
string

The name of the wishlist that the product applies to.

cart_id
string

The ID of the cart that the product was added to.

product_id
string

The product ID.

sku
string

The stock keeping unit (SKU) of the product a person viewed.

category
string

The product category a person viewed.

name
string

The name of the product a person viewed.

brand
string

The brand associated with the product.

variant
string

The variant of the product a person viewed, if applicable.

price
number

The price of the product.

quantity
integer

The quantity of the product.

coupon
string

The coupon code associated with the product (like NEWUSER20).

position
number

The position of the product in the list.

url
string

The URL of the product page.

image_url
string

The URL of the product image.

{
  • "wishlist_id": "cool_persons_wishlist_123",
  • "wishlist_name": "Cool Person's Wishlist",
  • "cart_id": "cool_persons_cart_123",
  • "product_id": "coolshoes-123",
  • "sku": "abc-123-xyz",
  • "category": "shoes",
  • "name": "Cool Shoes",
  • "brand": "A Shoe Brand",
  • "variant": "red",
  • "price": 139.99,
  • "quantity": 1,
  • "coupon": "NEWUSER20",
  • "position": 3,
}

Product Shared

Send the Product Shared event when a user shares a product.

share_via
string

The channel the product was shared through.

share_message
string

The message the customer sent with the share.

recipient
string

The person the product was shared with.

product_id
string

The product ID.

sku
string

The stock keeping unit (SKU) of the product a person viewed.

category
string

The product category a person viewed.

name
string

The name of the product a person viewed.

brand
string

The brand associated with the product.

variant
string

The variant of the product a person viewed, if applicable.

price
number

The price of the product.

url
string

The URL of the product page.

image_url
string

The URL of the product image.

{}

Cart Shared

Send the Cart Shared event when a user shares their cart.

share_via
string

The channel the product was shared through.

share_message
string

The message the customer sent with the share.

recipient
string

The person the product was shared with.

cart_id
string

The shopping cart ID.

Array of objects

An array of product IDs contained in the shared cart.

{
  • "share_via": "email",
  • "share_message": "Check out my cart!",
  • "recipient": "friendOfcool.person@example.com",
  • "cart_id": "cool_persons_cart_123",
  • "products": [
    • {
      }
    ]
}

Product Reviewed

Send the Product Reviewed event when a user submits a review of a product.

product_id
string

The product ID.

review_id
string

The ID of the review.

review_body
string

The body of the review.

rating
integer

The rating the customer gave the product.

{
  • "product_id": "coolshoes-123",
  • "review_id": "review_123",
  • "review_body": "These shoes are great!",
  • "rating": 5
}

Email event schemas

If you send events from an email service provider or another application that sends and tracks email, we recommend that you use events with the names and properties specified below. Sending uniform events that conform to the schemas defined here ensures that you can use any default actions that we set up for destinations that rely on email events—now or with destinations we add in the future.

Email Bounced

This event indicates that your email server/service provider couldn’t deliver a message to the recipient.

object

Event properties that you can send in a semantic email event. You should send as many of these properties as are available, but you'll almost certainly need the email_id to know which email the event refers to.

object

Contextual information about the event. These fields are in addition to any captured automatically by your source library.

{
  • "properties": {
    • "email_id": "string",
    • "email_subject": "string",
    • "campaign_id": "string",
    • "campaign_name": "string"
    },
  • "context": {
    • "traits": {
      }
    }
}

Email Delivered

object

Event properties that you can send in a semantic email event. You should send as many of these properties as are available, but you'll almost certainly need the email_id to know which email the event refers to.

object

Contextual information about the event. These fields are in addition to any captured automatically by your source library.

{
  • "properties": {
    • "email_id": "string",
    • "email_subject": "string",
    • "campaign_id": "string",
    • "campaign_name": "string"
    },
  • "context": {
    • "traits": {
      }
    }
}

Email Opened

object

Event properties that you can send in a semantic email event. You should send as many of these properties as are available, but you'll almost certainly need the email_id to know which email the event refers to.

object

Contextual information about the event. These fields are in addition to any captured automatically by your source library.

{
  • "properties": {
    • "email_id": "string",
    • "email_subject": "string",
    • "campaign_id": "string",
    • "campaign_name": "string"
    },
  • "context": {
    • "traits": {
      }
    }
}

Email Marked as Spam

object

Event properties that you can send in a semantic email event. You should send as many of these properties as are available, but you'll almost certainly need the email_id to know which email the event refers to.

object

Contextual information about the event. These fields are in addition to any captured automatically by your source library.

{
  • "properties": {
    • "email_id": "string",
    • "email_subject": "string",
    • "campaign_id": "string",
    • "campaign_name": "string"
    },
  • "context": {
    • "traits": {
      }
    }
}

Email Unsubscribed

object

Event properties that you can send in a semantic email event. You should send as many of these properties as are available, but you'll almost certainly need the email_id to know which email the event refers to.

object

Contextual information about the event. These fields are in addition to any captured automatically by your source library.

{
  • "properties": {
    • "email_id": "string",
    • "email_subject": "string",
    • "campaign_id": "string",
    • "campaign_name": "string",
    • "list_id": "string",
    • "list_name": "string"
    },
  • "context": {
    • "traits": {
      }
    }
}

Live chat event schemas

analytics.track('Experiment Viewed', {
  experiment_id: "12345",
  experiment_name: "Homepage Hero",
  variant_id: "67890",
  variant_name: "Hero B"
})

If you send events from a live chat application, we recommend that you use events with the names and properties specified below. Sending uniform events that conform to the schemas defined here ensures that you can use any default actions that we set up for destinations that rely on Live Chat events—now or with destinations we add in the future.

Live Chat Conversation Started

Send this event when a user begins a conversation with you or your team (the "agent").

agent_id
string

The ID of the agent taking the conversation.

agent_name
string

The real name of the agent.

agent_username
string

The username of the agent.

conversation_id
string

The ID of the conversation.

conversation_duration
integer

The duration of the conversation in seconds. 0 when the conversation starts, and the number of seconds indicates the time in the conversation when each message

message_id
string

The ID of the message that starts the conversation.

{
  • "agent_id": "string",
  • "agent_name": "string",
  • "agent_username": "string",
  • "conversation_id": "string",
  • "conversation_duration": 0,
  • "message_id": "string"
}

Live Chat Conversation Ended

Send this event when you or a user ends a conversation.

agent_id
string

The ID of the agent taking the conversation.

agent_name
string

The real name of the agent.

agent_username
string

The username of the agent.

conversation_id
string

The ID of the conversation.

conversation_duration
integer

The duration of the conversation in seconds. 0 when the conversation starts, and the number of seconds indicates the time in the conversation when each message

message_id
string

The ID of the message that starts the conversation.

{
  • "agent_id": "string",
  • "agent_name": "string",
  • "agent_username": "string",
  • "conversation_id": "string",
  • "conversation_duration": 0,
  • "message_id": "string"
}

Live Chat Message Sent

Send this event when an agent sends a message to a customer/user.

agent_id
string

The ID of the agent taking the conversation.

agent_name
string

The real name of the agent.

agent_username
string

The username of the agent.

conversation_id
string

The ID of the conversation.

conversation_duration
integer

The duration of the conversation in seconds. 0 when the conversation starts, and the number of seconds indicates the time in the conversation when each message

message_id
string

The ID of the message that starts the conversation.

{
  • "agent_id": "string",
  • "agent_name": "string",
  • "agent_username": "string",
  • "conversation_id": "string",
  • "conversation_duration": 0,
  • "message_id": "string"
}

Live Chat Message Received

Send this event when you receive a message from a customer/user.

agent_id
string

The ID of the agent taking the conversation.

agent_name
string

The real name of the agent.

agent_username
string

The username of the agent.

conversation_id
string

The ID of the conversation.

conversation_duration
integer

The duration of the conversation in seconds. 0 when the conversation starts, and the number of seconds indicates the time in the conversation when each message

message_id
string

The ID of the message that starts the conversation.

{
  • "agent_id": "string",
  • "agent_name": "string",
  • "agent_username": "string",
  • "conversation_id": "string",
  • "conversation_duration": 0,
  • "message_id": "string"
}

Mobile application lifecycle event schemas

import CioDataPipelines

CustomerIO.shared.track(
    name: "Application Crashed", 
    properties: [
      "url": "urls://page/in/app"
    ]
)

These events represent your users' activities in your app—like when they open, close, or update your app. If you use our iOS 3.0 SDK, Android 4.0 SDK, or later versions of those SDKs, we automatically track a number of these events for you.

Application Installed

Our CDP-enabled SDKs send this event the first time a user opens your application. If the user never opens your app, we won't be able to collect this event. This event doesn't wait for the SDK to capture attribution or campaign information, and is collected automatically. Destinations like Facebook and Google require discrete install events to correctly attribute installs to ads served through their platforms.

One of
userId
string

The identifier of the user performing the event.

type
string
Value: "track"

Application events are always track calls.

event
string
Value: "Application Installed"

A person installed your app.

object

The properties typically sent with the event.

Example
{
  • "userId": "string",
  • "type": "track",
  • "event": "Application Installed",
  • "properties": {
    • "version": "string",
    • "build": "string"
    }
}

Application Opened

Our CDP-enabled SDKs send this event when a user launches or foregrounds your mobile application—after the first open. The first open results in an Application Installed event, so we only send this event on subsequent opens. Like the Application Installed event, this event also does not wait for the SDK to capture attribution information but it can include information about referring applications or deep link URLs if available when the app opens.

One of
userId
string

The identifier of the user performing the event.

type
string
Value: "track"

Application events are always track calls.

event
string
Value: "Application Opened"

A person opened your app. Our SDKs automatically send this event when a person opens your app fresh or when they return to the app after sending it to the the background.

object

The properties typically sent with the event.

Example
{
  • "userId": "string",
  • "type": "track",
  • "event": "Application Opened",
  • "properties": {
    • "from_background": true,
    • "url": "string",
    • "version": "string",
    • "build": "string"
    }
}

Application Backgrounded

Send this event when a user backgrounds the application upon applicationDidEnterBackground.

One of
userId
string

The identifier of the user performing the event.

type
string
Value: "track"

Application events are always track calls.

event
string
Value: "Application Backgrounded"

A person sent your app to the background. Our SDKs automatically send this event when a person backgrounds your app.

object

There are no default properties for the Application Backgrounded event. You can add custom properties to the event payload.

Example
{
  • "userId": "string",
  • "type": "track",
  • "event": "Application Backgrounded",
  • "properties": {
    • "property1": null,
    • "property2": null
    }
}

Application Foregrounded

Send this event when your audience returns to your app after previously backgrounding it. This event is distinct from Application Opened in that the app is considered opened already, even if it's in the background.

One of
userId
string

The identifier of the user performing the event.

type
string
Value: "track"

Application events are always track calls.

event
string
Value: "Application Foregrounded"

A person brought your app to the foreground after having backgrounded it, indicating that they're using it again. Our SDKs automatically send this event when a person brings your app back to the foreground.

object

There are no default properties for the Application Foregrounded event. You can add custom properties to the event payload.

Example
{
  • "userId": "string",
  • "type": "track",
  • "event": "Application Foregrounded",
  • "properties": {
    • "property1": null,
    • "property2": null
    }
}

Application Updated

Send this event when the user opens your app after updating your app. Our iOS 3 SDK, Android 4 SDK, and later versions of both automatically collect this event rather than the "Application Opened" event after someone updates your app.

If you want to capture all Application Opened events, you'll want to add Application Updated and Application Opened events!

One of
userId
string

The identifier of the user performing the event.

type
string
Value: "track"

Application events are always track calls.

event
string
Value: "Application Updated"

A person updated your app.

object

The properties typically sent with the event.

Example
{
  • "userId": "string",
  • "type": "track",
  • "event": "Application Updated",
  • "properties": {
    • "previous_version": "string",
    • "previous_build": "string",
    • "version": "string",
    • "build": "string"
    }
}

Application Uninstalled

You can send this event when a user uninstalls your app. Like similar events that happen outside of your app itself, our CDP-enabled SDKs cannot capture this event automatically.

However, some direct-mode destinations detect this for you using silent push notifications through their own SDKs. You might also be able to send these events to Customer.io using callbacks.

One of
userId
string

The identifier of the user performing the event.

type
string
Value: "track"

Application events are always track calls.

event
string
Value: "Application Uninstalled"

A person uninstalled your app.

object

There are no default properties for the Application uninstalled event. You can add custom properties to the event payload.

Example
{
  • "userId": "string",
  • "type": "track",
  • "event": "Application Uninstalled",
  • "properties": {
    • "property1": null,
    • "property2": null
    }
}

Application Crashed

You can send this event when you receive a crash notification from your app, but it is not meant to supplant traditional crash reporting tools. By tracking crashes this way, you can analyze which types of users are impacted by crashes and how those crashes affect their engagement. You may also want to send messages to users who experience crashes through other messaging channels.

Like similar events that happen outside of your app itself, our CDP-enabled SDKs cannot capture this event automatically. But you might be able to capture this kind of event with a callback or a webhook.

One of
userId
string

The identifier of the user performing the event.

type
string
Value: "track"

Application events are always track calls.

event
string
Value: "Application Crashed"

A person experienced a crash in your app. Our SDKs automatically send this event when a person experiences a crash in your app.

object

There are no default properties for the Application Crashed event. You can add custom properties to the event payload.

Example
{
  • "userId": "string",
  • "type": "track",
  • "event": "Application Crashed",
  • "properties": {
    • "property1": null,
    • "property2": null
    }
}

Video events

analytics.track('Experiment Viewed', {
  experiment_id: "12345",
  experiment_name: "Homepage Hero",
  variant_id: "67890",
  variant_name: "Hero B"
})

If you send events from a live chat application, we recommend that you use events with the names and properties specified below. Sending uniform events that conform to the schemas defined here ensures that you can use any default actions that we set up for destinations that rely on Live Chat events—now or with destinations we add in the future.

Video playback started

When a user presses Play; after the last user action required for playback to begin (for example, after user login/authentication).

content_asset_ids
Array of strings

The ID of the videos a user started. The array indicates a potential playlist of videos/content IDs a person is starting.

content_pod_ids
Array of strings

The IDs of the content "pods" in a playback session. Imagine a video that contains content and an ad; that means the video contains two pods—one for the content and one for the ad. The array indicates a potential playlist of content pod IDs a person is starting.

session_id
string

The unique ID of the overall session used to tie all events generated from a specific playback. This value should be the same across all playback, content, and ad events if they are from the same playback session.

ad_asset_id
string

The Ad Asset Id(s) of the ad/ads playing or about to be played in the video player. For Video Playback Started events only, you should send an Array of unique ad asset IDs. For all other playback events, you should send a string with the ID of the current ad asset playing at the time of the event.

ad_pod_id
string

The Ad Pod Id(s) of the ad/ads playing or about to be played in the video player. For Video Playback Started events only, you should send an Array of unique ad pod IDs. For all other playback events, you should send a string with the ID of the current ad pod playing at the time of the event.

ad_type
string
Enum: "pre-roll" "mid-roll" "post-roll"

The type of ad playing at the time of the event. Values can include pre-roll, mid-roll, and post-roll.

position
integer

The current index position in seconds of the playhead, including the duration of any ads seen (if available). If the playback is a livestream, check the documentation for relevant destinations for details on how to correctly pass the playhead position.

total_length
integer

The total duration of the playback in seconds. This should include the duration of all your content and ad included in this playback session. For livestream playback, send null.

bitrate
integer

The current kbps.

framerate
integer

The average frames per second (fps).

video_player
string

The name of the video player the client uses, like youtube or vimeo.

sound
integer [ 0 .. 100 ]

The current volume of the video player as a value between 1 and 100.

full_screen
boolean

If true, playback is in fullscreen mode.

ad_enabled
boolean

Set to true if a viewer can see your ads. You'd set false if a viewer has ad block or other blockers enabled.

quality
string

The video quality of playback, like 480p or highres.

livestream
boolean

Set to true if the playback is a livestream.

{
  • "content_asset_ids": [
    • "string"
    ],
  • "content_pod_ids": [
    • "string"
    ],
  • "session_id": "string",
  • "ad_asset_id": "string",
  • "ad_pod_id": "string",
  • "ad_type": "pre-roll",
  • "position": 0,
  • "total_length": 0,
  • "bitrate": 0,
  • "framerate": 0,
  • "video_player": "string",
  • "sound": 100,
  • "full_screen": true,
  • "ad_enabled": true,
  • "quality": "string",
  • "livestream": true
}

Video playback paused

When a user pauses playback.

content_asset_id
string

The ID of the video a user interacted with.

content_pod_id
string

The ID of the content "pod" in a playback session. Imagine a video that contains content and an ad; that means the video contains two pods—one for the content and one for the ad. This is the specific piece of content that the user interacted with.

session_id
string

The unique ID of the overall session used to tie all events generated from a specific playback. This value should be the same across all playback, content, and ad events if they are from the same playback session.

ad_asset_id
string

The Ad Asset Id(s) of the ad/ads playing or about to be played in the video player. For Video Playback Started events only, you should send an Array of unique ad asset IDs. For all other playback events, you should send a string with the ID of the current ad asset playing at the time of the event.

ad_pod_id
string

The Ad Pod Id(s) of the ad/ads playing or about to be played in the video player. For Video Playback Started events only, you should send an Array of unique ad pod IDs. For all other playback events, you should send a string with the ID of the current ad pod playing at the time of the event.

ad_type
string
Enum: "pre-roll" "mid-roll" "post-roll"

The type of ad playing at the time of the event. Values can include pre-roll, mid-roll, and post-roll.

position
integer

The current index position in seconds of the playhead, including the duration of any ads seen (if available). If the playback is a livestream, check the documentation for relevant destinations for details on how to correctly pass the playhead position.

total_length
integer

The total duration of the playback in seconds. This should include the duration of all your content and ad included in this playback session. For livestream playback, send null.

bitrate
integer

The current kbps.

framerate
integer

The average frames per second (fps).

video_player
string

The name of the video player the client uses, like youtube or vimeo.

sound
integer [ 0 .. 100 ]

The current volume of the video player as a value between 1 and 100.

full_screen
boolean

If true, playback is in fullscreen mode.

ad_enabled
boolean

Set to true if a viewer can see your ads. You'd set false if a viewer has ad block or other blockers enabled.

quality
string

The video quality of playback, like 480p or highres.

livestream
boolean

Set to true if the playback is a livestream.

{
  • "content_asset_id": "string",
  • "content_pod_id": "string",
  • "session_id": "string",
  • "ad_asset_id": "string",
  • "ad_pod_id": "string",
  • "ad_type": "pre-roll",
  • "position": 0,
  • "total_length": 0,
  • "bitrate": 0,
  • "framerate": 0,
  • "video_player": "string",
  • "sound": 100,
  • "full_screen": true,
  • "ad_enabled": true,
  • "quality": "string",
  • "livestream": true
}

Video playback interrupted

When a user is watching a video and playback is interrupted by an error, network loss, or buffering. With this event, you can send a method to indicate the reason for the interruption.

method
string

For Video Playback Interrupted events only, you can send this property denoting how the playback was interrupted (such as browser redirect, device lock, or call).

content_asset_id
string

The ID of the video a user interacted with.

content_pod_id
string

The ID of the content "pod" in a playback session. Imagine a video that contains content and an ad; that means the video contains two pods—one for the content and one for the ad. This is the specific piece of content that the user interacted with.

session_id
string

The unique ID of the overall session used to tie all events generated from a specific playback. This value should be the same across all playback, content, and ad events if they are from the same playback session.

ad_asset_id
string

The Ad Asset Id(s) of the ad/ads playing or about to be played in the video player. For Video Playback Started events only, you should send an Array of unique ad asset IDs. For all other playback events, you should send a string with the ID of the current ad asset playing at the time of the event.

ad_pod_id
string

The Ad Pod Id(s) of the ad/ads playing or about to be played in the video player. For Video Playback Started events only, you should send an Array of unique ad pod IDs. For all other playback events, you should send a string with the ID of the current ad pod playing at the time of the event.

ad_type
string
Enum: "pre-roll" "mid-roll" "post-roll"

The type of ad playing at the time of the event. Values can include pre-roll, mid-roll, and post-roll.

position
integer

The current index position in seconds of the playhead, including the duration of any ads seen (if available). If the playback is a livestream, check the documentation for relevant destinations for details on how to correctly pass the playhead position.

total_length
integer

The total duration of the playback in seconds. This should include the duration of all your content and ad included in this playback session. For livestream playback, send null.

bitrate
integer

The current kbps.

framerate
integer

The average frames per second (fps).

video_player
string

The name of the video player the client uses, like youtube or vimeo.

sound
integer [ 0 .. 100 ]

The current volume of the video player as a value between 1 and 100.

full_screen
boolean

If true, playback is in fullscreen mode.

ad_enabled
boolean

Set to true if a viewer can see your ads. You'd set false if a viewer has ad block or other blockers enabled.

quality
string

The video quality of playback, like 480p or highres.

livestream
boolean

Set to true if the playback is a livestream.

{
  • "method": "string",
  • "content_asset_id": "string",
  • "content_pod_id": "string",
  • "session_id": "string",
  • "ad_asset_id": "string",
  • "ad_pod_id": "string",
  • "ad_type": "pre-roll",
  • "position": 0,
  • "total_length": 0,
  • "bitrate": 0,
  • "framerate": 0,
  • "video_player": "string",
  • "sound": 100,
  • "full_screen": true,
  • "ad_enabled": true,
  • "quality": "string",
  • "livestream": true
}

Video playback buffer started

Send this event when playback begins buffering content or an ad.

content_asset_id
string

The ID of the video a user interacted with.

content_pod_id
string

The ID of the content "pod" in a playback session. Imagine a video that contains content and an ad; that means the video contains two pods—one for the content and one for the ad. This is the specific piece of content that the user interacted with.

session_id
string

The unique ID of the overall session used to tie all events generated from a specific playback. This value should be the same across all playback, content, and ad events if they are from the same playback session.

ad_asset_id
string

The Ad Asset Id(s) of the ad/ads playing or about to be played in the video player. For Video Playback Started events only, you should send an Array of unique ad asset IDs. For all other playback events, you should send a string with the ID of the current ad asset playing at the time of the event.

ad_pod_id
string

The Ad Pod Id(s) of the ad/ads playing or about to be played in the video player. For Video Playback Started events only, you should send an Array of unique ad pod IDs. For all other playback events, you should send a string with the ID of the current ad pod playing at the time of the event.

ad_type
string
Enum: "pre-roll" "mid-roll" "post-roll"

The type of ad playing at the time of the event. Values can include pre-roll, mid-roll, and post-roll.

position
integer

The current index position in seconds of the playhead, including the duration of any ads seen (if available). If the playback is a livestream, check the documentation for relevant destinations for details on how to correctly pass the playhead position.

total_length
integer

The total duration of the playback in seconds. This should include the duration of all your content and ad included in this playback session. For livestream playback, send null.

bitrate
integer

The current kbps.

framerate
integer

The average frames per second (fps).

video_player
string

The name of the video player the client uses, like youtube or vimeo.

sound
integer [ 0 .. 100 ]

The current volume of the video player as a value between 1 and 100.

full_screen
boolean

If true, playback is in fullscreen mode.

ad_enabled
boolean

Set to true if a viewer can see your ads. You'd set false if a viewer has ad block or other blockers enabled.

quality
string

The video quality of playback, like 480p or highres.

livestream
boolean

Set to true if the playback is a livestream.

{
  • "content_asset_id": "string",
  • "content_pod_id": "string",
  • "session_id": "string",
  • "ad_asset_id": "string",
  • "ad_pod_id": "string",
  • "ad_type": "pre-roll",
  • "position": 0,
  • "total_length": 0,
  • "bitrate": 0,
  • "framerate": 0,
  • "video_player": "string",
  • "sound": 100,
  • "full_screen": true,
  • "ad_enabled": true,
  • "quality": "string",
  • "livestream": true
}

Video playback buffer completed

Send this event when buffering finishes.

content_asset_id
string

The ID of the video a user interacted with.

content_pod_id
string

The ID of the content "pod" in a playback session. Imagine a video that contains content and an ad; that means the video contains two pods—one for the content and one for the ad. This is the specific piece of content that the user interacted with.

session_id
string

The unique ID of the overall session used to tie all events generated from a specific playback. This value should be the same across all playback, content, and ad events if they are from the same playback session.

ad_asset_id
string

The Ad Asset Id(s) of the ad/ads playing or about to be played in the video player. For Video Playback Started events only, you should send an Array of unique ad asset IDs. For all other playback events, you should send a string with the ID of the current ad asset playing at the time of the event.

ad_pod_id
string

The Ad Pod Id(s) of the ad/ads playing or about to be played in the video player. For Video Playback Started events only, you should send an Array of unique ad pod IDs. For all other playback events, you should send a string with the ID of the current ad pod playing at the time of the event.

ad_type
string
Enum: "pre-roll" "mid-roll" "post-roll"

The type of ad playing at the time of the event. Values can include pre-roll, mid-roll, and post-roll.

position
integer

The current index position in seconds of the playhead, including the duration of any ads seen (if available). If the playback is a livestream, check the documentation for relevant destinations for details on how to correctly pass the playhead position.

total_length
integer

The total duration of the playback in seconds. This should include the duration of all your content and ad included in this playback session. For livestream playback, send null.

bitrate
integer

The current kbps.

framerate
integer

The average frames per second (fps).

video_player
string

The name of the video player the client uses, like youtube or vimeo.

sound
integer [ 0 .. 100 ]

The current volume of the video player as a value between 1 and 100.

full_screen
boolean

If true, playback is in fullscreen mode.

ad_enabled
boolean

Set to true if a viewer can see your ads. You'd set false if a viewer has ad block or other blockers enabled.

quality
string

The video quality of playback, like 480p or highres.

livestream
boolean

Set to true if the playback is a livestream.

{
  • "content_asset_id": "string",
  • "content_pod_id": "string",
  • "session_id": "string",
  • "ad_asset_id": "string",
  • "ad_pod_id": "string",
  • "ad_type": "pre-roll",
  • "position": 0,
  • "total_length": 0,
  • "bitrate": 0,
  • "framerate": 0,
  • "video_player": "string",
  • "sound": 100,
  • "full_screen": true,
  • "ad_enabled": true,
  • "quality": "string",
  • "livestream": true
}

Video playback seek started

Send this event when a user begins seeking to a new position in the video. Use position to show where the user begins seeking from and seek_position to capture where the user ends.

content_asset_id
string

The ID of the video a user interacted with.

content_pod_id
string

The ID of the content "pod" in a playback session. Imagine a video that contains content and an ad; that means the video contains two pods—one for the content and one for the ad. This is the specific piece of content that the user interacted with.

session_id
string

The unique ID of the overall session used to tie all events generated from a specific playback. This value should be the same across all playback, content, and ad events if they are from the same playback session.

ad_asset_id
string

The Ad Asset Id(s) of the ad/ads playing or about to be played in the video player. For Video Playback Started events only, you should send an Array of unique ad asset IDs. For all other playback events, you should send a string with the ID of the current ad asset playing at the time of the event.

ad_pod_id
string

The Ad Pod Id(s) of the ad/ads playing or about to be played in the video player. For Video Playback Started events only, you should send an Array of unique ad pod IDs. For all other playback events, you should send a string with the ID of the current ad pod playing at the time of the event.

ad_type
string
Enum: "pre-roll" "mid-roll" "post-roll"

The type of ad playing at the time of the event. Values can include pre-roll, mid-roll, and post-roll.

position
integer

The current index position in seconds of the playhead, including the duration of any ads seen (if available). If the playback is a livestream, check the documentation for relevant destinations for details on how to correctly pass the playhead position.

total_length
integer

The total duration of the playback in seconds. This should include the duration of all your content and ad included in this playback session. For livestream playback, send null.

bitrate
integer

The current kbps.

framerate
integer

The average frames per second (fps).

video_player
string

The name of the video player the client uses, like youtube or vimeo.

sound
integer [ 0 .. 100 ]

The current volume of the video player as a value between 1 and 100.

full_screen
boolean

If true, playback is in fullscreen mode.

ad_enabled
boolean

Set to true if a viewer can see your ads. You'd set false if a viewer has ad block or other blockers enabled.

quality
string

The video quality of playback, like 480p or highres.

livestream
boolean

Set to true if the playback is a livestream.

{
  • "content_asset_id": "string",
  • "content_pod_id": "string",
  • "session_id": "string",
  • "ad_asset_id": "string",
  • "ad_pod_id": "string",
  • "ad_type": "pre-roll",
  • "position": 0,
  • "total_length": 0,
  • "bitrate": 0,
  • "framerate": 0,
  • "video_player": "string",
  • "sound": 100,
  • "full_screen": true,
  • "ad_enabled": true,
  • "quality": "string",
  • "livestream": true
}

Video playback seek completed

After a user manually seeks to a certain position of the content or ad in the playback. Pass in the position property to denote where the user desires to begin the playback from.

content_asset_id
string

The ID of the video a user interacted with.

content_pod_id
string

The ID of the content "pod" in a playback session. Imagine a video that contains content and an ad; that means the video contains two pods—one for the content and one for the ad. This is the specific piece of content that the user interacted with.

session_id
string

The unique ID of the overall session used to tie all events generated from a specific playback. This value should be the same across all playback, content, and ad events if they are from the same playback session.

ad_asset_id
string

The Ad Asset Id(s) of the ad/ads playing or about to be played in the video player. For Video Playback Started events only, you should send an Array of unique ad asset IDs. For all other playback events, you should send a string with the ID of the current ad asset playing at the time of the event.

ad_pod_id
string

The Ad Pod Id(s) of the ad/ads playing or about to be played in the video player. For Video Playback Started events only, you should send an Array of unique ad pod IDs. For all other playback events, you should send a string with the ID of the current ad pod playing at the time of the event.

ad_type
string
Enum: "pre-roll" "mid-roll" "post-roll"

The type of ad playing at the time of the event. Values can include pre-roll, mid-roll, and post-roll.

position
integer

The current index position in seconds of the playhead, including the duration of any ads seen (if available). If the playback is a livestream, check the documentation for relevant destinations for details on how to correctly pass the playhead position.

total_length
integer

The total duration of the playback in seconds. This should include the duration of all your content and ad included in this playback session. For livestream playback, send null.

bitrate
integer

The current kbps.

framerate
integer

The average frames per second (fps).

video_player
string

The name of the video player the client uses, like youtube or vimeo.

sound
integer [ 0 .. 100 ]

The current volume of the video player as a value between 1 and 100.

full_screen
boolean

If true, playback is in fullscreen mode.

ad_enabled
boolean

Set to true if a viewer can see your ads. You'd set false if a viewer has ad block or other blockers enabled.

quality
string

The video quality of playback, like 480p or highres.

livestream
boolean

Set to true if the playback is a livestream.

{
  • "content_asset_id": "string",
  • "content_pod_id": "string",
  • "session_id": "string",
  • "ad_asset_id": "string",
  • "ad_pod_id": "string",
  • "ad_type": "pre-roll",
  • "position": 0,
  • "total_length": 0,
  • "bitrate": 0,
  • "framerate": 0,
  • "video_player": "string",
  • "sound": 100,
  • "full_screen": true,
  • "ad_enabled": true,
  • "quality": "string",
  • "livestream": true
}

Video playback resumed

Send this event when a user resumes playback after they previously paused playback.

content_asset_id
string

The ID of the video a user interacted with.

content_pod_id
string

The ID of the content "pod" in a playback session. Imagine a video that contains content and an ad; that means the video contains two pods—one for the content and one for the ad. This is the specific piece of content that the user interacted with.

session_id
string

The unique ID of the overall session used to tie all events generated from a specific playback. This value should be the same across all playback, content, and ad events if they are from the same playback session.

ad_asset_id
string

The Ad Asset Id(s) of the ad/ads playing or about to be played in the video player. For Video Playback Started events only, you should send an Array of unique ad asset IDs. For all other playback events, you should send a string with the ID of the current ad asset playing at the time of the event.

ad_pod_id
string

The Ad Pod Id(s) of the ad/ads playing or about to be played in the video player. For Video Playback Started events only, you should send an Array of unique ad pod IDs. For all other playback events, you should send a string with the ID of the current ad pod playing at the time of the event.

ad_type
string
Enum: "pre-roll" "mid-roll" "post-roll"

The type of ad playing at the time of the event. Values can include pre-roll, mid-roll, and post-roll.

position
integer

The current index position in seconds of the playhead, including the duration of any ads seen (if available). If the playback is a livestream, check the documentation for relevant destinations for details on how to correctly pass the playhead position.

total_length
integer

The total duration of the playback in seconds. This should include the duration of all your content and ad included in this playback session. For livestream playback, send null.

bitrate
integer

The current kbps.

framerate
integer

The average frames per second (fps).

video_player
string

The name of the video player the client uses, like youtube or vimeo.

sound
integer [ 0 .. 100 ]

The current volume of the video player as a value between 1 and 100.

full_screen
boolean

If true, playback is in fullscreen mode.

ad_enabled
boolean

Set to true if a viewer can see your ads. You'd set false if a viewer has ad block or other blockers enabled.

quality
string

The video quality of playback, like 480p or highres.

livestream
boolean

Set to true if the playback is a livestream.

{
  • "content_asset_id": "string",
  • "content_pod_id": "string",
  • "session_id": "string",
  • "ad_asset_id": "string",
  • "ad_pod_id": "string",
  • "ad_type": "pre-roll",
  • "position": 0,
  • "total_length": 0,
  • "bitrate": 0,
  • "framerate": 0,
  • "video_player": "string",
  • "sound": 100,
  • "full_screen": true,
  • "ad_enabled": true,
  • "quality": "string",
  • "livestream": true
}

Video playback completed

Send this event when a user finishes a playback session.

content_asset_id
string

The ID of the video a user interacted with.

content_pod_id
string

The ID of the content "pod" in a playback session. Imagine a video that contains content and an ad; that means the video contains two pods—one for the content and one for the ad. This is the specific piece of content that the user interacted with.

session_id
string

The unique ID of the overall session used to tie all events generated from a specific playback. This value should be the same across all playback, content, and ad events if they are from the same playback session.

ad_asset_id
string

The Ad Asset Id(s) of the ad/ads playing or about to be played in the video player. For Video Playback Started events only, you should send an Array of unique ad asset IDs. For all other playback events, you should send a string with the ID of the current ad asset playing at the time of the event.

ad_pod_id
string

The Ad Pod Id(s) of the ad/ads playing or about to be played in the video player. For Video Playback Started events only, you should send an Array of unique ad pod IDs. For all other playback events, you should send a string with the ID of the current ad pod playing at the time of the event.

ad_type
string
Enum: "pre-roll" "mid-roll" "post-roll"

The type of ad playing at the time of the event. Values can include pre-roll, mid-roll, and post-roll.

position
integer

The current index position in seconds of the playhead, including the duration of any ads seen (if available). If the playback is a livestream, check the documentation for relevant destinations for details on how to correctly pass the playhead position.

total_length
integer

The total duration of the playback in seconds. This should include the duration of all your content and ad included in this playback session. For livestream playback, send null.

bitrate
integer

The current kbps.

framerate
integer

The average frames per second (fps).

video_player
string

The name of the video player the client uses, like youtube or vimeo.

sound
integer [ 0 .. 100 ]

The current volume of the video player as a value between 1 and 100.

full_screen
boolean

If true, playback is in fullscreen mode.

ad_enabled
boolean

Set to true if a viewer can see your ads. You'd set false if a viewer has ad block or other blockers enabled.

quality
string

The video quality of playback, like 480p or highres.

livestream
boolean

Set to true if the playback is a livestream.

{
  • "content_asset_id": "string",
  • "content_pod_id": "string",
  • "session_id": "string",
  • "ad_asset_id": "string",
  • "ad_pod_id": "string",
  • "ad_type": "pre-roll",
  • "position": 0,
  • "total_length": 0,
  • "bitrate": 0,
  • "framerate": 0,
  • "video_player": "string",
  • "sound": 100,
  • "full_screen": true,
  • "ad_enabled": true,
  • "quality": "string",
  • "livestream": true
}

Video playback exited

Send this event when a user navigates away from a playback/stream (scrolls out of view, goes to a different page, etc).

content_asset_id
string

The ID of the video a user interacted with.

content_pod_id
string

The ID of the content "pod" in a playback session. Imagine a video that contains content and an ad; that means the video contains two pods—one for the content and one for the ad. This is the specific piece of content that the user interacted with.

session_id
string

The unique ID of the overall session used to tie all events generated from a specific playback. This value should be the same across all playback, content, and ad events if they are from the same playback session.

ad_asset_id
string

The Ad Asset Id(s) of the ad/ads playing or about to be played in the video player. For Video Playback Started events only, you should send an Array of unique ad asset IDs. For all other playback events, you should send a string with the ID of the current ad asset playing at the time of the event.

ad_pod_id
string

The Ad Pod Id(s) of the ad/ads playing or about to be played in the video player. For Video Playback Started events only, you should send an Array of unique ad pod IDs. For all other playback events, you should send a string with the ID of the current ad pod playing at the time of the event.

ad_type
string
Enum: "pre-roll" "mid-roll" "post-roll"

The type of ad playing at the time of the event. Values can include pre-roll, mid-roll, and post-roll.

position
integer

The current index position in seconds of the playhead, including the duration of any ads seen (if available). If the playback is a livestream, check the documentation for relevant destinations for details on how to correctly pass the playhead position.

total_length
integer

The total duration of the playback in seconds. This should include the duration of all your content and ad included in this playback session. For livestream playback, send null.

bitrate
integer

The current kbps.

framerate
integer

The average frames per second (fps).

video_player
string

The name of the video player the client uses, like youtube or vimeo.

sound
integer [ 0 .. 100 ]

The current volume of the video player as a value between 1 and 100.

full_screen
boolean

If true, playback is in fullscreen mode.

ad_enabled
boolean

Set to true if a viewer can see your ads. You'd set false if a viewer has ad block or other blockers enabled.

quality
string

The video quality of playback, like 480p or highres.

livestream
boolean

Set to true if the playback is a livestream.

{
  • "content_asset_id": "string",
  • "content_pod_id": "string",
  • "session_id": "string",
  • "ad_asset_id": "string",
  • "ad_pod_id": "string",
  • "ad_type": "pre-roll",
  • "position": 0,
  • "total_length": 0,
  • "bitrate": 0,
  • "framerate": 0,
  • "video_player": "string",
  • "sound": 100,
  • "full_screen": true,
  • "ad_enabled": true,
  • "quality": "string",
  • "livestream": true
}

Video content started

Send this event when a user begins watching a video content within a playback session.

session_id
string

The unique ID of the overall session used to tie all events generated from a specific playback. This value should be the same across all playback, content, and ad events if they are from the same playback session.

asset_id
string

The ID of the video a user interacted with.

pod_id
string

The ID of the content "pod" in a playback session. Imagine a video that contains content and an ad; that means the video contains two pods—one for the content and one for the ad. This is the specific piece of content that the user interacted with.

program
string

The name of the program or show the content belongs to (if applicable).

title
string

The title of the video content/pod.

description
string

The description of the video content/pod.

season
string

The season the video content/pod belongs to, if applicable.

position
integer

The current index position in seconds of the playhead, including the duration of any ads seen (if available). If the playback is a livestream, check the documentation for relevant destinations for details on how to correctly pass the playhead position.

total_length
integer

The total duration of the content/asset in seconds. Note that this is not the duration of the video itself or the playback, but a piece of a complete "pod" of content. If the content is an ad in the video, this is the length of the ad.

genre
string

The genre of the video content/pod.

publisher
string

The publisher of the video content/pod.

channel
string

The channel the video content/pod belongs to or is aired on, like hgtv or my_youtube_channel.

full_episode
boolean

Set to true if the content is a full episode of a show.

livestream
boolean

Set to true if the content is a livestream.

airdate
string <date-time>

The ISO-8601 date-time when the video content/pod originally aired or was published.

bitrate
integer

The current kbps.

framerate
integer

The average frames per second (fps).

keywords
Array of strings

Keywords associated with the video content/pod.

{
  • "session_id": "string",
  • "asset_id": "string",
  • "pod_id": "string",
  • "program": "string",
  • "title": "string",
  • "description": "string",
  • "season": "string",
  • "position": 0,
  • "total_length": 0,
  • "genre": "string",
  • "publisher": "string",
  • "channel": "string",
  • "full_episode": true,
  • "livestream": true,
  • "airdate": "2019-08-24T14:15:22Z",
  • "bitrate": 0,
  • "framerate": 0,
  • "keywords": [
    • "string"
    ]
}

Video content playing

Send this event as a heartbeat on a regular interval to track how far into the video a person is (indicated by the position).

session_id
string

The unique ID of the overall session used to tie all events generated from a specific playback. This value should be the same across all playback, content, and ad events if they are from the same playback session.

asset_id
string

The ID of the video a user interacted with.

pod_id
string

The ID of the content "pod" in a playback session. Imagine a video that contains content and an ad; that means the video contains two pods—one for the content and one for the ad. This is the specific piece of content that the user interacted with.

program
string

The name of the program or show the content belongs to (if applicable).

title
string

The title of the video content/pod.

description
string

The description of the video content/pod.

season
string

The season the video content/pod belongs to, if applicable.

position
integer

The current index position in seconds of the playhead, including the duration of any ads seen (if available). If the playback is a livestream, check the documentation for relevant destinations for details on how to correctly pass the playhead position.

total_length
integer

The total duration of the content/asset in seconds. Note that this is not the duration of the video itself or the playback, but a piece of a complete "pod" of content. If the content is an ad in the video, this is the length of the ad.

genre
string

The genre of the video content/pod.

publisher
string

The publisher of the video content/pod.

channel
string

The channel the video content/pod belongs to or is aired on, like hgtv or my_youtube_channel.

full_episode
boolean

Set to true if the content is a full episode of a show.

livestream
boolean

Set to true if the content is a livestream.

airdate
string <date-time>

The ISO-8601 date-time when the video content/pod originally aired or was published.

bitrate
integer

The current kbps.

framerate
integer

The average frames per second (fps).

keywords
Array of strings

Keywords associated with the video content/pod.

{
  • "session_id": "string",
  • "asset_id": "string",
  • "pod_id": "string",
  • "program": "string",
  • "title": "string",
  • "description": "string",
  • "season": "string",
  • "position": 0,
  • "total_length": 0,
  • "genre": "string",
  • "publisher": "string",
  • "channel": "string",
  • "full_episode": true,
  • "livestream": true,
  • "airdate": "2019-08-24T14:15:22Z",
  • "bitrate": 0,
  • "framerate": 0,
  • "keywords": [
    • "string"
    ]
}

Video content completed

Send this event when a user finishes watching a video content within a playback session—position and total_length are equal.

session_id
string

The unique ID of the overall session used to tie all events generated from a specific playback. This value should be the same across all playback, content, and ad events if they are from the same playback session.

asset_id
string

The ID of the video a user interacted with.

pod_id
string

The ID of the content "pod" in a playback session. Imagine a video that contains content and an ad; that means the video contains two pods—one for the content and one for the ad. This is the specific piece of content that the user interacted with.

program
string

The name of the program or show the content belongs to (if applicable).

title
string

The title of the video content/pod.

description
string

The description of the video content/pod.

season
string

The season the video content/pod belongs to, if applicable.

position
integer

The current index position in seconds of the playhead, including the duration of any ads seen (if available). If the playback is a livestream, check the documentation for relevant destinations for details on how to correctly pass the playhead position.

total_length
integer

The total duration of the content/asset in seconds. Note that this is not the duration of the video itself or the playback, but a piece of a complete "pod" of content. If the content is an ad in the video, this is the length of the ad.

genre
string

The genre of the video content/pod.

publisher
string

The publisher of the video content/pod.

channel
string

The channel the video content/pod belongs to or is aired on, like hgtv or my_youtube_channel.

full_episode
boolean

Set to true if the content is a full episode of a show.

livestream
boolean

Set to true if the content is a livestream.

airdate
string <date-time>

The ISO-8601 date-time when the video content/pod originally aired or was published.

bitrate
integer

The current kbps.

framerate
integer

The average frames per second (fps).

keywords
Array of strings

Keywords associated with the video content/pod.

{
  • "session_id": "string",
  • "asset_id": "string",
  • "pod_id": "string",
  • "program": "string",
  • "title": "string",
  • "description": "string",
  • "season": "string",
  • "position": 0,
  • "total_length": 0,
  • "genre": "string",
  • "publisher": "string",
  • "channel": "string",
  • "full_episode": true,
  • "livestream": true,
  • "airdate": "2019-08-24T14:15:22Z",
  • "bitrate": 0,
  • "framerate": 0,
  • "keywords": [
    • "string"
    ]
}

Video ad started

Send this event when a user begins watching an ad within a playback session.

Video ad playing

Send this event as a heartbeat on a regular interval to track how far into the ad a person is (indicated by the position).

session_id
string

The unique ID of the overall session used to tie all events generated from a specific playback. This value should be the same across all playback, content, and ad events if they are from the same playback session.

asset_id
string

The ID of the video a user interacted with.

pod_id
string

The ID of the content "pod" in a playback session. Imagine a video that contains content and an ad; that means the video contains two pods—one for the content and one for the ad. This is the specific piece of content that the user interacted with.

pod_position
integer

The position of the pod/asset relative to other assets in the same pod. If your ad pod plays 3 ads, you would indicate if this is add number 1, 2, or 3.

pod_length
integer

The number of ad assets in the ad-pod

type
string
Enum: "pre-roll" "mid-roll" "post-roll"

The ad type. Values can include pre-roll, mid-roll, and post-roll.

title
string

The title of the ad.

position
integer

The current index position in seconds of the playhead, with respect to the length of the ad.

total_length
integer

The total duration of the ad in seconds.

publisher
string

The ad's publisher.

load_type
string
Enum: "dynamic" "linear"

Set to dynamic if you insert ads dynamically and linear if ads are the same for all viewers.

content
object

For video destinations that require you to send content metadata with ad events, you can send all the content metadata in this object—like content.title, etc.

quartile
integer

Specifies the quartile of the ad that a viewer reached. If you use our client-side libraries, we'll automatically track this for you.

{
  • "session_id": "string",
  • "asset_id": "string",
  • "pod_id": "string",
  • "pod_position": 0,
  • "pod_length": 0,
  • "type": "pre-roll",
  • "title": "string",
  • "position": 0,
  • "total_length": 0,
  • "publisher": "string",
  • "load_type": "dynamic",
  • "content": { },
  • "quartile": 0
}

Video ad completed

Send this event when a user finishes watching an ad within a playback session—position and total_length are equal.

Identify

Identifies a person and assigns traits to them.

In most cases, you'll identify people with a userId or an anonymousId. But when you use Customer.io as a destination, you can pass an empty userId or anonymousId, and identify people by their email trait.

When you use our libraries, you'll typically only provide an ID and traits. The libraries fill in the rest of the payload automatically.

Authorization:
Request Body: application/json
One of
userId
required
string

The unique identifier for a person. This value should be unique across systems, so you recognize the same person in your sources and destinations.

anonymousId
string

A unique substitute for a User ID in cases when you don’t have an absolutely unique identifier. Our libraries generate this value automatically to help you track people before they sign up, log in, provide their email, etc.

object

Additional properties that you know about a person. We've listed some common/reserved traits below, but you can add any traits that you might use in another system.

object

Contains a list of booleans indicating the integrations that are enabled (true) or disabled (false). By default, all integrations are enabled (returning an empty object). Set "All": false to reverse this behavior.

messageId
string

A unique identifier for a Data Pipelines call, ensuring that each individual event is unique. This is set by Customer.io

sentAt
string <date-time>

The ISO-8601 timestamp when a library sends an event to Data Pipelines.

originalTimestamp
string <date-time>

In general, you can use timestamp rather than this field if you want to back-date events. This is the timestamp on the client device you invoke a call or the timestamp value you manually passed in a server-side library call.

timestamp
string <date-time>

The ISO-8601 timestamp when the event originally took place. This is mostly useful when you backfill past events. If you're not backfilling data, you can leave this field empty and we'll use the current time or server time.

object

A dictionary of context about a source call/event, like the user’s IP address or locale. Context is automatically collected by our source libraries.

Responses

Request samples

Content type
application/json
Example
{
  • "userId": "97980cfea0067",
  • "anonymousId": "c0e5cae6-6f04-46e4-97a8-25076e8bdc0b",
  • "traits": {
    • "email": "cool.person@example.com",
    • "createdAt": "2019-08-24T14:15:22Z",
    • "Additional Traits1": null,
    • "Additional Traits2": null,
    • "name": "Cool Person",
    • "likes_baseball": true,
    • "games_attended": 5
    },
  • "integrations": {
    • "All": true,
    • "Salesforce": false
    },
  • "messageId": "string",
  • "sentAt": "2019-08-24T14:15:22Z",
  • "originalTimestamp": "2019-08-24T14:15:22Z",
  • "timestamp": "2019-08-24T14:15:22Z",
  • "context": {
    • "active": true,
    • "ip": "string",
    • "locale": "string",
    • "userAgent": "string",
    • "channel": "browser",
    • "campaign": {
      },
    • "page": {
      }
    },
  • "type": "identify"
}

Track

Send an event associated with a person. The track call is how you record the things that people do on your website or in your app.

With each event, you'll send an event name, and a dictionary of properties that you want to record for the event. For example, if someone added a product to a cart, you might call your event added_to_cart with properties about the item added the the cart, quantity, price, etc. We automatically trim leading and trailing spaces from event names.

When you use our libraries, you'll typically only provide an event, an ID for the person, and properties. The libraries fill in the rest of the payload automatically.

Authorization:
Request Body: application/json
One of
userId
required
string

The unique identifier for a person. This value should be unique across systems, so you recognize the same person in your sources and destinations.

event
required
string

The name of the event

object

Additional properties for your event.

object

Contains a list of booleans indicating the integrations that are enabled (true) or disabled (false). By default, all integrations are enabled (returning an empty object). Set "All": false to reverse this behavior.

messageId
string

A unique identifier for a Data Pipelines call, ensuring that each individual event is unique. This is set by Customer.io

sentAt
string <date-time>

The ISO-8601 timestamp when a library sends an event to Data Pipelines.

originalTimestamp
string <date-time>

In general, you can use timestamp rather than this field if you want to back-date events. This is the timestamp on the client device you invoke a call or the timestamp value you manually passed in a server-side library call.

timestamp
string <date-time>

The ISO-8601 timestamp when the event originally took place. This is mostly useful when you backfill past events. If you're not backfilling data, you can leave this field empty and we'll use the current time or server time.

object

A dictionary of context about a source call/event, like the user’s IP address or locale. Context is automatically collected by our source libraries.

Responses

Request samples

Content type
application/json
Example
{
  • "userId": "AiUGstSDIg",
  • "event": "Course Started",
  • "properties": {
    • "Event Properties1": null,
    • "Event Properties2": null,
    • "title": "Intro to Customer.io"
    },
  • "integrations": null,
  • "messageId": "ajs-f8ca1e4de5024d9430b3928bd8ac6b96",
  • "sentAt": "2015-12-12T19:11:01.169Z",
  • "originalTimestamp": "2015-12-12T19:11:01.152Z",
  • "timestamp": "2015-12-12T19:11:01.249Z",
  • "context": {
    • "active": true,
    • "ip": "108.0.78.21",
    • "locale": "string",
    • "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_11_0) AppleWebKit/537.36 (KHTML like Gecko) Chrome/46.0.2490.86 Safari/537.36",
    • "channel": "browser",
    • "campaign": {
      },
    • "page": {},
    • "library": {
      }
    },
  • "anonymousId": "23adfd82-aa0f-45a7-a756-24f2a7a4c895",
  • "receivedAt": "2015-12-12T19:11:01.266Z",
  • "type": "track"
}

Page

Sends a page view event. If you use our JavaScript source, it automatically records page events whenever it loads (every page). If you use a single-page app, you'll need to call the page method people change routes.

The request consists of the page name and additional properties about the page.

If you use our JavaScript library, the page name and URL are automatically gathered and passed as event properties.

When you use our libraries, you'll typically only provide a user ID/anonymous ID and the name of the page. The libraries fill in the rest of the payload automatically.

Authorization:
Request Body: application/json
One of
userId
required
string

The unique identifier for a person. This value should be unique across systems, so you recognize the same person in your sources and destinations.

name
string

The name of the page.

object

Additional page properties. Analytics.js automatically collects url, title, referrer, path, and search properties. But, if you use our other sources or you write your own integration, you should consider sending these properties yourself. Destination actions that take page events often rely on the url and title properties.

object

Contains a list of booleans indicating the integrations that are enabled (true) or disabled (false). By default, all integrations are enabled (returning an empty object). Set "All": false to reverse this behavior.

messageId
string

A unique identifier for a Data Pipelines call, ensuring that each individual event is unique. This is set by Customer.io

sentAt
string <date-time>

The ISO-8601 timestamp when a library sends an event to Data Pipelines.

originalTimestamp
string <date-time>

In general, you can use timestamp rather than this field if you want to back-date events. This is the timestamp on the client device you invoke a call or the timestamp value you manually passed in a server-side library call.

timestamp
string <date-time>

The ISO-8601 timestamp when the event originally took place. This is mostly useful when you backfill past events. If you're not backfilling data, you can leave this field empty and we'll use the current time or server time.

object

A dictionary of context about a source call/event, like the user’s IP address or locale. Context is automatically collected by our source libraries.

Responses

Request samples

Content type
application/json
Example
{
  • "userId": "97980cfea0067",
  • "name": "Home",
  • "properties": {},
  • "integrations": {
    • "All": true,
    • "Salesforce": false,
    • "Mixpanel": false
    },
  • "messageId": "022bb90c-bbac-11e4-8dfc-aa07a5b093db",
  • "sentAt": "2015-02-23T22:28:55.111Z",
  • "originalTimestamp": "2019-08-24T14:15:22Z",
  • "timestamp": "2015-02-23T22:28:55.111Z",
  • "context": {
    • "active": true,
    • "ip": "8.8.8.8",
    • "locale": "string",
    • "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_9_5) AppleWebKit/537.36 (KHTML like Gecko) Chrome/40.0.2214.115 Safari/537.36",
    • "channel": "browser",
    • "campaign": {
      },
    • "page": {
      }
    },
  • "anonymousId": "507f191e810c19729de860ea",
  • "channel": "browser",
  • "receivedAt": "2015-02-23T22:28:55.387Z",
  • "type": "page",
  • "version": 1.1
}

Screen

Sends a screen view event for mobile devices. Screen events help you understand the screens that people use in your app. You should send a screen call whenever a user requests a page of your app.

Authorization:
Request Body: application/json
One of
userId
required
string

The unique identifier for a person. This value should be unique across systems, so you recognize the same person in your sources and destinations.

name
string

The name of the screen the person visited.

object

Additional properties for your screen.

object

Contains a list of booleans indicating the integrations that are enabled (true) or disabled (false). By default, all integrations are enabled (returning an empty object). Set "All": false to reverse this behavior.

messageId
string

A unique identifier for a Data Pipelines call, ensuring that each individual event is unique. This is set by Customer.io

sentAt
string <date-time>

The ISO-8601 timestamp when a library sends an event to Data Pipelines.

originalTimestamp
string <date-time>

In general, you can use timestamp rather than this field if you want to back-date events. This is the timestamp on the client device you invoke a call or the timestamp value you manually passed in a server-side library call.

timestamp
string <date-time>

The ISO-8601 timestamp when the event originally took place. This is mostly useful when you backfill past events. If you're not backfilling data, you can leave this field empty and we'll use the current time or server time.

object

A dictionary of context about a source call/event, like the user’s IP address or locale. Context is automatically collected by our source libraries.

Responses

Request samples

Content type
application/json
Example
{
  • "userId": "97980cfea0067",
  • "name": "feed",
  • "properties": {
    • "Screen Properties1": null,
    • "Screen Properties2": null,
    • "subscriptions": [
      ]
    },
  • "integrations": {
    • "All": true,
    • "Salesforce": false
    },
  • "messageId": "022bb90c-bbac-11e4-8dfc-aa07a5b093db",
  • "sentAt": "2015-02-23T22:28:55.111Z",
  • "originalTimestamp": "2019-08-24T14:15:22Z",
  • "timestamp": "2015-02-23T22:28:55.111Z",
  • "context": {
    • "active": true,
    • "ip": "8.8.8.8",
    • "locale": "string",
    • "userAgent": "string",
    • "channel": "browser",
    • "app": {
      },
    • "device": {
      },
    • "network": {
      },
    • "os": {
      }
    },
  • "anonymousId": "507f191e810c19729de860ea",
  • "receivedAt": "2015-02-23T22:28:55.387Z",
  • "type": "screen",
  • "version": 1.1
}

Group

Group calls add people to a group. Groups could be a companies, accounts, online classes, and so on. How groups are represented in your destination depends on the destination. Some destinations have concepts of "groups"; Customer.io's destination calls groups "objects."

When you use our libraries, you'll typically only provide an ID for the user, the groupId, and traits. The libraries fill in the rest of the payload automatically.

Authorization:
Request Body: application/json
One of
userId
string

The unique identifier for a person. This value should be unique across systems, so you recognize the same person in your sources and destinations.

groupId
string

ID of the group

objectTypeId
string

If you use Customer.io Journeys as a destination, this value is the type of group/object your group belongs to; object type IDs are stringified integers. If you don't include this value, we assume the object type ID is 1. See objects in Customer.io Journeys for more information.

You can include this value as objectTypeId at the top level of your payload or as object_type_id in the traits object.

object

Additional information about the group.

object

Contains a list of booleans indicating the integrations that are enabled (true) or disabled (false). By default, all integrations are enabled (returning an empty object). Set "All": false to reverse this behavior.

messageId
string

A unique identifier for a Data Pipelines call, ensuring that each individual event is unique. This is set by Customer.io

sentAt
string <date-time>

The ISO-8601 timestamp when a library sends an event to Data Pipelines.

originalTimestamp
string <date-time>

In general, you can use timestamp rather than this field if you want to back-date events. This is the timestamp on the client device you invoke a call or the timestamp value you manually passed in a server-side library call.

timestamp
string <date-time>

The ISO-8601 timestamp when the event originally took place. This is mostly useful when you backfill past events. If you're not backfilling data, you can leave this field empty and we'll use the current time or server time.

object

A dictionary of context about a source call/event, like the user’s IP address or locale. Context is automatically collected by our source libraries.

Responses

Request samples

Content type
application/json
Example
{
  • "userId": "97980cfea0067",
  • "groupId": "0e8c78ea9d97a7b8185e8632,",
  • "objectTypeId": "1",
  • "traits": {
    • "object_type_id": "1",
    • "Group Traits1": {
      },
    • "Group Traits2": {
      },
    • "name": "ACME, Inc.",
    • "industry": "Technology",
    • "employees": 329,
    • "plan": "enterprise",
    • "total billed": 830
    },
  • "integrations": {
    • "All": true,
    • "Salesforce": false,
    • "Mixpanel": false
    },
  • "messageId": "022bb90c-bbac-11e4-8dfc-aa07a5b093db,",
  • "sentAt": "2015-02-23T22:28:55.111Z,",
  • "originalTimestamp": "2019-08-24T14:15:22Z",
  • "timestamp": "2015-02-23T22:28:55.111Z,",
  • "context": {
    • "active": true,
    • "ip": "8.8.8.8",
    • "locale": "string",
    • "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_9_5) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/40.0.2214.115 Safari/537.36",
    • "channel": "browser",
    • "campaign": {
      },
    • "page": {
      }
    },
  • "anonymousId": "507f191e810c19729de860ea,",
  • "channel": "browser,",
  • "receivedAt": "2015-02-23T22:28:55.387Z,",
  • "type": "group",
  • "version": 1.1
}

Alias

You only need to use this method to support a few select destinations like Mixpanel.

The alias method reconciles identifiers in systems that don't automatically handle identity changes—like when a person graduates from an anonymous user to an identified user.

For example, a person typically has an anonymousId until you identify them by userId. Most destinations will automatically associate data from the anonymous ID with the new user ID when you send an identify call. But a select few destinations, like Mixpanel, won't! The alias call tells Mixpanel to represent the anonymousId with the new userId.

If you need to use the alias call, you'll want to send it before you identify someone with a userId.

If you use our web or server-side libraries, and you've already identified someone, we assume that this is the userId that you want to keep. Otherwise, you need to pass both the previousId and the userId.

When you use our libraries, you'll typically only provide the previousId and userId. The libraries fill in the rest of the payload automatically.

Authorization:
Request Body: application/json
previousId
required
string

The userId that you want to merge into the canonical profile.

userId
required
string

The userId that you want to keep. This is required if you haven't already identified someone with one of our web or server-side libraries.

Responses

Request samples

Content type
application/json
{
  • "previousId": "string",
  • "userId": "string"
}

Batch

The batch method helps you send an array of identify, group, track, page and/or screen requests in a single call, so you don't have to send multiple requests. Our server-side sources use this method automatically to increase performance.

Requests are limited to 500KB total per request and 32KB per call in the request. In a batch request, the context and integrations objects apply to all calls in the request. You can't set different context or integrations values for different calls in the same request.

Authorization:
Request Body: application/json
Array of objects

A group of requests you want to send to Data Pipelines in the call.

object

A dictionary of context about a source call/event, like the user’s IP address or locale. Context is automatically collected by our source libraries.

object

Contains a list of booleans indicating the integrations that are enabled (true) or disabled (false). By default, all integrations are enabled (returning an empty object). Set "All": false to reverse this behavior.

Responses

Request samples

Content type
application/json
{
  • "batch": [
    • {
      }
    ],
  • "context": {
    • "active": true,
    • "ip": "string",
    • "locale": "string",
    • "userAgent": "string",
    • "channel": "browser",
    • "campaign": {
      },
    • "page": {
      }
    },
  • "integrations": {
    • "All": true,
    • "Salesforce": false
    }
}