> This page is part of the [Customer.io documentation](https://docs.customer.io). For the complete index, see [llms.txt](https://docs.customer.io/llms.txt).
> Last updated: June 27, 2025

# Mapping Customer.io to outgoing integrations

## How it works

When we receive traffic from some integrations, like the [Track API](/integrations/api/track/), we translate them to our newer and more generic [Pipelines format](/integrations/api/cdp/) to better support downstream, data outAn integration that sends data *out* of Customer.io. [integrations](/integrations/catalog/). 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](/integrations/data-in/connections/classic-api/cio-journeys-api).

## 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](#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](#group-calls) calls below for more information.

Track v1 API Call

Pipelines Result

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

```json
{
  "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.

Track v1 API Call

Pipelines Result

```bash
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}}'
```

```json
{
  "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.

Track API Call

Semantic event

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

```json
{
  "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.](/journeys/objects-data/objects/). 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.

Track v1 API Call

Data out integration Result

```bash
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"
                }
            }
        ]
    },
  }'
```

```json
{
  "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.

```json
{
  "context": {
    "journeys": {
      "identifiers": {
        "object_type_id": "1",
        "object_id": "acme",
        "id": "42",
      }
    }
  }
}
```

*   *   [How it works](#how-it-works)
    *   [How the Track API maps to the Pipelines API](#how-the-track-api-maps-to-the-pipelines-api)
        *   [Mapping Track v2 calls](#mapping-track-v2-calls)
    *   [Identify](#identify)
    *   [Track, page, and screen events](#track-page-and-screen-events)
        *   [Semantic Events](#semantic-events)
    *   [Group calls (`cio_relationships`)](#group-calls)
    *   [Context from the Track API](#context-object)

Copy page

Copy page [Download .md](/integrations/data-in/connections/classic-api/journeys-track-mappings.md)

Is this page helpful?

![](https://docs.customer.io/images/export-success.png) ![](https://docs.customer.io/images/export-failure.png)

# How can we make it better?

Close

Do you need help from Customer.io support?  No  
 Yes

What part of Customer.io do you need help with? 

How can we improve this page?

Email (optional):  Please provide a valid email address

 I am not a bot

 

We appreciate your feedback!

Our support team will contact you as soon as possible