v1.0.0

OAS 3.0.0

Pipelines API

Overview

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.

Server addresses: US and EU

Customer.io hosts services in the United States (US) and European Union. Select the appropriate server address for your region.

Region	Server Address
US	https://cdp.customer.io
EU	https://cdp-eu.customer.io

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.

Get an API key

Go to the tab and click Sources.
Click Add Source, pick HTTP, 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 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.
Click Submit.

Now you can use the key as a username with a blank password to authenticate and send requests to our API.

Authentication & rate limits

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.

Rate and payload 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.

The Data Pipelines API has a rate limit of 3000 requests per 3 seconds for both active data integrations and historical backfill scripts. This limit applies to both our v1 and v2 APIs.

While this rate is not strictly enforced, consistently exceeding it may lead to throttling or dropped data, especially during periods of high system load. If we detect a sustained high volume that could impact other customers, we may contact you to help adjust your integration or, in rare cases, temporarily block requests.

Warning

Rate limits are subject to change. We may adjust these thresholds to ensure stable performance for all customers.

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.

Deletions, suppressions, and other semantic events

You'll notice that this API only contains POST calls; we don't have DELETE operations. For delete operations, and other operations that don't have bespoke endpoints, we use semantic events.

When you need to do things like deleting people, removing relationships, and other sorts of things, you'll send a request to the /track endpoint with a specific event name parameter. The name tells us what to do with the request.

For example, you can send a track event with the name Delete Person to remove a person from your workspace.

See Semantic Events to see Customer.io-specific events.

We also support semantic events for other kinds of destinations. See Semantic Events for other destinations below for more information.

Event Name	Description
`Device Created or Updated`	Adds or updates a mobile device (by token), and associates it with a person
`Device Deleted`	Deletes a device
`User Deleted`	Removes a person from your workspace
`User Suppressed`	Removes a person from your workspace and suppresses their identifiers so you can't add them back to Customer.io.
`User Unsuppressed`	Unsuppresses an identifier so you can add someone back to Customer.io and message them again.
`Relationship Deleted`	Remove a relationship between a person and an object
`Object Deleted`	Remove an object (like an account or company) from your Customer.io workspace
`Report Delivery Event`	Report delivery events for messages

Semantic events for other destinations

In addition to events that have special meanings in Customer.io, we have a number of other events that we support across different kinds of destinations. These uniform events ensure that we'll map event data to destinations consistently—so you can move from one provider to another without having to change your event names or payload structures.

For example, our ecommerce events work across any ecommerce platform we integrate with—even if those ecommerce platforms have different APIs or payload structures.

See Semantic Events to learn more.

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.

Server

The base URL for all Data Pipelines calls in our United States (US) region.

Client Libraries

Shell Curl

Add and Update People

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.

Headers

X-Strict-Mode
enum
const:
1

When set to 1, enables strict validation that returns proper HTTP error codes (400/401) for validation failures. When not set or set to any other value, the API operates in permissive mode, logging errors but returning HTTP 200. Learn more
values
- 1

Body·

application/json

userId
Type: string
required

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
Type: 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.

traits
Type: 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.

integrations
Type: 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
Type: string

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

sentAt
Type: stringFormat: date-time

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

originalTimestamp
Type: stringFormat: 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
Type: stringFormat: 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.

context

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

200

A successful request returns an empty object response.

post/identify

{
  "type": "identify",
  "traits": {
    "name": "Cool Person",
    "email": "cool.person@example.com",
    "likes_baseball": true,
    "games_attended": 5
  },
  "userId": "97980cfea0067"
}

No Body

A successful request returns an empty object response.

Track events

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.

While this endpoint takes any event name you want to send, Customer.io also supports "semantic events." These are specific event names (like User Deleted or Device Created or Updated) that perform special operations in Customer.io like deleting people, adding mobile devices to profiles, and so on. See the Customer.io Semantic Events documentation for complete schemas and examples.

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.

Headers

X-Strict-Mode
enum
const:
1

When set to 1, enables strict validation that returns proper HTTP error codes (400/401) for validation failures. When not set or set to any other value, the API operates in permissive mode, logging errors but returning HTTP 200. Learn more
values
- 1

Body·

application/json

userId
Type: string
required

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
Type: string
required

The name of the event

properties
Type: object

Additional properties for your event.

integrations
Type: 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
Type: string

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

sentAt
Type: stringFormat: date-time

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

originalTimestamp
Type: stringFormat: 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
Type: stringFormat: 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.

context

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

200

A successful request returns an empty object response.

post/track

{
  "anonymousId": "23adfd82-aa0f-45a7-a756-24f2a7a4c895",
  "context": {
    "library": {
      "name": "analytics.js",
      "version": "2.11.1"
    },
    "page": {
      "path": "/",
      "referrer": "https://www.google.com/",
      "search": "?q=analytics",
      "title": "Customer.io Docs",
      "url": "https://docs.customer.io"
    },
    "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",
    "ip": "108.0.78.21"
  },
  "event": "Course Started",
  "integrations": null,
  "messageId": "ajs-f8ca1e4de5024d9430b3928bd8ac6b96",
  "properties": {
    "title": "Intro to Customer.io"
  },
  "receivedAt": "2015-12-12T19:11:01.266Z",
  "sentAt": "2015-12-12T19:11:01.169Z",
  "timestamp": "2015-12-12T19:11:01.249Z",
  "type": "track",
  "userId": "AiUGstSDIg",
  "originalTimestamp": "2015-12-12T19:11:01.152Z"
}

No Body

A successful request returns an empty object response.

Track pageviews

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.

Headers

X-Strict-Mode
enum
const:
1

