Common fields

How it works

In general, your source calls will be short, but we capture much more information from our libraries and information implicit in each call, like:

context for the source of your calls
the ip and locale of the person the call represents
timestamps that help you understand the chronology of your data

The added context these common fields provide can help you debug issues with your data or add special handling in 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 downstream applications.

A full payload

Imagine you send the track call (using our JavaScript source) below. The call itself simply contains the event name and a properties object:

analytics.track("Report Submitted", {
  reportType: "sales",
  reportFormat: "csv"
})

But, when you look at your call in Data Pipelines, you’ll see the complete payload below. Our libraries and API automatically capture the context, integrations, messageId, receivedAt, sentAt, version, type (which is implicit in the method/endpoint you call), and timestamp properties.

{
  "userId": "AiUGstSDIg",
  "event": "Report Submitted",
  "properties": {
    "reportType": "sales",
    "reportFormat": "csv"
  },
  "integrations": {
    "All": true
  },
  "messageId": "ajs-f8ca1e4de5024d9430b3928bd8ac6b96",
  "timestamp": "2015-12-12T19:11:01.249Z",
  "context": {
    "active": true,
    "ip": "108.0.78.21",
    "locale": "string",
    "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_11_0) AppleWebKit/537.36 (KHTML like Gecko) Chrome/46.0.2490.86 Safari/537.36",
    "channel": "browser",
    "campaign": {
      "name": "string",
      "source": "string",
      "medium": "string",
      "term": "string",
      "content": "string",
    },
    "page": {
      "name": "string",
      "path": "/docs/",
      "referrer": null,
      "search": null,
      "title": "Customer.io Docs",
      "url": "https://customer.io/docs",
      "keywords": [
        "report"
      ]
    },
    "library": {
      "name": "analytics.js",
      "version": "2.11.1"
    }
  },
  "anonymousId": "23adfd82-aa0f-45a7-a756-24f2a7a4c895",
  "receivedAt": "2015-12-12T19:11:01.266Z",
  "sentAt": "2015-12-12T19:11:01.169Z",
  "type": "track",
  "originalTimestamp": "2015-12-12T19:11:01.152Z"
}

Here are the fields that are common to all source calls, many of which are implicit and set by Customer.io.

integrations object
Contains a list of booleans indicating the integrations that are enabled (true) or disabled (false). By default, all integrations are enabled (returning an empty object). Set "All": false to reverse this behavior.
- Enabled/Disabled integrations* boolean
messageId string
A unique identifier for a Data Pipelines call, ensuring that each individual event is unique. This is set by Customer.io
receivedAt string (date-time)
The ISO-8601 timestamp when Data Pipelines receives an event.
sentAt string (date-time)
The ISO-8601 timestamp when a library sends an event to Data Pipelines.
timestamp string (date-time)
The ISO-8601 timestamp when the event originally took place. This is mostly useful when you backfill data past events. If you’re not backfilling data, you can leave this field empty and we’ll use the current time or server time.
type string
The type of source event. This is implicit and set by Customer.io based on the endpoint/method you use (e.g. identify).
Accepted values:identify,group,track,page,screen,alias
version number
The version of the API that received the event, automatically set by Customer.io.
context
A dictionary of context about a source call/event, like the user’s IP address or locale. Context is automatically collected by our source libraries.
- active boolean
  
  Whether a user is active.
  This is usually used to flag an .identify() call to just update the traits but not “last seen.”
- channel string
  The channel the event originated from.
  Accepted values:browser,server,mobile
- ip string
  The user’s IP address. This isn’t captured by our libraries, but by our servers when we receive client-side events (like from our JavaScript source).
- locale string
  The local string for the current user, e.g. en-US.
- userAgent string
  The user agent of the device making the request
- campaign object
  Contains information about the campaign that resulted in the API call, gathered from, or mapping to, UTM parameters (e.g. utm_source).
  - content string
  - medium string
    The type of traffic a person/event originates from, like email, or referral.
  - name string
    The campaign name.
  - source string
    The source of traffic—like the name of your email list, Facebook, Google, etc.
  - term string
    The keyword term(s) a user came from.
  - Additional UTM Parameters* string
