Data Pipelines API
Download OpenAPI specification:Download
All endpoints begin 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 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.
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.
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.
After you add a Rest API source, you'll use endpoints at
- 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
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.
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
|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
page calls when the activities actually took place.
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
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
userId, we'll associate anonymous activity to the
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
attributes. You'll need to check with your destination to understand what your destination calls people-data!