Customer.io Pipelines API

With the Pipelines API (shown in the UI as the Customer.io API source), you can send data from anywhere directly to Customer.io and other downstream integrations without using an SDK. See our API documentation for more information about the Pipelines APIs.

Connect a Customer.io Pipelines API source

1. Go to Integrations and click Add integration.
2. Find the Customer.io API integration.

   

3. Give the integration a name. The name helps you find and differentiate between different API credentials; you might name them for users, environments, or the services you use them for.
4. Under Configure your API call, copy the API key. This is the key you’ll use to authenticate with Customer.io. The page also shows you a ready-made curl request with your key already filled in, so you can paste that straight into a terminal instead of building the request yourself.
5. Send a test call with your key. Your key is the username and the password is blank, so pass it to curl with a trailing colon and let curl encode the credentials for you. Here’s an example:

   curl --request POST \
     --url https://cdp.customer.io/v1/identify \
     --user '<your api key>:' \
     --header 'content-type: application/json' \
     -d '
     {
       "userId": "97980cfea0067",
       "traits": {
         "name": "Cool Person",
         "email": "cool.person@example.com"
       }
     }'

   A 200 response doesn't always mean we accepted your data

   If your credentials are wrong, we still return 200, but we drop the request. Add the header X-Strict-Mode: 1 to your call and we’ll return an error instead, which makes an authentication problem much easier to spot.

6. Click Test connection. We check whether we’ve received data from your source. Sending the call isn’t enough on its own; you have to run this check for us to record that your source is connected.
7. Click Complete setup.

After you’ve added your source, you can start making your own calls and add a destination to work with your new source.

Enable automatic geolocation support

You can automatically geolocate profiles when you identify them and pass their IP addresses in the context.ip field in your identify requests. This helps you gather information about your audience’s location and time zone so you can schedule messages at the right times or send messages relevant to their communities.

If you’ve already set up your integration to capture IP addresses, and you’ve enabled the workspace-level Automatic Geolocation Data Collection setting, you can enable geolocation for your integration.

After you enable the Customer.io API source, go to your integration’s Settings tab and turn on the Enable Geolocation setting.

Identify

You should call identify when your customers create an account, log in, or otherwise identify themselves. The identify method tells you who the current website or app visitor is and lets you set or update unique traits to a profile.

You can send an identify call with an anonymous ID and/or user ID. To associate anonymous activity with an identified profile, send both IDs in a single call.

• Anonymous ID only: This assigns traits to a profile before you know who they are.
• User ID only: Identifies a user and sets traits.
• Both user ID and anonymous ID: Associates the data sent in previous anonymous page, track, and identify calls with the person you identify by user ID.

Merge anonymous activity into a profile

Unlike our client-side JavaScript library, server-side libraries and the API don’t assign an anonymous ID automatically. You assign an anonymous ID to track a person’s anonymous track and page calls. Then when you identify the user, you pass the anonymous ID with their user ID and Customer.io will merge the last 30 days of anonymous activity with the identified profile.

You can’t reuse an anonymous ID after it’s merged into a profile. Once an identify call links an anonymous ID to a user ID, Customer.io merges that ID’s anonymous activity into the profile and marks the anonymous ID as used—any events sent under the same anonymous ID afterward stay anonymous and won’t link to the profile.

If a person generates new anonymous activity after you’ve identified them—for example, they log out and keep browsing before logging back in—assign a new anonymous ID for that activity, then send another identify call with their user ID and the new anonymous ID to merge it into the same profile.

However, there is a 5 minute window after you merge anonymous activity into a profile where you can still merge anonymous activity using the same anonymous ID. This allows you to merge anonymous activity in a batch or in rapid succession without worrying about the order of your calls.

Track

The track method tells us about actions profiles take—the events profiles perform—on your site. Every track call represents an event.

You should track your audience’s activities with events both as performance indicators and so you can respond to your audience’s activities with automations in Journeys. For example, if your audience performs a Video Viewed or Item Purchased event, you might respond with other videos or products the profile might enjoy.

You can send events with an anonymousId or a userId. Calls that you make with an anonymousId are associated with a userId when you identify someone by their userId.

Track calls require an event name describing what a person did. And they generally include a series of properties, providing additional information about the event. Beyond that, we’ve provided a complete schema for writable event fields below, and you can find more information in our API documentation.

Page

The Page method records page views on your website, along with optional extra information about the page a person visited.

Screen

The Screen method sends screen view events for mobile devices. These help you understand the screens that profiles use in your app.

Group

The Group method associates an identified profile with a group—like a company, organization, project, online class or any other collective noun you come up with for the same concept. In Customer.io Journeys, we call groups objects.

Group calls are useful for integrations where you maintain relationships between profiles and larger organizations, like in Customer.io! In Customer.io Journeys, you can store groups as objects, and trigger automations based on a profile’s relationship to an object—like an account, online class, and so on.

Find more details about group, including the group payload, in our API spec.

Alias

The Alias method combines two previously unassociated user identities. Some integrations automatically reconcile profiles with different identifiers based on whether you send anonymousId, userId, or another trait that the integration expects to be unique. But for integrations that don’t, you may need to send alias requests to do this.

In general, you won’t need to use the alias call; we try to handle user identification gracefully so you don’t need to merge profiles. But you may need to send alias calls to manage user identities in some data-out integrations.

For example, in Mixpanel it’s used to associate an anonymous user with an identified user once they sign up.