- page object
  Contains information about the current page in the browser. This is automatically collected by our JavaScript source.
  - keywords array of [ strings ]
    A list/array of keywords describing the page’s content. The keywords are likely the same as, or similar to, the keywords you would find in an HTML meta tag for SEO purposes. This property is mainly used by content publishers that rely heavily on pageview tracking. This isn’t automatically collected.
  - name string
    The name of the page. Reserved for future use.
  - path string
    The path portion of the page’s URL. Equivalent to the canonical path which defaults to location.pathname from the DOM API.
  - referrer string
    The previous page’s full URL. Equivalent to document.referrer from the DOM API.
  - search string
    The query string portion of the page’s URL. Equivalent to location.search from the DOM API.
  - title string
    The page’s title. Equivalent to document.title from the DOM API.
  - url string
    A page’s full URL. Segment first looks for the canonical URL. If the canonical URL is not provided, Segment uses location.href from the DOM API.
- active boolean
  
  Whether a user is active.
  This is usually used to flag an .identify() call to just update the traits but not “last seen.”
- channel string
  The channel the event originated from.
  Accepted values:browser,server,mobile
- ip string
  The user’s IP address. This isn’t captured by our libraries, but by our servers when we receive client-side events (like from our JavaScript source).
- locale string
  The local string for the current user, e.g. en-US.
- userAgent string
  The user agent of the device making the request
- app object
  Contains information about the mobile app the event originated from, automatically collected by our mobile libraries when possible.
  - build string
    The specific build number in the app.
  - name string
    The name of the app.
  - namespace string
    The app’s namespace.
  - version string
    The version of the app the call originated from.
- device object
  Contains information about the device the event originated from.
  - advertisingId string
    The advertising ID is a unique, anonymous ID for advertising.
  - id string
    The device ID.
  - manufacturer string
    The device manufacturer.
  - model string
    The device model.
  - name string
    The device name.
  - type string
    The device type—android, iOS, etc.
    Accepted values:android,ios
  - version string
    The firmware version for the device.
- network object
  Information about the current network connection, containing bluetooth, carrier, cellular, and wifi. If the context.network.cellular and context.network.wifi fields are empty, then the user is offline.
  - bluetooth boolean
    Lets you know if bluetooth is enabled on a device.
  - carrier string
    The cellular carrier the phone uses.
  - cellular boolean
    Indicates whether the device’s cellular connection is enabled or not.
  - wifi boolean
    Indicates whether a device’s wifi connection is enabled or not.
- os object
  Dictionary of information about the operating system, containing name and version.
  - name string
    The operating system running on the device.
  - version string
    The version of the OS running on the device.

The context object

The context object contains useful information about the origin of a call, like the page the call originates from, or the ip address of the user the call represents.

You’ll notice slightly different context depending on whether the source of a call is a mobile SDK or non-mobile libraries. Our mobile libraries capture information about a device rather than a page.

If you use our server libraries, you’ll need to set this information yourself. Make sure that you use these properties for their originally-intended purpose; setting values that don’t make sense for the property can result in unexpected behaviors in downstream applications that rely on context.

active boolean

Whether a user is active.
This is usually used to flag an .identify() call to just update the traits but not “last seen.”
channel string
The channel the event originated from.
Accepted values:browser,server,mobile
ip string
The user’s IP address. This isn’t captured by our libraries, but by our servers when we receive client-side events (like from our JavaScript source).
locale string
The local string for the current user, e.g. en-US.
userAgent string
The user agent of the device making the request
campaign object
Contains information about the campaign that resulted in the API call, gathered from, or mapping to, UTM parameters (e.g. utm_source).
- content string
- medium string
  The type of traffic a person/event originates from, like email, or referral.
- name string
  The campaign name.
- source string
  The source of traffic—like the name of your email list, Facebook, Google, etc.
- term string
  The keyword term(s) a user came from.
- Additional UTM Parameters* string
page object
Contains information about the current page in the browser. This is automatically collected by our JavaScript source.
- keywords array of [ strings ]
  A list/array of keywords describing the page’s content. The keywords are likely the same as, or similar to, the keywords you would find in an HTML meta tag for SEO purposes. This property is mainly used by content publishers that rely heavily on pageview tracking. This isn’t automatically collected.
- name string
  The name of the page. Reserved for future use.
