About Customer.io's APIs
UpdatedWe have three APIs and webhooks. This page covers our APIs and the best ways to get data into and out of Customer.io if you’re using a terminal, Postman, or writing your own integration.
Use one of our libraries or SDKs!
We have ready-made libraries and SDKs that make it easy to use our APIs and provide other features like in-app messaging, retry logic, and so on. While our APIs can help you get started—and our API documentation includes examples for some of our libraries—you’ll almost always do better with a library or SDK. Check out our integration directory for more information.
Just getting started?
To get data into Customer.io, use an SDK or the Pipelines API. This is the API that most of our integrations are based on and likely the API you’ll use the most. If you’re new to Customer.io, this is where you should start.
To send broadcasts, transactional messages, and fetch data (outside of a data out integration), use the App API. This API is named as such because it’s the API that you’d use to build an app on top of Customer.io. But the most popular use case is to send broadcasts and transactional messages.
There are two ingress APIs
We have two different APIs that you can use to get data into Customer.io—the Pipelines API and Track API. They effectively do the same things within Customer.io, so you can’t really go wrong. But if you’re just getting started with Customer.io, we recommend our Pipelines API because it’s easier to use with newer outbound integrations and it’s where we’re focusing our future development efforts.
The APIs are similar. They both use basic authorization, and they’re both designed to send data to Customer.io with minimal resistance (we handle errors after receiving data) and so on. But there are some differences:
- The Pipelines API only uses
POSToperations. You’ll perform deletes and other operations by sending events with specific names. - The Pipelines API natively supports objectsAn object is a non-person entity that you can associate with one or more people—like a company, account, or online course. and relationshipsThe connection between an object and a person in your workspace. For instance, if you have Account objects, people could have relationships to an Account if they’re admins. through the
/groupendpoint. The Track v1 API and integrations based on this API don’t support most object and relationship operations.
The Pipelines API
Most of our integrations are based on this API, so we recommend starting here. If you use any of our mobile SDKs or libraries, you’re effectively using this API!
Unlike our Track API, this API is made to be relatively generic and support not only Customer.io but all the services we integrate with. If you intend to send data to services outside of Customer.io and use Customer.io like a Customer Data Platform (CDP), then this API is perfect for you.
But if you’re only sending data into Customer.io, and you don’t plan to use an SDK or a library, then this API might seem a little obtuse. For example, if you want to delete a person in Customer.io using the Pipelines API, you’ll send a POST call to the /track endpoint and include a specific event parameter. It’s not a DELETE operation, which is what you might expect!
Events with special meanings
The Pipelines API only contains POST calls. For deletes and other operations, you’ll use track events with a specific name parameters. We use the event name to determine what to do with the data. We sometimes refer to these as semantic events.
For example, if you wanted to delete a person, you’d send a track event with a name parameter called Delete Person. If you want to suppress a person, you’d send an event called Suppress Person.
This paradigm of “events with specialized meanings” isn’t unique to Customer.io operations. We have suites of semantic events to support different downstream integrations as well. If you integrate with an eCommerce platform or a CRM, you might see events like Add to Cart, Purchase, Update Customer, and so on.
The Track API
The Track API is oriented towards getting data into Customer.io specifically, which can make it easy to use if you only integrate with Customer.io.
But we translate data from the Track API to the Pipelines API for downstream integrations. That can make it hard to troubleshoot integrations, because you’ll have to understand how we map operations between the two APIs. For example, imagine that you use the Track API and integrate with both Customer.io and another system like Mixpanel. In this case, it’ll be easy to understand the data you send to Customer.io, but it may be harder to understand (and troubleshoot) the data that you send to Mixpanel.
All of our newer libraries are based on the Pipelines API. You can still use the Track API alongside libraries that use the Pipelines API, but if you’re going to use our libraries anyway, you may want to use the Pipelines API so you don’t have learn two sets of operations!
The App API
Unlike the Pipelines and Track APIs, the App API uses bearer authorization. The App API serves three major purposes:
You can trigger a message to a wide array of people when things like new products become available, you announce tickets for an event, it’s time to register for classes for the next semester, and so on. You can trigger transactional messages for individual people when someone does something on your website or in your app. For example, you might send a receipt when someone buys something, a password reset email when someone forgets their password, and other similar cases. You can fetch data from Customer.io to use in your application. For example, you might look up a person’s information to show them a personalized message on your website, or you might look up campaign information to see how a campaign is performing.Trigger broadcasts: you’ll set up a broadcast in our UI and then trigger it with a single call.
Trigger transactional messages: send receipts, password reset requests, and important notifications.
Fetch data from Customer.io: look up people, campaign information, and so on.
Reporting Webhooks
Reporting webhooks send information about messages sent from Customer.io to downstream systems. So when you draft a message, send a message, someone opens a message, and so on, we send a webhook to an address or system you choose.
We have various downstream integrations that support message events similar to reporting webhooks. If you use an integration that captures information about messages sent from Customer.io, this documentation may help you understand the different events and information we send to those services.
