Loading API documentation...
v1.0.0
OAS 3.1.0

Journeys Track API

Overview

Our Track API provides ways to send real-time customer data to your Customer.io workspace including customer identification and event tracking.

Use our Postman collection

We've generated a Postman collection to help you get started with our APIs.

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 to the server variables (track_api_url and app_api_url).

Run In Postman

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://track.customer.io
EU https://track-eu.customer.io

Note that if your account is in the EU region and you send traffic to our US endpoints, we'll redirect it accordingly but this traffic still passes through US servers and data could be logged in the US.

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.

v1 vs v2 APIs

Most of the time, when we talk about The Track API, we're talking about the v1 API because the v2 API isn't used in any of our libraries and rarely used in libraries built by third parties; it's much more common that you'd encounter the v1 API.

If you're integrating with Customer.io using one of our libraries, or a third party customer data platform (CDP) like Segment or Rudderstack, you'll be using the v1 API.

The v2 API is newer and supports two important features that the v1 API doesn't natively support: objects and batching. But, if you're integrating directly with our API, we suggest you use the Pipelines API. The Pipelines API supports both objects, batching, and all of our newest integrations and libraries are based on it.

Rate Limits

The Track API has a rate limit of 1000 requests per second 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.

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

Below are the payload size limits for the Track API. If any of these limits are too restrictive for your needs, contact support to let us know your situation as we may be able to accommodate special circumstances.

Customer limits

These limits apply to people and their attributes, often referred to as "customers" in our APIs.

Data Type Limit Description
ID 150 bytes Max length of a person's ID value
Attribute Name 150 bytes Max length of each attribute name
Attribute Value 1000 bytes Max length of attribute values
Unique attributes 300 Max number of attributes allowed per person or Identify call

Object and relationship limits

Objects (groups) and relationships between people and objects can have their own attributes. Their limits are similar to people (customers).

Data Type Limit Description
Object ID 150 bytes Max length of a object's ID
Attribute Names 150 bytes Max length of each attribute name
Attribute Values 1000 bytes Max length of attribute values
Unique attributes 300 Max number of attributes allowed per object or relationship
Total attribute size 100 Kilobytes Max size of all attributes associated with an object or relationship

Track API Event limits

These limits apply to events that you'll send with the /v1/track call.

Data Type Limit Description
Event Name 100 bytes Max length of each event name
Event Data 100000 bytes Max length of each event data

v2 API Limits

The v2 API has two endpoints, both of which have limits on the total size of requests.

  • /entity is limited to requests 32kb or smaller.

  • /batch is limited to requests 500kb or smaller.

    Each of the requests within a batch must also be 32kb or smaller.

The base URL for the Track API. Track endpoints use basic authentication with your Site ID as the user name and your secret key as the password.

No authentication selected
Client Libraries
Shell Curl

Track v2 API

​

This 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 ✅
Track v2 API Operations

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.

Body
application/json

      • Add or update a person.

        • action
          Discriminator
          enum
          const:  
          identify
          required

          Indicates that the operation will identify the the item of the specified type.

          values
          • identify
        • type
          enum
          const:  
          person
          required

          The operation modifies a person in Customer.io

          values
          • person
        • identifiers
          required

          The person you want to perform an action for—one of either id, email, or cio_id. You cannot pass multiple identifiers.

        • timestamp
          Type: integer

          The Unix timestamp for when the attribute update occurred. This can be used to control the order of attribute updates when multiple requests are sent in rapid succession.

        • attributes
          Type: object

          Attributes that you want to add or update for this person. You can pass properties that aren't defined below to set custom attributes; the defined properties are reserved in the Customer.io Track API.

        • cio_relationships
Responses
  • 200

    A successful request returns an empty object response.

  • application/json
  • 401

    Unauthorized request. Make sure that you provided the right credentials.

Request Example for post/api/v2/entity
{
  "type": "person",
  "identifiers": {
    "id": "42"
  },
  "action": "identify",
  "attributes": {
    "first_name": "Jane"
  }
}
No Body

A successful request returns an empty object response.

Send multiple requests

​

This endpoint lets you batch requests for different people and objects in a single request. Each object in your array represents an individual "entity" operation—it represents a change for a person, an object, or a delivery.