When set to 1, enables strict validation that returns proper HTTP error codes (400/401) for validation failures. When not set or set to any other value, the API operates in permissive mode, logging errors but returning HTTP 200. Learn more
values
- 1

Body·

application/json

userId
Type: string
required

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
Type: string

The name of the page.

properties
Type: 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.

integrations
Type: 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
Type: string

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

sentAt
Type: stringFormat: date-time

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

originalTimestamp
Type: stringFormat: 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
Type: stringFormat: 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.

context

Responses

200

A successful request returns an empty object response.

post/page

{
  "anonymousId": "507f191e810c19729de860ea",
  "channel": "browser",
  "context": {
    "ip": "8.8.8.8",
    "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"
  },
  "integrations": {
    "All": true,
    "Mixpanel": false,
    "Salesforce": false
  },
  "messageId": "022bb90c-bbac-11e4-8dfc-aa07a5b093db",
  "name": "Home",
  "properties": {
    "title": "Welcome | ACME, Inc.",
    "url": "https://www.example.com"
  },
  "receivedAt": "2015-02-23T22:28:55.387Z",
  "sentAt": "2015-02-23T22:28:55.111Z",
  "timestamp": "2015-02-23T22:28:55.111Z",
  "type": "page",
  "userId": "97980cfea0067",
  "version": 1.1
}

No Body

A successful request returns an empty object response.

Track mobile screenviews

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.

Headers

X-Strict-Mode
enum
const:
1

When set to 1, enables strict validation that returns proper HTTP error codes (400/401) for validation failures. When not set or set to any other value, the API operates in permissive mode, logging errors but returning HTTP 200. Learn more
values
- 1

Body·

application/json

userId
Type: string
required

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
Type: string

The name of the screen the person visited.

properties
Type: object

Additional properties for your screen.

integrations
Type: 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
Type: string

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

sentAt
Type: stringFormat: date-time

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

originalTimestamp
Type: stringFormat: 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
Type: stringFormat: 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.

context

Responses

200

A successful request returns an empty object response.

post/screen

{
  "anonymousId": "507f191e810c19729de860ea",
  "context": {
    "ip": "8.8.8.8"
  },
  "integrations": {
    "All": true,
    "Salesforce": false
  },
  "messageId": "022bb90c-bbac-11e4-8dfc-aa07a5b093db",
  "name": "feed",
  "properties": {
    "subscriptions": [
      "baseball",
      "basketball"
    ]
  },
  "receivedAt": "2015-02-23T22:28:55.387Z",
  "sentAt": "2015-02-23T22:28:55.111Z",
  "timestamp": "2015-02-23T22:28:55.111Z",
  "type": "screen",
  "userId": "97980cfea0067",
  "version": 1.1
}

No Body

A successful request returns an empty object response.

Create objects and relationships

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.

Headers

X-Strict-Mode
enum
const:
1

When set to 1, enables strict validation that returns proper HTTP error codes (400/401) for validation failures. When not set or set to any other value, the API operates in permissive mode, logging errors but returning HTTP 200. Learn more
values
- 1

Body·

application/json

userId
Type: 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
Type: string

ID of the group

traits
Type: object

Additional information about the group.

integrations
Type: 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
Type: string

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

sentAt
Type: stringFormat: date-time

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

originalTimestamp
Type: stringFormat: 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
Type: stringFormat: 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.

context

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

200

A successful request returns an empty object response.

post/group

{
  "anonymousId": "507f191e810c19729de860ea,",
  "channel": "browser,",
  "context": {
    "ip": "8.8.8.8",
    "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"
  },
  "integrations": {
    "All": true,
    "Mixpanel": false,
    "Salesforce": false
  },
  "messageId": "022bb90c-bbac-11e4-8dfc-aa07a5b093db,",
  "receivedAt": "2015-02-23T22:28:55.387Z,",
  "sentAt": "2015-02-23T22:28:55.111Z,",
  "timestamp": "2015-02-23T22:28:55.111Z,",
  "traits": {
    "name": "ACME, Inc.",
    "industry": "Technology",
    "employees": 329,
    "plan": "enterprise",
    "total billed": 830
  },
  "type": "group",
  "userId": "97980cfea0067",
  "groupId": "0e8c78ea9d97a7b8185e8632,",
  "version": 1.1
}

No Body

A successful request returns an empty object response.

Merge profiles

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.

Headers

X-Strict-Mode
enum
const:
1

When set to 1, enables strict validation that returns proper HTTP error codes (400/401) for validation failures. When not set or set to any other value, the API operates in permissive mode, logging errors but returning HTTP 200. Learn more
values
- 1

Body·

application/json

previousId
Type: string
required

The userId that you want to merge into the canonical profile.
userId
Type: string
required

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

200

A successful request returns an empty object response.

post/alias

{
  "previousId": "string",
  "userId": "string"
}

No Body

A successful request returns an empty object response.

Batch requests

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.

Headers

X-Strict-Mode
enum
const:
1

When set to 1, enables strict validation that returns proper HTTP error codes (400/401) for validation failures. When not set or set to any other value, the API operates in permissive mode, logging errors but returning HTTP 200. Learn more
values
- 1

Body·

application/json

batch
Type: array

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

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

active
Type: 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
Type: 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
Type: string

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

userAgent
Type: string

The user agent of the device making the request

channel
Type: stringenum

The channel the event originated from.

values
browser
server
mobile
campaign
Type: object

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

page
Type: object

Contains information about the current page in the browser. This is automatically collected by our JavaScript source.
integrations
Type: 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

200

A successful request returns an empty object response.

post/batch

{}

No Body

A successful request returns an empty object response.