Customer.io Data Pipelines API
This is a reference for the Customer.io 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.
These APIs are for the United States (US) region
If your account is based in the European Union (EU) data center, you should switch to the EU region's API documentation.
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.
These APIs are for the European Union (EU) region
If your account is based in the United States (US) data center, requests to EU endpoints will fail. Switch to the US region's API documentation.
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.
Customer.io hosts 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.
Host/Server | Purpose |
---|---|
https://cdp.customer.io/v1/ | You'll typically consume our CDP API through one of our [source libraries](/docs/cdp/sources/catalog/), but you can set up your own integration if you want to use a source that we don't support. |
- Go to the {{< svg "connection" >}} tab and click Sources.
- Click Add Source, pick JavaScript, and click Next.
- 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.
- (Optional) Test your connection by sending a test call. You can copy your write 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.
- Click Submit.
Now you can connect your REST API source to destinations.
Our API uses basic authorization with a write key provided when you set up a source. If you use Postman or another platform that helps you send API calls, this write key is the Username, and the Password is blank.
Our sources are all authenticated using a Write Key that we generate when you create a source.
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.
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.
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!
type required | string Value: "identify" The event type. This is set automatically by the request method/endpoint. |
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. |
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, integrations are all enabled (returning an empty object). Set | |
messageId | string A unique identifier for a CDP event, ensuring that each individual event is unique. |
receivedAt | string <date-time> The ISO-8601 timestamp when the CDP receives an event. |
sentAt | string <date-time> The ISO-8601 timestamp when a library sends an event to the CDP. |
timestamp | string <date-time> The ISO-8601 timestamp when the event originally took place. This is mostly useful when you backfill data 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 our source libraries. |
{- "type": "identify",
- "traits": {
- "name": "Cool Person",
- "email": "cool.person@example.com",
- "likes_baseball": true,
- "games_attended": 5
}, - "userId": "97980cfea0067",
- "integrations": {
- "Salesforce": false,
- "Mixpanel": true
}, - "messageId": "string",
- "receivedAt": "2019-08-24T14:15:22Z",
- "sentAt": "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": {
- "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": [
- "string"
]
}
}
}
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.
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, integrations are all enabled (returning an empty object). Set | |
messageId | string A unique identifier for a CDP event, ensuring that each individual event is unique. |
receivedAt | string <date-time> The ISO-8601 timestamp when the CDP receives an event. |
sentAt | string <date-time> The ISO-8601 timestamp when a library sends an event to the CDP. |
timestamp | string <date-time> The ISO-8601 timestamp when the event originally took place. This is mostly useful when you backfill data 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 our source libraries. |