Region:

Customer.io Track API Reference

Our Track API provides ways to send real-time customer data to your Customer.io workspace.

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. While we redirect traffic from US track API endpoints to EU-based accounts, this traffic still passes through US servers and data may be logged in the US. Our App APIs are not redirected this way, and will fail (401) if you send your request to the wrong regional endpoint.

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/Server	Purpose
`https://track.customer.io/api/`	Use the Track API to report customer attributes and track customer events/activity. You cannot retrieve data using this API. Track endpoints support minimal validation to ensure as close to real-time processing as possible.

Use our Postman collection

We've generated a Postman collection with all of our APIs—not just the ones on this page—with a starter environment (called "CIO Env") containing variables for authorization and path parameters.

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.

NOTE: Postman endpoints default to our US APIs. If you're in our European (EU) region, you'll need to add -eu server variables (track_api_url and app_api_url).

Authentication

You can find all of your API authentication information in your Account Settings. Our Tracking API uses HTTP basic authorization. The App API uses bearer authorization, and you can generate tokens supporting different scopes. Each operation in this document references the authorization header it requires.

Basic Auth (Tracking API Key)

The Track API uses a basic authentication scheme. Your credentials are your Site ID and your API key, Base-64 encoded in the format site_id:api_key.

You can find your Site ID and API key on the Track API Keys page.

Security Scheme Type	HTTP
HTTP Authorization Scheme	basic

Track v2 Overview

This new version of our edge API has only two endpoints, but supports the majority of our traditional v1 track operations and then some based on the type and action keys that you set in your request.

You can use the /batch call to send multiple requests at the same time. Unlike the v1 API, you can also make requests affecting objects and deliveries. Objects are a grouping mechanism for people—like an account people belong to or an online course that they enroll in. Deliveries are events based on messages sent from Customer.io.

The chart below lists the type of action you can perform for each type. Our requests below are broken out by type; use the action dropdown to see the specific payload structure for each action.

Action	Person	Object	Delivery
identify	✅	✅
delete	✅	✅
event	✅		✅
screen	✅
page	✅
add_relationships	✅	✅
delete_relationships	✅	✅
add_device	✅
delete_device	✅
merge	✅
suppress	✅
unsuppress	✅

Make a single request

This endpoint lets you create, update, or delete a single person or object—including managing relationships between objects and people.

An "object" is any kind of non-person entity that you want to associate with one or more people—like a company, an educational course that people signed up for, a product, etc.

Your request must be smaller than 32kb.

Authorization:

Basic Auth (Tracking API Key)

Request Body: application/json

One of

type required	string Value: "person" The operation modifies a person in Customer.io
required	object The person you want to perform an action for—one of either `id`, `email`, or `cio_id`. You cannot pass multiple identifiers.
action required	string Indicates that the operation will `identify` the the item of the specified `type`. identify