Customer.io · Schema
batch
Behavioral DataBroadcastCampaignsCDPCustomer DataCustomer Data PlatformData IngestionEmailEvent TrackingMarketing AutomationMessagingPush NotificationsSegmentsSMSTransactional EmailA2A
Properties
| Name | Type | Description |
|---|---|---|
| batch | array | A group of requests you want to send to Data Pipelines in the call. |
| context | object | 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. |
| integrations | object |
JSON Schema
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"$id": "https://raw.githubusercontent.com/api-evangelist/customer-io/main/json-schema/customer-io-batch-schema.json",
"title": "batch",
"x-generated": "2026-10-12",
"x-method": "derived",
"x-generator": "derive-json-schema.py",
"x-source": "openapi/customer-io-batch-api-openapi.yml#/components/schemas/batch",
"x-scalar-ignore": true,
"type": "object",
"properties": {
"batch": {
"type": "array",
"description": "A group of requests you want to send to Data Pipelines in the call.",
"items": {
"anyOf": [
{
"title": "Identify",
"$ref": "#/$defs/identify"
},
{
"title": "Track",
"oneOf": [
{
"title": "Known User",
"allOf": [
{
"type": "object",
"required": [
"userId",
"event",
"type"
],
"properties": {
"userId": {
"$ref": "#/$defs/userId"
},
"type": {
"type": "string",
"enum": [
"track"
],
"description": "The event type. This is set automatically by the request method/endpoint."
},
"event": {
"type": "string",
"description": "The name of the event"
},
"properties": {
"type": "object",
"description": "Additional properties for your event.",
"additionalProperties": {
"x-additionalPropertiesName": "Event Properties",
"description": "Additional properties that you want to capture in the event. These can take any JSON shape."
}
}
}
}
]
},
{
"title": "Anonymous User",
"allOf": [
{
"type": "object",
"required": [
"event",
"type"
],
"properties": {
"anonymousId": {
"$ref": "#/$defs/anonymousId"
},
"type": {
"type": "string",
"enum": [
"track"
],
"description": "The event type. This is set automatically by the request method/endpoint."
},
"event": {
"type": "string",
"description": "The name of the event"
},
"properties": {
"type": "object",
"description": "Additional properties for your event.",
"additionalProperties": {
"x-additionalPropertiesName": "Event Properties",
"description": "Additional properties that you want to capture in the event. These can take any JSON shape."
}
}
}
}
]
}
]
},
{
"title": "Page",
"oneOf": [
{
"title": "Known User",
"allOf": [
{
"type": "object",
"required": [
"userId",
"type"
],
"properties": {
"userId": {
"$ref": "#/$defs/userId"
},
"type": {
"type": "string",
"enum": [
"page"
],
"description": "The event type. This is set automatically by the request method/endpoint."
},
"name": {
"type": "string",
"description": "The name of the page."
},
"properties": {
"type": "object",
"description": "Additional properties for your event.",
"properties": {
"category": {
"type": "string",
"description": "The category of the page. This might be useful if you have a single page routes or have a flattened URL structure."
}
},
"additionalProperties": {
"x-additionalPropertiesName": "Page Properties",
"description": "A dictionary of properties about the page."
}
}
}
}
]
},
{
"title": "Anonymous User",
"allOf": [
{
"type": "object",
"required": [
"anonymousId",
"type"
],
"properties": {
"anonymousId": {
"$ref": "#/$defs/anonymousId"
},
"type": {
"type": "string",
"enum": [
"page"
],
"description": "The event type. This is set automatically by the request method/endpoint."
},
"name": {
"type": "string",
"description": "The name of the page."
},
"properties": {
"type": "object",
"description": "Additional properties for your event.",
"properties": {
"category": {
"type": "string",
"description": "The category of the page. This might be useful if you have a single page routes or have a flattened URL structure."
}
},
"additionalProperties": {
"x-additionalPropertiesName": "Page Properties",
"description": "A dictionary of properties about the page."
}
}
}
}
]
}
]
},
{
"title": "Screen",
"oneOf": [
{
"title": "Known User",
"allOf": [
{
"type": "object",
"required": [
"userId",
"type"
],
"properties": {
"userId": {
"$ref": "#/$defs/userId"
},
"type": {
"type": "string",
"enum": [
"screen"
],
"description": "The event type. This is set automatically by the request method/endpoint."
},
"name": {
"type": "string",
"description": "The name of the screen the person visited."
},
"properties": {
"type": "object",
"description": "Additional properties for your screen.",
"additionalProperties": {
"x-additionalPropertiesName": "Screen Properties",
"description": "A dictionary of properties about the screen."
}
}
}
}
]
},
{
"title": "Anonymous User",
"allOf": [
{
"type": "object",
"required": [
"anonymousId",
"type"
],
"properties": {
"anonymousId": {
"$ref": "#/$defs/anonymousId"
},
"type": {
"type": "string",
"enum": [
"screen"
],
"description": "The event type. This is set automatically by the request method/endpoint."
},
"name": {
"type": "string",
"description": "The name of the screen the person visited."
},
"properties": {
"type": "object",
"description": "Additional properties for your screen.",
"additionalProperties": {
"x-additionalPropertiesName": "Screen Properties",
"description": "A dictionary of properties about the screen."
}
}
}
}
]
}
]
},
{
"title": "Group",
"oneOf": [
{
"title": "Known User",
"allOf": [
{
"type": "object",
"required": [
"userId",
"groupId",
"type"
],
"properties": {
"userId": {
"$ref": "#/$defs/userId"
},
"type": {
"type": "string",
"enum": [
"group"
],
"description": "The event type. This is set automatically by the request method/endpoint."
},
"groupId": {
"type": "string",
"description": "ID of the group"
},
"traits": {
"type": "object",
"description": "Additional information about the group.",
"additionalProperties": {
"x-additionalPropertiesName": "Group Traits",
"description": "A dictionary of traits for the group."
}
}
}
}
]
},
{
"title": "Anonymous User",
"allOf": [
{
"type": "object",
"required": [
"anonymousId",
"groupId",
"type"
],
"properties": {
"anonymousId": {
"$ref": "#/$defs/anonymousId"
},
"type": {
"type": "string",
"enum": [
"group"
],
"description": "The event type. This is set automatically by the request method/endpoint."
},
"groupId": {
"type": "string",
"description": "ID of the group"
},
"traits": {
"type": "object",
"description": "Additional information about the group.",
"additionalProperties": {
"x-additionalPropertiesName": "Group Traits",
"description": "A dictionary of traits for the group."
}
}
}
}
]
}
]
}
]
}
},
"context": {
"description": "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.",
"oneOf": [
{
"$ref": "#/$defs/context_non_mobile"
},
{
"$ref": "#/$defs/context_mobile"
}
]
},
"integrations": {
"$ref": "#/$defs/integrations"
}
},
"$defs": {
"all_common_fields": {
"x-scalar-ignore": true,
"allOf": [
{
"$ref": "#/$defs/common_fields"
},
{
"type": "object",
"properties": {
"context": {
"description": "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.",
"oneOf": [
{
"$ref": "#/$defs/context_non_mobile"
},
{
"$ref": "#/$defs/context_mobile"
}
]
}
}
}
]
},
"anonymousId": {
"x-scalar-ignore": true,
"type": "string",
"description": "A unique substitute for a User ID in cases when you don’t have an absolutely unique identifier. Our libraries generate this value automatically to help you track people before they sign up, log in, provide their email, etc."
},
"common_fields": {
"x-scalar-ignore": true,
"type": "object",
"properties": {
"integrations": {
"$ref": "#/$defs/integrations"
},
"messageId": {
"type": "string",
"description": "A unique identifier for a Data Pipelines call, ensuring that each individual event is unique. This is set by Customer.io"
},
"receivedAt": {
"type": "string",
"format": "date-time",
"readOnly": true,
"description": "The ISO-8601 timestamp when Data Pipelines receives an event."
},
"sentAt": {
"type": "string",
"format": "date-time",
"description": "The ISO-8601 timestamp when a library sends an event to Data Pipelines."
},
"originalTimestamp": {
"type": "string",
"format": "date-time",
"description": "In general, you can use `timestamp` rather than this field if you want to back-date events. This is the timestamp on the client device you invoke a call or the timestamp value you manually passed in a server-side library call."
},
"timestamp": {
"type": "string",
"format": "date-time",
"description": "The ISO-8601 timestamp when the event originally took place. This is mostly useful when you backfill 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": {
"readOnly": true,
"type": "string",
"enum": [
"identify",
"group",
"track",
"page",
"screen",
"alias"
],
"description": "The type of source event. This is implicit and set by Customer.io based on the endpoint/method you use (e.g. `identify`)."
},
"version": {
"readOnly": true,
"type": "number",
"description": "The version of the API that received the event, automatically set by Customer.io."
}
}
},
"context_common": {
"x-scalar-ignore": true,
"type": "object",
"description": "Contains contextual information about the event.",
"properties": {
"active": {
"type": "boolean",
"description": "Whether a user is active.\n\nThis is usually used when you send an .identify() call to update the traits independently of when you've “last seen” a user.\n"
},
"ip": {
"type": "string",
"description": "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": {
"type": "string",
"description": "The locale string for the current user, e.g. `en-US`."
},
"userAgent": {
"type": "string",
"description": "The user agent of the device making the request"
},
"channel": {
"type": "string",
"enum": [
"browser",
"server",
"mobile"
],
"description": "The channel the event originated from."
}
}
},
"context_mobile": {
"x-scalar-ignore": true,
"description": "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.",
"title": "Mobile",
"allOf": [
{
"$ref": "#/$defs/context_common"
},
{
"type": "object",
"description": "Fields included in events from mobile libraries.",
"properties": {
"app": {
"type": "object",
"description": "Contains information about the mobile app the event originated from, automatically collected by our mobile libraries when possible.\n",
"properties": {
"name": {
"type": "string",
"description": "The name of the app."
},
"version": {
"type": "string",
"description": "The version of the app the call originated from."
},
"build": {
"type": "string",
"description": "The specific build number in the app."
},
"namespace": {
"type": "string",
"description": "The app's namespace."
}
}
},
"device": {
"type": "object",
"description": "Contains information about the device the event originated from.\n",
"properties": {
"id": {
"type": "string",
"description": "The device ID."
},
"advertisingId": {
"type": "string",
"description": "The advertising ID is a unique, anonymous ID for advertising."
},
"manufacturer": {
"type": "string",
"description": "The device manufacturer."
},
"model": {
"type": "string",
"description": "The device model."
},
"name": {
"type": "string",
"description": "The device name."
},
"type": {
"type": "string",
"description": "The device type—android, iOS, etc.",
"enum": [
"android",
"ios"
]
},
"version": {
"type": "string",
"description": "The firmware version for the device."
}
}
},
"network": {
"type": "object",
"description": "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.",
"properties": {
"bluetooth": {
"type": "boolean",
"description": "Lets you know if bluetooth is enabled on a device."
},
"carrier": {
"type": "string",
"description": "The cellular carrier the phone uses."
},
"cellular": {
"type": "boolean",
"description": "Indicates whether the device's cellular connection is enabled or not."
},
"wifi": {
"type": "boolean",
"description": "Indicates whether a device's wifi connection is enabled or not."
}
}
},
"os": {
"type": "object",
"description": "Dictionary of information about the operating system, containing `name` and `version`.\n",
"properties": {
"name": {
"type": "string",
"description": "The operating system running on the device."
},
"version": {
"type": "string",
"description": "The version of the OS running on the device."
}
}
}
}
}
]
},
"context_non_mobile": {
"x-scalar-ignore": true,
"description": "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.",
"title": "Non-mobile",
"allOf": [
{
"$ref": "#/$defs/context_common"
},
{
"type": "object",
"properties": {
"campaign": {
"type": "object",
"description": "Contains information about the campaign that resulted in the API call, gathered from, or mapping to, UTM parameters (e.g. `utm_source`).\n",
"properties": {
"name": {
"type": "string",
"description": "The campaign name."
},
"source": {
"type": "string",
"description": "The source of traffic—like the name of your email list, Facebook, Google, etc."
},
"medium": {
"type": "string",
"description": "The type of traffic a person/event originates from, like `email`, or `referral`."
},
"term": {
"type": "string",
"description": "The keyword term(s) a user came from."
},
"content": {
"type": "string"
}
},
"additionalProperties": {
"type": "string",
"x-additionalPropertiesName": "Additional UTM Parameters"
}
},
"page": {
"$ref": "#/$defs/context_page"
}
}
}
]
},
"context_page": {
"x-scalar-ignore": true,
"type": "object",
"description": "Contains information about the current page in the browser. This is automatically collected by our JavaScript source.",
"properties": {
"name": {
"type": "string",
"description": "The name of the page. Reserved for future use.\n"
},
"path": {
"type": "string",
"description": "The path portion of the page's URL. Equivalent to the canonical `path` which defaults to `location.pathname` from the DOM API."
},
"referrer": {
"type": "string",
"description": "The previous page's full URL. Equivalent to `document.referrer` from the DOM API."
},
"search": {
"type": "string",
"description": "The query string portion of the page's URL. Equivalent to `location.search` from the DOM API."
},
"title": {
"type": "string",
"description": "The page's title. Equivalent to `document.title` from the DOM API."
},
"url": {
"type": "string",
"description": "A page's full URL. We first look for the canonical URL. If the canonical URL is not provided, we'll use `location.href` from the DOM API."
},
"keywords": {
"type": "array",
"description": "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.",
"items": {
"type": "string"
}
}
}
},
"identify": {
"x-scalar-ignore": true,
"oneOf": [
{
"title": "Known User",
"allOf": [
{
"type": "object",
"required": [
"userId"
],
"properties": {
"userId": {
"$ref": "#/$defs/userId"
},
"anonymousId": {
"$ref": "#/$defs/anonymousId"
},
"type": {
"type": "string",
"enum": [
"identify"
],
"description": "The event type. This is set automatically by the request method/endpoint."
},
"traits": {
"type": "object",
"description": "Additional properties that you know about a person. We've listed some common/reserved traits below, but you can add any traits that you might use in another system.",
"properties": {
"email": {
"type": "string",
"description": "A person's email address. In some cases, you can pass an empty `userId` and we'll use this value to identify a person."
},
"createdAt": {
"type": "string",
"format": "date-time",
"description": "We recommend that you pass date-time values as ISO 8601 date-time strings. We convert this value to fit destinations where appropriate."
},
"cio_subscription_preferences": {
"description": "Stores your audience's subscription preferences if you enable our [subscription center](/journeys/channels/subscriptions/center/) feature. These items are set automatically when people use the unsubscribe link in your messages, but you can set preferences outside the subscription flow. To update select topic preferences while preserving those set for other topics, use JSON dot notation `\"cio_subscription_preferences.topics.topic_<topic ID>\":<boolean>`. To update channel preferences, use `\"cio_subscription_preferences.channels.<channel>\":<boolean>`.",
"type": "object",
"properties": {
"topics": {
"type": "object",
"description": "Contains active topics in your workspace, named `topic_<id>`.",
"additionalProperties": {
"x-additionalPropertiesName": "topic_<id>",
"description": "Each property is a boolean named `topic_<id>`. Topic `id` values begin at `1` and increment for each new topic. You can find your topic ids in [Workspace Settings](https://fly.customer.io/workspaces/last/settings/subscription_center/topics) or by querying our [App API](https://customer.io/api/app/#operation/getTopics). For each boolean, `true` means that a person is subscribed to the topic; false means they are unsubscribed. An empty or missing value reverts to the default preference for the topic (opt-in or opt-out).",
"type": "boolean"
}
},
"channels": {
"type": "object",
"description": "Contains channel subscription preferences. Keys are channel type names.",
"additionalProperties": {
"x-additionalPropertiesName": "channel_type",
"description": "Each property is a boolean keyed by the channel type name: `email`, `sms`, `push`, `in_app`, `whatsapp`, `slack`, `line`, or `inbox`. `true` means a person is subscribed to the channel; `false` means they are unsubscribed. Both the topic and channel must be subscribed for a message to send.",
"type": "boolean"
}
}
}
},
"unsubscribed": {
"description": "If `true`, a person is unsubscribed from emails, SMS, WhatsApp, and push notifications (not in-app messages). Any casing of \"true\" (i.e. TRUE, true, tRUe, etc.), 1, or \"1\" means the person is unsubscribed. If `false`, absent, or any value not considered \"true\", a person is globally subscribed, or if you enabled a subscription center, a person will receive messages based on their `cio_subscription_preferences`.",
"type": "boolean"
}
},
"additionalProperties": {
"x-additionalPropertiesName": "Additional Traits",
"description": "Traits that you want to set on a person. These can take any JSON shape."
}
}
}
},
{
"$ref": "#/$defs/all_common_fields"
}
]
},
{
"title": "Anonymous User",
"allOf": [
{
"type": "object",
"required": [
"anonymousId"
],
"properties": {
"anonymousId": {
"$ref": "#/$defs/anonymousId"
},
"type": {
"type": "string",
"enum": [
"identify"
],
"description": "The event type. This is set automatically by the request method/endpoint."
},
"traits": {
"type": "object",
"description": "Additional properties that you know about a person. We've listed some common/reserved traits below, but you can add any traits that you might use in another system.",
"properties": {
"email": {
"type": "string",
"description": "A person's email address. In some cases, you can pass an empty `userId` and we'll use this value to identify a person."
},
"createdAt": {
"type": "string",
"format": "date-time",
"description": "We recommend that you pass date-time values as ISO 8601 date-time strings. We convert this value to fit destinations where appropriate."
}
},
"additionalProperties": {
"x-additionalPropertiesName": "Additional Traits",
"description": "Traits that you want to set on a person. These can take any JSON shape."
}
}
}
},
{
"$ref": "#/$defs/all_common_fields"
}
]
}
]
},
"integrations": {
"x-scalar-ignore": true,
"type": "object",
"description": "Contains a
# --- truncated at 32 KB (32 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/customer-io/refs/heads/main/json-schema/customer-io-batch-schema.json
Work with this as data
Every JSON Schema here is available over the APIs.io API and to AI agents over MCP.
MCP server
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
Tools for schemas
4 MCP tools reach this
find_json_schemasBrowse and filter every JSON Schema in the catalog.apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.resolveTurn a domain, URL or GitHub org into the provider it belongs to.find_cohortsEvery scored population of providers in the catalog.
Call it yourself
curl for this page
This JSON Schema
curl "https://apis.io/api/v1/json-schemas/customer-io-batch"
All schemas
curl "https://apis.io/api/v1/json-schemas?limit=25"Discovery needs no key. Ratings and market analysis are Pro.
Get an API key
Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.
A second provider on the same verified email joins the account you already have.