15

Differences between the Pipelines and Track APIs

A comprehensive comparison of the Track API and Pipelines API to help you understand when and how to use them.

General differences

We have two APIs to help you get data into Customer.io: the Track API and the Pipelines API. If you’re new to Customer.io: most of our libraries and SDKs are based on the Pipelines API; it’s what you’ll use for most integrations.

If you’re migrating from an earlier integration that used the Track API, this page can help you understand the differences between your track-based integration and our Pipelines API.

The Pipelines API is based on customer data platform (CDP) APIs like Segment or Rudderstack. It’s a bit more generic than the Track API, and that means you may need to map some concepts from the Pipelines API to their equivalents in Customer.io. But, most of our integrations are built on this API. Understanding it can help you better support your integrations.

The Track API is purpose-built for Customer.io, but libraries built on it don’t support as many features as our newer, Pipelines-based integrations. While there are two versions of the Track API, we typically mean the track v1 API when we talk about The Track 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.

JavaScript snippets

While we typically offer integrations based on our Pipelines API, we have two different JavaScript snippets—one based on the Pipelines API and one based on the Track API. We recommend the snippet based on the Pipelines API because it offers features that aren’t available for the classic, track API-based snippet. You’ll find the recommended, Pipelines-based JavaScript snippet in our integrations catalog.

If you have an older integration, you might be using our Track-based JavaScript snippet. It’s no longer available in our integrations catalog, but we have code samples in our legacy JavaScript documentation.

Two versions of the Track API

The Track API has two versions: v1 and v2. While we discuss the v2 API in a few places on this page, and it can be useful if you write your own integration, it isn’t used in any of our libraries.

Most of the time, when we talk about The Track API, we’re talking about the v1 API. It was much more commonly used in our older integrations and is still in use in some third-party integrations. For example, if you integrate with Customer.io using Segment, Segment sends data to Customer.io using the Track v1 API.

The major differences between the v1 and v2 APIs are that the v2 API only has two endpoints: entity and batch and determines what to do based on the type and action in the payload. The type represents the thing you want to work with and the action is what you want to do with it. Unlike our v1 API, the v2 API supports objects and relationships natively.

Authentication

The Track API uses a traditional basic authentication scheme with a site ID and API key as the username and password respectively.

The Pipelines API uses basic authentication with a single key rather than a username and password. When you’re using our SDKs, you’ll pass a single key. When you use the API directly, you’ll use enter the key as the username and a blank password, so you authorization header looks like this: Authorization <your_key_here>:

Deleting data

The Track API supports DELETE calls to remove data. The Pipelines API does not; it only contains POST calls to add and update data.

To delete data with the Pipelines API, you’ll send a POST to the /track endpoint with a specific event name—we call these “semantic events.” For example, you can send a POST to the /track endpoint with the event name User Deleted to remove a person from Customer.io.

See Semantic Events for a list of the semantic events you can use with Customer.io and our Pipelines API.

Identifying people: id and userId

In Customer.io, people have an id and an email address. You can use either to identify them, but they appear differently in our APIs.

When you use the Track v1 API, you identify people by their id or email address as a part of the URL path.

For the Pipelines API, you pass a userId in your payloads. This value can be an id or an email address and Customer.io will automatically handle it as the correct identifier. If you need to pass both, you’d pass the userId and a traits.email attribute to store the email address.

{
  "email": "user@example.com",
  "name": "cool person"
}

{
  "userId": "user123",
  "traits": {
    "email": "user@example.com",
    "name": "cool person"
  }
}

Attributes in identify calls

The Track API treats all values in the payload of an identify call as attributes.

The Pipelines API uses a traits object to pass attributes. This is because the Pipelines API supports different objects in its payload (like context and integrations, etc.)

{
  "email": "user@example.com",
  "name": "cool person",
  "likes_pizza": true
}

{
  "userId": "user123",
  "traits": {
    "email": "user@example.com",
    "name": "cool person",
    "likes_pizza": true
  }
}

Tracking events

