11

Mapping Customer.io to outgoing integrations

How 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.

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.

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.

_cio.identify('customer-id', {
  "email": "customer@example.com",
  "created_at": 1361205308,
  "first_name": "Bob",
  "plan": "basic"
})

{
  "type": "identify",
  "traits": {
    "created_at": 1361205308,
    "first_name": "Bob",
    "plan": "basic"
  },
  "userId": "97980cfea0067",
  "integrations": {
    "All": true,
  },
  "sentAt": "2023-08-24T14:15:22Z",
  "messageId": "01H95X6RDPC4P9DHPC0JX52YKE",
  "timestamp": "2023-08-24T14:15:22Z",
  "context": {
    "journeys": {
      "identifiers": {
        "id": "customer-id",
        "email": "customer@example.com"
      }
    }
  }
}

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.

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.

curl --request POST \
  --url https://track.customer.io/api/v1/customers/customer-id/events \
  --header "Authorization: Basic $(echo -n site_id:api_key | base64)" \
  --header 'content-type: application/json' \
  --data '{"name":"Started Game","data":{"game":"checkers","moves":0}}'

{
  "type": "track",
  "event": "Started Game",
  "properties": {
    "game": "checkers",
    "moves": 0
  },
  "userId": "customer-id",
  "integrations": {
    "All": true,
  },
  "sentAt": "2023-08-24T14:15:22Z",
  "messageId": "01H95X6RDPC4P9DHPC0JX52YKE",
  "timestamp": "2023-08-24T14:15:22Z",
  "context": {
    "journeys": {
      "identifiers": {
        "id": "customer-id",
      }
    }
  }
}

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.

{
  "name": "Application Installed",
  "data": {
    "version": 1.2.3,
    "build": "v8"
  }
}

{
  "userId": "abcde12345",
  "type": "track",
  "event": "Application Installed",
  "properties": {
    "version": "1.2.3", 
    "build": "v8"
  }
}

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 containing cio_relationships.
• Track v2 API: Where type is object or whenever action is add_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.

curl --request PUT \
  --url https://track.customer.io/api/v1/customers/example-person-id \
  --header "Authorization: Basic $(echo -n site_id:api_key | base64)" \
  --header 'content-type: application/json' \
  --data '{
    "email": "person@example.com",
    "cio_relationships": {
        "action": "add_relationships",
        "relationships": [
            {
                "identifiers": {
                    "object_type_id": "1",
                    "object_id": "acme"
                }
            }
        ]
    },
  }'

{
  "userId": "97980cfea0067",
  "groupId": "acme",
  "traits": {},
  "integrations": {},
  "messageId": "01H95X6RDPC4P9DHPC0JX52YKE",
  "timestamp": "2023-08-23T22:28:55.111Z,",
  "context": {
    "journeys": {
      "identifiers": {
        "id": "example-person-id"
      }
    }
  },
  "receivedAt": "2023-08-23T22:28:55.387Z,",
  "type": "group"
}

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",
      }
    }
  }
}