Mapping Customer.io to outgoing integrations
UpdatedHow it works
When we receive traffic from some integrations, like the Track API, we translate them to our newer and more generic Pipelines format to better support downstream, data outAn integration that sends data out of Customer.io. integrations. This might be a little confusing when you send data in to Customer.io with one format, and then see the resulting Data Out calls in a different format!
This page explains how we map the Track API to our Pipelines API for data out integrations, to help you understand how your data transforms as we send it out of Customer.io. You can even change the way we map your data to destinations if you need to.
How the Track API maps to the Pipelines API
The Track and Pipelines APIs are very similar. In many cases, they share the same “method” names—they both identify
people, track
events, and so on. This makes it easy to map calls from the Track API to Pipelines, but we discuss mappings in greater detail in the sections below.
The Journeys Track API doesn’t have a group
method; rather, it handles group calls with a cio_relationships
object in identify
calls. We discuss this in greater detail in the Group calls section below, but this means that the Journeys Track API identify
method with cio_relationships
in the payload will produce two calls to Pipelines: one identify
call and one group
call.
Pipelines API call | JavaScript Client method | Track v1 API call | Track v2 API call |
---|---|---|---|
Identify | identify | /v1/identify/{customer_id} | Any object where "type": "person" and "action" is "identify" |
Track | track | /v1/customers/{customer_id}/event | Any object where"type": "person" and "action" is "event" , "add_device" , or "remove_device" |
Page | page | /v1/customers/{customer_id}/event where "type": "page" | Any object where "type": "person", "action": "page" |
Screen | N/A | /v1/customers/{customer_id}/event where "type": "screen" | Any object where "type": "person", "action": "screen" |
Group | N/A | /v1/identify/{customer_id} containing cio_relationships | Any object where type: "group" ,"action": "add_relationship" , or "action": "delete_relationship" |
Alias | N/A | /v1/merge_customers | "type": "identify", "action": "merge" |
Suppress | N/A | /v1/customers/{customer_id}/suppress | Any object where "type": "person", "action": "suppress" |
Unsuppress | N/A | /v1/customers/{customer_id}/unsuppress | Any object where "type": "person", "action": "unsuppress" |
Some Track API calls don’t map neatly to downstream destinations
There are a couple of sparsely-used Track API calls that don’t have an analog in Pipelines and therefore don’t map neatly to downstream destinations:
- Calls that add or remove people from manual segments
- Custom unsubscribe calls
Mapping Track v2 calls
The Track v1 API includes methods that generally map to our Pipelines API—they both have methods to identify
, track
, send page
events, etc.
The Track v2 API uses the type
and action
keys to dictate an action. We use these keys to map actions to Pipelines. For example, if the v2 action
is identify
and type
is person
, that represents a Pipelines identify
call. If the type
is object
, that represents a group
call.
Pipelines API method | Track v2 API type | Track v2 API action |
---|---|---|
Identify | person | identify |
Group | object | identify or add_relationship |
Group | person | add_relationship |
Track | person | event |
Page | person | page |
Screen | person | screen |
Alias | person | merge |
Identify
The Track v1 API includes an identify
method that maps cleanly to the identify
method in Pipelines. We map Track v2 calls to the Pipelines identify
method when type
is person
and action
is identify
.
For a typical identify
call, we map any keys that aren’t identifiers to traits
. The lone exception is cio_relationships
: we don’t pass this key in identify
calls, but rather send a separate group
call to set relationships. See Group calls below for more information.
identify
API call)
a-->b(identify)
a-->c{"does call includecio_relationships
?"}
c-.->|Yes|d(group)Track v1 API Call | Pipelines Result |
---|---|
|
|
Track, page, and screen events
The Track v1 API includes a track
method that maps cleanly to Pipelines track
method. The Track v1 API doesn’t have methods for page
and screen
events. Rather, you’ll send standard track
events with a type
of page
or screen
. These map to the Pipelines page
and screen
methods respectively.
track
API call)
a-->b(type: page)-->c(page)
a-->d(type: screen)-->e(screen)
a-->f(type is event)-->g(track)
a-->h(type is not set)-->g
a-->i(type is notpage or screen)-->g
The Track v2 API works similarly. We map Track v2 calls to Pipelines track
, page
, and screen
methods when the incoming type
is person
and the action
is event
, page
, or screen
respectively.
The event name
maps directly to the event
key in the Pipelines API. The data
object in your event call maps to the properties
key in the Pipelines API. For page
calls, the event name
is typically the URL of the page a person viewed. For screen
calls, the event name
is typically the name of the screen in your app.
Track v1 API Call | Pipelines Result |
---|---|
|
|
Semantic Events
A number of default actionsThe source event and data that triggers an API call to your destination. For example, an incoming identify
event from your sources adds or updates a person in our Customer.io Journeys destination. for data out integrations are based on the event name in a track
call. We call these semantic events. If you send events with names and structures corresponding to our semantic events, you’ll be able to use our default actions in destinations without any extra work.
For example, we typically use an event name called Application Installed
to trigger the Add Device action in destinations.
Track API Call | Semantic event |
---|---|
|
|
Group calls (cio_relationships
)
In Customer.io Journeys, we refer to groups as objectsAn object is a non-person entity that you can associate with one or more people—like a company, account, or online course.. The Journeys Track API and associated integrations don’t have a specific endpoint to create groups. Instead, we base “group” calls on payloads of the Track API:
- Track v1 API:
identify
method containingcio_relationships
. - Track v2 API: Where
type
isobject
or wheneveraction
isadd_relationship
.
Because the Track API revolves around people, the calls in which you set relationships will result in two actions in Pipelines: one identify
call and one group
call.
While an identify
call including cio_relationships
will result in two actions (identify
and group
), we’ll just show the resulting group
call in the example below.
Track v1 API Call | Data out integration Result |
---|---|
|
|
Context from the Track API
Payloads for the Pipelines API contain a context
object including information about the source of the data. For data coming in through our Track API (including integrations like our classic JavaScript snippet), the context
contains a child object called journeys
with identifiers from the original call. This can help you understand which calls were made from the Track API (or our associated libraries).
The context
object contains a journeys.identifiers
object with identity information for the person or group represented in the original call.
{
"context": {
"journeys": {
"identifiers": {
"object_type_id": "1",
"object_id": "acme",
"id": "42",
}
}
}
}