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.

If you're in our EU region, you'll need to specify the EU URL when you initialize our server-side libraries. If you use our JavaScript client library, we'll set your region and route data/calls automatically.

After you add a Rest API source, you'll use endpoints at https://cdp.customer.io/v1/{method}

1. Go to the tab and click Sources.
2. Click Add Source, pick HTTP, and click Next.
3. 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.
4. (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.
5. 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 context, 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.

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 track and page calls when the activities actually took place.

You only need to populate a few fields when you send data to Customer.io. Our JavaScript client and server libraries populate additional information for each call, which you'll see when you look at individual events in Customer.io.

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 userId and 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 anonymousId and userId, we'll associate anonymous activity to the userId.

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 traits or attributes. You'll need to check with your destination to understand what your destination calls people-data!

When you send a track call, you'll typically include the event name and additional properties you want to track. You can provide either an anonymousId or a userId. If you provide both, we attribute the activity to the userId and ignore the anonymousId.

Most other fields are populated by Customer.io—either by a source library or our servers.

A page call represents a pageview.

Page events are automatically sent whenever you load our JavaScript library, which is typically every page. Customer.io automatically gathers the page name and URL, but you can pass additional properties, like the category.

Most other fields are populated by Customer.io—either by a source library or our servers.

A scren call indicates that someone went to a screen in your mobile app.

We don't have mobile libraries supporting the screen method just yet, but we'll still accept calls with type: "screen" if you want to set up your own calls.

Group events assign the identified person to a group. You'll typically pass the groupId that you want to associate a person with, and any traits that you want to assign to the group.

Most other fields are populated by Customer.io—either by a source library or our servers.

These are the fields that we augment incoming data with. The shape of this data may change depending on the type of call you make (identify, track, etc), and the source medium (client side javascript, mobile library, etc). We collect many of these values automatically, though you can override some of them. See individual methods below for information about which fields are accepted in requests.

These are fields that we collect automatically with requests—context for the request—but you can override these values.

analytics.track("Device Created or Updated", {
  device: {
    token: "string",
    type: "ios"
  }
});

Journeys, our messaging automation tool, supports a number of actions that aren't immediately apparent from the API. For example, I can add a person using the identify function, but what if I want to remove a person?

That's what semantic events are for: they let you send track calls with a specific event name and payload to perform actions in Journeys. In general, the event names map directly to the thing you want to do: like Create Device or Delete Person.

Remove a person from your Customer.io environment. You might do this when someone cancels their subscription with you or otherwise leaves your service.

Add or update a device. If a device (represented by the context.device.token) exists, does not exist, we'll create it. If the device token already exists, we'll update the it.

Delete a device. You might do this when someone logs out of your app or otherwise removes a device.

Remove a relationship between a person and an object in Customer.io. This is basically the opposite of a group operation. Where objects represent things like accounts, companies, or online classes, you might delete a relationship when a person is no longer on an account, leaves a company, or drops a class.

This event requires a groupId and an objectTypeId. If you don't provide an objectTypeId, we'll assume it's 1, but if the groupId with the associated objectTypeId` (defaulting to 1) does not exist, the event will not remove a person from the group.

Remove a group (also called an "object") from Customer.io Journeys. Groups/objects represent things like accounts, companies, and online classes—non-people entities that people can be related to. You might delete a group when an account is closed, a company is acquired, or you stop offering a class.

This event requires a groupId and an objectTypeId. If you don't provide an objectTypeId, we'll assume it's 1, but if the groupId with the associated objectTypeId (defaulting to 1) does not exist, the event will not find and delete the groupId.

Remove a person from your Customer.io workspace and prevent them from being added back to your workspace using the same identifier. In general you should only send this event for compliance reasons, like when someone invokes their right to be forgotten in accordance with GDPR or CAN-SPAM regulations.

Allow a userId to be added back to your Customer.io workspace. This does not restore information from a person you previously suppressed. It only allows you to add a person back to your workspace using the same identifier.

Reports delivery events for messages. In general, we use this event with our JavaScript snippet to report delivery events for in-app messages back to your Customer.io workspace.

While Customer.io knows about messages that are sent, we use this event to determine when an in-app message is delivered, clicked, and so on. Each message contains a unique deliveryId that we trace back to the person, campaign/broadcast, and other items in your Customer.io workspace.

analytics.track('Experiment Viewed', {
  experiment_id: "12345",
  experiment_name: "Homepage Hero",
  variant_id: "67890",
  variant_name: "Hero B"
})

If you track A/B tests, we recommend that you use the event name Experiment Viewed and properties listed below. Sending uniform events that conform to the schema defined here helps ensure that you can use any default actions that we set up for destinations that rely on A/B test events—now or with destinations we add in the future.

analytics.track('Product Viewed', {
  product_id: "coolshoes-123"
  sku: "abc-123-xyz"
  category: "shoes"
  name: "Cool Shoes"
  brand: "A Shoe Brand"
  variant: "red"
  price: 139.99
  quantity: 1
  coupon: "NEWUSER20"
  position: 3
  url: "https://www.example.com/product/123"
  image_url: "https://www.example.com/product/123.jpg"
  currency: "USD"
  value: 119.99
})

We've defined a set of track events that you can use to send ecommerce activity from your sources. Our default actions and data structures assume that you send ecommerce events in the shapes below. Learn more about our ecommerce specification.

If you send an event with a matching name and structure defined below (where the schemas below represents the properties object), destinations that rely on ecommerce events (like "ad" destinations) will already be set up with actions to handle your ecommerce source events. For example, sending the following Product Viewed event would automatically trigger an action in most of our "ad" destinations and handle all the fields in the event.

The title of each schema below is the name of the event you should pass in a track call.

While you can map ecommerce events however you want, we recommend that you use the events below to take advantage of our default actions and data structures. These events make it easy to send uniform data through data pipelines to your destinations.

Send Products Searched when a user searches for products.

Send the Product List Viewed event when a user views a product.

Send the Product List Filtered event when a user filters a list of products.

Send the Product Clicked event when a user clicks a product.

Send the Product Viewed event when a user viewed a product. This might happen on a page, in a modal window, etc.

Send the Product Added event when a user adds a product to their cart.

Send the Product Removed event when a user removes a product from their cart.

Send the Cart Viewed event when a user views their cart.

Send the Checkout Started event when a user starts the checkout process.

Send the Checkout Step Viewed event when a user views a step in the checkout process.

Send the Checkout Step Completed event when a user completes a step in the checkout process.

Send the Payment Info Entered event when a user enters their payment information.

Send the Order Completed event when a user completes an order.

Send the Order Updated event when a user updates an order.

Send the Order Refunded event when you refund an order.

Send the Order Cancelled event when a customer cancels an order.

Send the Promotion Viewed event when a user views a promotion.

Send the Promotion Clicked event when a user clicks a promotion.