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
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 docs. If you're in the EU region and you send data to our US endpoints, you may receive a 200 OK response, but we won't populate data or forward it to destinations.
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 may return a 200 OK but we won't store this data, nor will we forward it to destinations. 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.
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.
After you add a Rest API source, you'll use endpoints at https://cdp.customer.io/v1/{method}
- 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 connect your REST API source to destinations.
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.
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 |
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.
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!