You can mix types in this request; you are not limited to a batch containing only objects or only people. An "object" is a non-person entity that you want to associate with one or more people—like a company, an educational course that people enroll in, etc.

Your batch request must be smaller than 500kb. Each of the requests within the batch must also be 32kb or smaller.

Body
application/json
  • batch
    Type: array

    A batch of requests, where each object is any individual entity payload—modifying a single person or object.

Responses
  • 200

    A successful request returns an empty object response.

  • application/json
  • application/json
  • 401

    Unauthorized request. Make sure that you provided the right credentials.

Request Example for post/api/v2/batch
{
  "batch": [
    {
      "type": "person",
      "identifiers": {
        "id": "42"
      },
      "action": "identify",
      "attributes": {
        "first_name": "Jane",
        "last_name": "Doe",
        "plan": "premium"
      }
    },
    {
      "type": "object",
      "identifiers": {
        "object_type_id": "1",
        "object_id": "acme"
      },
      "action": "identify",
      "attributes": {
        "name": "Acme Corp",
        "plan": "enterprise",
        "seats": 50
      }
    },
    {
      "type": "object",
      "identifiers": {
        "object_type_id": "1",
        "object_id": "acme"
      },
      "action": "add_relationships",
      "cio_relationships": [
        {
          "identifiers": {
            "id": "42"
          },
          "relationship_attributes": {
            "role": "admin"
          }
        }
      ]
    }
  ]
}
No Body

A successful request returns an empty object response.

Track v1 Overview (Collapsed)

​

Web SDK vs Backend Integrations

  <script type="text/javascript">
      var _cio = _cio || [];
      (function() {
          var a,b,c;a=function(f){return function(){_cio.push([f].
          concat(Array.prototype.slice.call(arguments,0)))}};b=["load","identify",
          "sidentify","track","page"];for(c=0;c<b.length;c++){_cio[b[c]]=a(b[c])};
          var t = document.createElement('script'),
              s = document.getElementsByTagName('script')[0];
          t.async = true;
          t.id    = 'cio-tracker';
          t.setAttribute('data-site-id', 'YOUR_SITE_ID');
          t.setAttribute('data-use-array-params', 'true');
          t.src = 'https://assets.customer.io/assets/track.js';
          s.parentNode.insertBefore(t, s);
      })();
  </script>

You can integrate with this API using a javascript snippet, by consuming the API directly, or both.

You can simply copy/paste the Javascript snippet to your site to track basic customer behaviors directly from your website. In many cases, using the Javascript snippet is easier to integrate with your app, but there are several reasons why you may want to send events from your backend systems:

  • Ad blockers are becoming more prevalent as people and browsers increasingly try to avoid 3rd-party JS trackers.
  • You don't plan to trigger emails based on how customers interact with your website (e.g. users who haven’t visited the site in X days).
  • You use the Javascript snippet, but have a few events you’d like to send from your backend system. They will work well together!
  • You would rather not have another Javascript snippet slowing down your frontend. Our snippet is asynchronous (doesn’t affect initial page load) and very small, but we understand.

You should base your decision to send events from your backend or a Javascript snippet on what works best for you. You can fully integrate with Customer.io using either approach.

Account Region (Collapsed)

​

Determine whether your account and data are hosted in the US or EU data center using your Track API Key.

Account Region Operations

Customers (Collapsed)

​

Add, modify, suppress, or unsuppress people (referred to as "customers" in our APIs). You can also use these endpoints to set attributes on people.

Customers Operations

Events (Collapsed)

​

Use customer events to trigger campaigns or add users to segments. You can attribute events directly to customers or send anonymous events and associate them with users later when you identify them.

Events Operations

Segments (Collapsed)

​

Manual segments are lists of people that you incorporate using the API or by uploading CSVs. You can add people to, or remove people from, manual segments with these endpoints. These endpoints do not let you modify data-driven segments.

NOTE: These endpoints do not yet support workspaces that use both email and id as identifiers.

A segment must exist before you can add people to it. You can create manual segments using the App API /segments endpoints.

Segments Operations

Forms (Collapsed)

​

Connect forms to your workspace to identify people, apply form responses to people, and trigger campaigns for people who fill out forms on your website or in your app.

Forms Operations

Models