- path string
  The path portion of the page’s URL. Equivalent to the canonical path which defaults to location.pathname from the DOM API.
- referrer string
  The previous page’s full URL. Equivalent to document.referrer from the DOM API.
- search string
  The query string portion of the page’s URL. Equivalent to location.search from the DOM API.
- title string
  The page’s title. Equivalent to document.title from the DOM API.
- url string
  A page’s full URL. Segment first looks for the canonical URL. If the canonical URL is not provided, Segment uses location.href from the DOM API.

Automatically-collected fields

Our JavaScript, mobile, and server libraries capture the information below.

For now, our mobile libraries collect very few fields but we’re working on changes that will increase the context they capture.

Our server-side libraries generally require you to send context and other common fields yourself. They’ll set the context.library property, but you should check with the appropriate documentation for the server library you use for help adding context to your calls.

Context Field	JavaScript (Web)	Mobile	Server
app.name
app.version
app.build
campaign.name	✅
campaign.source	✅
campaign.medium	✅
campaign.term	✅
campaign.content	✅
device.type
device.id
device.advertisingId
device.adTrackingEnabled
device.manufacturer
device.model
device.name
journeys.identifiers		✅
library.name	✅		✅
library.version	✅		✅
ip¹	✅	✅
locale	✅
network.bluetooth
network.carrier
network.cellular
network.wifi
os.name
os.version
page.path	✅
page.referrer	✅
page.search	✅
page.title	✅
page.url	✅
screen.height
screen.width
traits
userAgent	✅	✅
userAgentData²	✅
timezone

¹Our libraries don’t capture IP address. Our servers fill in this information when we receive calls from our JavaScript or mobile libraries.

²We only collect userAgentData when the Client Hints API is available in the browser.

The integrations object

By default, we send your source data to all destinations connected to the source. But you can limit a source call to a specific subset of destinations using the integrations object.

In general, we recommend that you filter calls for each destination using 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., because they’re easier to change and manage than your source code. But you might want to modify the integrations object if:

You have a destination that bills you for incoming API calls and you want to limit traffic to that destination.
if you know that information in the individual call is only useful in specific downstream destinations.

To limit a call to specific destinations, you need to set "All": false and set true for the integrations you want to send to.

Within the integrations object, you need to use the integration name exactly as we show it at the top of every destination page in our catalog. For example, if you simply used Mixpanel below, we may not recognize the integration and send the call to your Mixpanel destination.

{
    "integrations": {
        "All": false,
        "Actions Customerio": true,
        "Google Analytics 4 Cloud": true,
        "Mixpanel (Actions)": true
    }
}

find the integration name in our catalog pages

Timestamps

Every call includes ISO-8601 timestamps, originalTimestamp, timestamp, sentAt, and receivedAt, each with different purposes.

When analyzing your data, we recommend that you use receivedAt when chronology doesn’t matter and timestamp when it does. This is because receivedAt is typically correct but not guaranteed to be in chronological order, but the formula we apply to timestamp ensures that it is always in chronological order.

Timestamp	Calculated	Description
`originalTimestamp`	The date-time on the client device when you invoked a call or a value that you pass manually from a server-side library.	Used to calculate `timestamp`.
`sentAt`	The date-time on client device when you invoked a call or a value that you set manually in your call.	Used to calculate `timestamp`.
`receivedAt`	The date-time when Customer.io received a call.	Used to calculate `timestamp` and used as sort key in data warehouse destinations.
`timestamp`	Calculated by Customer.io to correct client-device clock skew using the formula: `receivedAt` - (`sentAt` - `originalTimestamp`).	Used to send data to downstream destinations and in data replays.

Copied to clipboard!

Latest features at Customer.io

Reorganize in-app messages with drag-and-drop

Assign subscription topics in bulk to live campaigns and broadcasts

Jump to components in your in-app messages

Common fields

How it works

A full payload

The context object

Automatically-collected fields

The integrations object

Timestamps

Latest features at Customer.io

Reorganize in-app messages with drag-and-drop

Assign subscription topics in bulk to live campaigns and broadcasts

Jump to components in your in-app messages

Common fields

How it works

A full payload

The context object

Automatically-collected fields

The integrations object

Timestamps

How can we make it better?