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

Customer.io hosts services in the United States (US) and European Union. Select the appropriate server address for 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.

Our API uses basic authorization with the API key from your Customer.io API integration. If you use Postman or another platform that helps you send API calls, this API key is the Username, and the Password is blank.

You can get a Pipelines API key by setting up the Customer.io API integration in your workspace.

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

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, Customer.io doesn't process it. By default, Customer.io still returns a 200 response. In strict mode, Customer.io returns a 400 instead.

The Data Pipelines API has no fixed rate limit. Customer.io accepts your requests as fast as you send them and doesn't reject or drop them because of volume. Our guideline for both active integrations and historical backfills is about 3000 requests per 3 seconds, an average of 1000 requests per second. The 3-second window leaves room for short bursts.

Traffic above this level usually comes from high-volume integrations, which our Premium and Enterprise plans support. If your traffic regularly goes above this, we may contact you to learn more about your integration and talk about optimizing it, or about a plan that fits your volume.

The Pipelines API runs in lax mode by default. It returns a 200 response for almost every request, and logs issues after the fact in Customer.io. Lax mode keeps a bad request from breaking your integration, but it also means that a 200 response doesn't confirm that Customer.io processed your data.

Turn on strict mode to validate each request and return an error when it fails. This can help you build and test an integration, so you see each problem as soon as it happens. A strict mode error response contains an errors array. Each error has a reason, the field that failed, and a message that describes the problem. Errors from a /batch request also include an index, which is the position of the failing call in the batch array.

To turn on strict mode, send the X-Strict-Mode header with a value of 1. If you leave the header out or send any other value, the request runs in lax mode.

Different endpoints have different required fields:

• Identify, Page, Screen, and Alias calls need a userId or an anonymousId.
• Track calls need a userId, an anonymousId, or a groupId. They also need an event name.
• Group calls need a groupId.
• Alias calls need a previousId.
• Each call in a /batch request needs a type.

Note that in strict mode, a /batch request succeeds or fails as a whole. If any call in the batch fails, Customer.io rejects the entire batch with a 400 and doesn't process any of its calls. In lax mode, Customer.io drops the calls that fail and processes the rest.

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.

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.

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.

• A/B Test
• Ecommerce
• Email
• Live Chat
• Mobile App
• Video

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.