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.

Overview

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/ServerPurpose
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.

Set up a REST API source

  1. Go to the {{< svg "connection" >}} tab and click Sources.
  2. Click Add Source, pick JavaScript, 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 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.
  5. Click Submit.

Now you can connect your REST API source to destinations.

Authentication

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.

Basic Auth (Write Key)

Customer.io Data Pipelines use a basic authentication scheme with your Write key—which is generated automatically when you add a source. You can find your Write Key in your source's Settings page.

Security Scheme Type HTTP
HTTP Authorization Scheme basic

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!

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 "All": false to reverse this behavior.

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": {
      },
    • "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, integrations are all enabled (returning an empty object). Set "All": false to reverse this behavior.

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.

Example