The Track v1 API includes the identifier for the person performing the event in the URL path (user123 in the example below), has a name parameter to pass the event name, and includes a data object to pass event properties.

The Pipelines API expects the userId in the payload, uses the event parameter to pass the event name, and includes a properties object to pass event properties.

{
  "name": "purchase",
  "data": {
    "price": 23.45,
    "product": "socks"
  }
}

{
  "userId": "user123",
  "event": "purchase",
  "properties": {
    "price": 23.45,
    "product": "socks"
  }
}

Managing objects (groups)

The Pipelines API is the preferred way to support objectsAn object is a non-person entity that you can associate with one or more people—like a company, account, or online course. because it has a native concept of objects and a more consistent structure with the /group endpoint.

To support objects with the Track API, we suggest you use the v2 version of the Track API. But, if you’re using any of our libraries based on the Track API—all of which use v1—you’ll need to support objects as a part of your identify calls. You cannot delete objects with the Track v1 API.

{
  "userId": "user123",
  "groupId": "group123",
  "traits": {
    "object_type_id": "1",
    "account_name": "Acme",
    "account_type": "enterprise",
    "relationship_traits": {
      "is_admin": true,
      "position": "account manager"
    }
  }
}

{
  "identifiers": {
    "object_type_id": "1",
    "object_id": "group123"
  },
  "type": "object",
  "action": "identify",
  "attributes": {
    "account_name": "Acme",
    "account_type": "enterprise"
  },
  "cio_relationships": [
    {
      "identifiers": {
        "id": "user123"
      },
      "relationship_attributes": {
        "is_admin": true,
        "position": "account manager"
      }
    }
  ]
}

{
  "first_name": "Bob",
  "plan": "basic",
  "cio_relationships": {
    "action": "add_relationships",
    "relationships": [
      {
        "identifiers": {
          "object_type_id": "1",
          "object_id": "group123"
        },
        "relationship_attributes": {
          "is_admin": true,
          "position": "account manager"
        }
      }
    ]
  }
}

Timestamps

By default, the Pipelines API uses ISO 8601 timestamps (down to milliseconds), like 2023-04-26T13:42:19.722Z. The Track API, by comparison, uses Unix timestamps (in seconds), like 1361205308.

Customer.io typically relies on Unix timestamps for things like segmentA group of people who match a series of conditions. People enter and exit the segment automatically when they match or stop matching conditions. conditions where you might do time-based calculations. For example, if you check that an attribute is a timestamp in a segment, it will evaluate to true if the value is a Unix timestamp and false if it’s an ISO timestamp.

Most of the time, you don’t need to worry about this difference. By default, Customer.io converts ISO-8601 timestamps that come from the Pipelines API (and associated libraries) to Unix timestamps to support things you might do in Customer.io. But this distinction can be important if you need to store and manipulate timestamps in your own code.

Why does the Pipelines API use ISO 8601 timestamps when Customer.io generally expects Unix timestamps? Because ISO 8601 timestamps are common to many other platforms, and the Pipelines API is designed like a traditional customer data platform (CDP)—where you can send data to both Customer.io and other destinations.

The Pipelines API also includes additional timestamps—fields like receivedAt, sentAt, and originalTimestamp.

{
  "timestamp": 1361205308
}

{
  "timestamp": "2023-04-26T13:42:19.722Z",
  "receivedAt": "2023-04-26T13:42:20.512Z",
  "sentAt": "2023-04-26T13:42:20.477Z",
  "originalTimestamp": "2023-04-26T13:42:19.722Z"
}

The Pipelines API captures context and integrations

Because the Pipelines API is based off of traditional customer data platforms (CDPs) like Segment, it has reserved objects for context and integrations. The context object contains information about the event, like the IP address and user agent. The integrations object provides a way to determine which destinations you want to send your data to.

Maximum request sizes

The Track API has a 32 KB limit for single requests and a 500 KB limit for batch requests—which are only available in the v2/batch endpoint for the Track API.

The Pipelines API has a 64 KB limit for single requests and a 1 MB limit for batch requests.