A reference guide for building AI agents: every method, how to authenticate, and the permissions each one needs.
The Customer.io API is how an app or AI agent works with a Customer.io workspace: identifying people, tracking events and device tokens, sending transactional and broadcast messages, and reading back customers, segments, and message metrics. Access is split across two credentials, a Site ID and key for sending data in and a separate App API key for messaging and management, and an agent is limited to the workspace each credential belongs to. Customer.io can also push events to a webhook when a message is delivered, opened, or clicked.
How an app or AI agent connects to Customer.io determines what it can reach. Customer.io is split into two separate APIs with two separate credentials, one for sending in customer data and one for messaging and management, and each carries its own kind of access.
The Track API takes customer data into a workspace, identifying and updating people, tracking events, and managing device tokens. It answers at track.customer.io, or track-eu.customer.io in the EU region, and uses Basic auth with the Site ID and Track API key.
The App API sends messages and reads back data: transactional and broadcast sends, customer search, segments, broadcasts, and collections. It answers at api.customer.io, or api-eu.customer.io in the EU region, and uses a Bearer App API key generated in the UI.
Reporting webhooks post a JSON payload to a registered URL each time a message metric fires, such as an email being delivered, opened, or clicked. The X-CIO-Signature header, an HMAC-SHA256 of the signing key over the body, lets the receiver verify the request.
Customer.io's hosted MCP server lets an agent call Customer.io through the Model Context Protocol. It answers at https://mcp.customer.io/mcp, or https://mcp-eu.customer.io/mcp in the EU region, exposes the Journeys UI API and CDP Data Pipelines API through read, write, and delete tools, and authenticates with OAuth that respects the signed-in user's role and permissions.
The Track API uses Basic auth, with the Site ID as the username and the Track API key as the password, Base-64 encoded. It carries no per-endpoint scopes and reaches everything in its workspace.
The App API uses a Bearer token, the App API key, generated in the UI with a scope chosen at creation. It is workspace-scoped and is the recommended credential for production messaging and data reads.
The transactional send endpoints also accept a service-account Bearer token, prefixed sa_live_, which works across workspaces and requires an X-Workspace-Id header naming the target workspace. Customer.io recommends an App API key for production, since a service-account token has a wider blast radius.
Customer.io splits into two APIs an agent can act on. The Track API takes in people, events, and devices; the App API sends messages and reads back customers, segments, broadcasts, and collections. Each uses a different credential, and the two are not interchangeable.
Identify and update people, delete or suppress them, manage device tokens, and track customer, anonymous, and form events.
Create, update, or delete a single person or object, and send many such operations in one batched request.
Send transactional email, push, SMS, and in-app messages, trigger API broadcasts, and send or schedule newsletters.
Search for customers, look up a customer's attributes, relationships, segments, messages, and activities.
Create, list, read, and delete manual segments, count their members, and add or remove people.
List and read broadcasts and campaigns, get their metrics, and read the status and errors of a triggered broadcast.
Create, list, look up, update, and delete collections, the reusable data sets referenced inside messages.
Create, list, read, update, and delete the reporting webhooks that deliver message events.
Filter by method, access, or permission, or search any path. Select a row for version detail, rate limits, the related webhook event, and the source.
| Method | Endpoint | What it does | Access | Permission | Version | |
|---|---|---|---|---|---|---|
People & eventsIdentify and update people, delete or suppress them, manage device tokens, and track customer, anonymous, and form events.9 | ||||||
| PUT | /api/v1/customers/{identifier} | Add or update a person, setting attributes on their profile. | write | Track API key | Current | |
Track endpoints use Basic auth with the Site ID as the username and the Track API key as the password. There are no per-endpoint scopes; the key reaches everything in its workspace. Acts onperson Permission (capability) Track API keyVersionAvailable since the API’s base version Webhook eventNone Rate limit1000 requests per second (Track API) SourceOfficial documentation ↗ | ||||||
| DELETE | /api/v1/customers/{identifier} | Delete a person from the workspace. | write | Track API key | Current | |
Track endpoints use Basic auth with the Site ID and Track API key. There are no per-endpoint scopes. Acts onperson Permission (capability) Track API keyVersionAvailable since the API’s base version Webhook eventNone Rate limit1000 requests per second (Track API) SourceOfficial documentation ↗ | ||||||
| PUT | /api/v1/customers/{identifier}/devices | Add or update a person's device token for push messaging. | write | Track API key | Current | |
Track endpoints use Basic auth with the Site ID and Track API key. Acts ondevice Permission (capability) Track API keyVersionAvailable since the API’s base version Webhook eventNone Rate limit1000 requests per second (Track API) SourceOfficial documentation ↗ | ||||||
| DELETE | /api/v1/customers/{identifier}/devices/{device_id} | Delete a person's device token. | write | Track API key | Current | |
Track endpoints use Basic auth with the Site ID and Track API key. Acts ondevice Permission (capability) Track API keyVersionAvailable since the API’s base version Webhook eventNone Rate limit1000 requests per second (Track API) SourceOfficial documentation ↗ | ||||||
| POST | /api/v1/customers/{identifier}/suppress | Suppress a person so they no longer receive messages or get tracked. | write | Track API key | Current | |
Track endpoints use Basic auth with the Site ID and Track API key. Suppressing is distinct from deleting; the profile stays but is held back from messaging. Acts onperson Permission (capability) Track API keyVersionAvailable since the API’s base version Webhook eventNone Rate limit1000 requests per second (Track API) SourceOfficial documentation ↗ | ||||||
| POST | /api/v1/customers/{identifier}/events | Track an event for a known person, which can trigger campaigns or segment membership. | write | Track API key | Current | |
Track endpoints use Basic auth with the Site ID and Track API key. Events tracked here are automatically associated with the person. Acts onevent Permission (capability) Track API keyVersionAvailable since the API’s base version Webhook eventNone Rate limit1000 requests per second (Track API) SourceOfficial documentation ↗ | ||||||
| POST | /api/v1/events | Track an anonymous event not yet tied to a known person. | write | Track API key | Current | |
Track endpoints use Basic auth with the Site ID and Track API key. Anonymous events can be associated with a person later when they are identified. Acts onevent Permission (capability) Track API keyVersionAvailable since the API’s base version Webhook eventNone Rate limit1000 requests per second (Track API) SourceOfficial documentation ↗ | ||||||
| POST | /api/v1/merge_customers | Merge two duplicate people into a single profile. | write | Track API key | Current | |
Track endpoints use Basic auth with the Site ID and Track API key. The merge keeps one profile as primary and folds the secondary into it. Acts onperson Permission (capability) Track API keyVersionAvailable since the API’s base version Webhook eventNone Rate limit1000 requests per second (Track API) SourceOfficial documentation ↗ | ||||||
| POST | /api/v1/forms/{form_id}/submit | Submit a form on behalf of a person. | write | Track API key | Current | |
Track endpoints use Basic auth with the Site ID and Track API key. Acts onform Permission (capability) Track API keyVersionAvailable since the API’s base version Webhook eventNone Rate limit1000 requests per second (Track API) SourceOfficial documentation ↗ | ||||||
Entities & batchCreate, update, or delete a single person or object, and send many such operations in one batched request.2 | ||||||
| POST | /api/v2/entity | Create, update, or delete a single person or object, including relationships between them. | write | Track API key | Current | |
The v2 path uses the same Track API Basic auth. An object is any non-person entity, such as a company or a course, that people can be related to. Acts onentity Permission (capability) Track API keyVersionAvailable since the API’s base version Webhook eventNone Rate limitEach request must be smaller than 32kb SourceOfficial documentation ↗ | ||||||
| POST | /api/v2/batch | Send many person, object, and delivery operations in a single batched request. | write | Track API key | Current | |
The v2 path uses the same Track API Basic auth. Types can be mixed in one batch. The whole batch must be under 500kb and each operation within it under 32kb. Acts onentity Permission (capability) Track API keyVersionAvailable since the API’s base version Webhook eventNone Rate limitBatch under 500kb, each request under 32kb SourceOfficial documentation ↗ | ||||||
MessagingSend transactional email, push, SMS, and in-app messages, trigger API broadcasts, and send or schedule newsletters.5 | ||||||
| POST | /v1/send/email | Send a transactional email to a specific person. | write | App API key | Current | |
App endpoints use a Bearer App API key generated in the UI with a chosen scope; there are no per-endpoint scopes beyond that. The send endpoints also accept a service-account token prefixed sa_live_ that works across workspaces and needs an X-Workspace-Id header. Acts onmessage Permission (capability) App API keyVersionAvailable since the API’s base version Webhook event email_sentRate limit100 requests per second SourceOfficial documentation ↗ | ||||||
| POST | /v1/send/push | Send a transactional push notification to a specific person. | write | App API key | Current | |
App endpoints use a Bearer App API key. The send endpoints also accept a service-account sa_live_ token with an X-Workspace-Id header. Acts onmessage Permission (capability) App API keyVersionAvailable since the API’s base version Webhook event push_sentRate limit10 requests per second SourceOfficial documentation ↗ | ||||||
| POST | /v1/send/sms | Send a transactional SMS to a specific person. | write | App API key | Current | |
App endpoints use a Bearer App API key. The send endpoints also accept a service-account sa_live_ token with an X-Workspace-Id header. Acts onmessage Permission (capability) App API keyVersionAvailable since the API’s base version Webhook eventNone Rate limit10 requests per second SourceOfficial documentation ↗ | ||||||
| POST | /v1/campaigns/{broadcast_id}/triggers | Trigger an API-triggered broadcast to send to its audience. | write | App API key | Current | |
App endpoints use a Bearer App API key. The payload acts as a trigger, and its data can be referenced inside the broadcast's messages. Acts onbroadcast Permission (capability) App API keyVersionAvailable since the API’s base version Webhook eventNone Rate limit10 requests per second SourceOfficial documentation ↗ | ||||||
| POST | /v1/newsletters/{newsletter_id}/send | Send a newsletter. | write | App API key | Current | |
App endpoints use a Bearer App API key. Acts onnewsletter Permission (capability) App API keyVersionAvailable since the API’s base version Webhook eventNone Rate limit10 requests per second SourceOfficial documentation ↗ | ||||||
Customers & dataSearch for customers, look up a customer's attributes, relationships, segments, messages, and activities.4 | ||||||
| POST | /v1/customers | Search for customers by attributes, segments, or other filters. | read | App API key | Current | |
App endpoints use a Bearer App API key. This returns matching people; despite the POST verb it reads rather than creates. Acts oncustomer Permission (capability) App API keyVersionAvailable since the API’s base version Webhook eventNone Rate limit10 requests per second SourceOfficial documentation ↗ | ||||||
| GET | /v1/customers | Look up customers by email address. | read | App API key | Current | |
App endpoints use a Bearer App API key. This returns email addresses and profile data. Acts oncustomer Permission (capability) App API keyVersionAvailable since the API’s base version Webhook eventNone Rate limit10 requests per second SourceOfficial documentation ↗ | ||||||
| GET | /v1/customers/{customer_id}/attributes | Look up a customer's attributes. | read | App API key | Current | |
App endpoints use a Bearer App API key. Attributes can include personal data set on the profile. Acts oncustomer Permission (capability) App API keyVersionAvailable since the API’s base version Webhook eventNone Rate limit10 requests per second SourceOfficial documentation ↗ | ||||||
| GET | /v1/customers/{customer_id}/messages | Look up the messages sent to a customer. | read | App API key | Current | |
App endpoints use a Bearer App API key. Acts oncustomer Permission (capability) App API keyVersionAvailable since the API’s base version Webhook eventNone Rate limit10 requests per second SourceOfficial documentation ↗ | ||||||
SegmentsCreate, list, read, and delete manual segments, count their members, and add or remove people.5 | ||||||
| GET | /v1/segments | List the segments in the workspace. | read | App API key | Current | |
App endpoints use a Bearer App API key. Acts onsegment Permission (capability) App API keyVersionAvailable since the API’s base version Webhook eventNone Rate limit10 requests per second SourceOfficial documentation ↗ | ||||||
| POST | /v1/segments | Create a manual segment. | write | App API key | Current | |
App endpoints use a Bearer App API key. Only manual segments are managed through the API; data-driven segments update themselves. Acts onsegment Permission (capability) App API keyVersionAvailable since the API’s base version Webhook eventNone Rate limit10 requests per second SourceOfficial documentation ↗ | ||||||
| GET | /v1/segments/{segment_id}/membership | List the customers in a segment. | read | App API key | Current | |
App endpoints use a Bearer App API key. Acts onsegment Permission (capability) App API keyVersionAvailable since the API’s base version Webhook eventNone Rate limit10 requests per second SourceOfficial documentation ↗ | ||||||
| POST | /api/v1/segments/{segment_id}/add_customers | Add people to a manual segment. | write | Track API key | Current | |
Adding and removing members runs on the Track API with Basic auth, not the App API. Changing membership can change who a campaign reaches. Acts onsegment Permission (capability) Track API keyVersionAvailable since the API’s base version Webhook eventNone Rate limit1000 requests per second (Track API) SourceOfficial documentation ↗ | ||||||
| POST | /api/v1/segments/{segment_id}/remove_customers | Remove people from a manual segment. | write | Track API key | Current | |
Adding and removing members runs on the Track API with Basic auth, not the App API. Acts onsegment Permission (capability) Track API keyVersionAvailable since the API’s base version Webhook eventNone Rate limit1000 requests per second (Track API) SourceOfficial documentation ↗ | ||||||
Broadcasts & campaignsList and read broadcasts and campaigns, get their metrics, and read the status and errors of a triggered broadcast.4 | ||||||
| GET | /v1/broadcasts | List the broadcasts in the workspace. | read | App API key | Current | |
App endpoints use a Bearer App API key. Acts onbroadcast Permission (capability) App API keyVersionAvailable since the API’s base version Webhook eventNone Rate limit10 requests per second SourceOfficial documentation ↗ | ||||||
| GET | /v1/campaigns/{broadcast_id}/triggers/{trigger_id} | Get the status of a triggered broadcast. | read | App API key | Current | |
App endpoints use a Bearer App API key. Acts onbroadcast Permission (capability) App API keyVersionAvailable since the API’s base version Webhook eventNone Rate limit10 requests per second SourceOfficial documentation ↗ | ||||||
| GET | /v1/campaigns | List the campaigns in the workspace. | read | App API key | Current | |
App endpoints use a Bearer App API key. Acts oncampaign Permission (capability) App API keyVersionAvailable since the API’s base version Webhook eventNone Rate limit10 requests per second SourceOfficial documentation ↗ | ||||||
| GET | /v1/campaigns/{campaign_id}/metrics | Get the metrics for a campaign. | read | App API key | Current | |
App endpoints use a Bearer App API key. Acts oncampaign Permission (capability) App API keyVersionAvailable since the API’s base version Webhook eventNone Rate limit10 requests per second SourceOfficial documentation ↗ | ||||||
CollectionsCreate, list, look up, update, and delete collections, the reusable data sets referenced inside messages.4 | ||||||
| POST | /v1/collections | Create a collection, a reusable data set referenced inside messages. | write | App API key | Current | |
App endpoints use a Bearer App API key. Live messages can read from a collection, so changing one changes what they render. Acts oncollection Permission (capability) App API keyVersionAvailable since the API’s base version Webhook eventNone Rate limit10 requests per second SourceOfficial documentation ↗ | ||||||
| GET | /v1/collections | List the collections in the workspace. | read | App API key | Current | |
App endpoints use a Bearer App API key. Acts oncollection Permission (capability) App API keyVersionAvailable since the API’s base version Webhook eventNone Rate limit10 requests per second SourceOfficial documentation ↗ | ||||||
| PUT | /v1/collections/{collection_id} | Update a collection. | write | App API key | Current | |
App endpoints use a Bearer App API key. Acts oncollection Permission (capability) App API keyVersionAvailable since the API’s base version Webhook eventNone Rate limit10 requests per second SourceOfficial documentation ↗ | ||||||
| DELETE | /v1/collections/{collection_id} | Delete a collection. | write | App API key | Current | |
App endpoints use a Bearer App API key. Acts oncollection Permission (capability) App API keyVersionAvailable since the API’s base version Webhook eventNone Rate limit10 requests per second SourceOfficial documentation ↗ | ||||||
Reporting webhooksCreate, list, read, update, and delete the reporting webhooks that deliver message events.3 | ||||||
| POST | /v1/reporting_webhooks | Create a reporting webhook that delivers message events. | write | App API key | Current | |
App endpoints use a Bearer App API key. This sets where Customer.io posts message metric events. Acts onreporting webhook Permission (capability) App API keyVersionAvailable since the API’s base version Webhook eventNone Rate limit10 requests per second SourceOfficial documentation ↗ | ||||||
| GET | /v1/reporting_webhooks | List the reporting webhooks in the workspace. | read | App API key | Current | |
App endpoints use a Bearer App API key. Acts onreporting webhook Permission (capability) App API keyVersionAvailable since the API’s base version Webhook eventNone Rate limit10 requests per second SourceOfficial documentation ↗ | ||||||
| DELETE | /v1/reporting_webhooks/{webhook_id} | Delete a reporting webhook. | write | App API key | Current | |
App endpoints use a Bearer App API key. Acts onreporting webhook Permission (capability) App API keyVersionAvailable since the API’s base version Webhook eventNone Rate limit10 requests per second SourceOfficial documentation ↗ | ||||||
Customer.io can notify an app or AI agent when a message is acted on, instead of the app repeatedly asking. A reporting webhook posts a JSON payload to a registered URL each time a metric fires, such as an email being delivered, opened, or clicked.
| Event | What it signals | Triggered by |
|---|---|---|
email sent | Fires when an email is handed off for sending. The object_type is email and the metric is sent. | /v1/send/email |
email delivered | Fires when an email is accepted by the recipient's mail server. The object_type is email and the metric is delivered. | In-app only |
email opened | Fires when a recipient opens an email. The object_type is email and the metric is opened. | In-app only |
email clicked | Fires when a recipient clicks a link in an email. The object_type is email and the metric is clicked. | In-app only |
email bounced | Fires when an email bounces and cannot be delivered. The object_type is email and the metric is bounced. | In-app only |
email marked as spam | Fires when a recipient marks an email as spam. The object_type is email and the metric is spammed. | In-app only |
email unsubscribed | Fires when a recipient unsubscribes from an email. The object_type is email and the metric is unsubscribed. | In-app only |
email converted | Fires when a recipient completes the conversion goal tied to an email. The object_type is email and the metric is converted. | In-app only |
push sent | Fires when a push notification is handed off for sending. The object_type is push and the metric is sent. | /v1/send/push |
sms sent | Fires when an SMS is handed off for sending. The object_type is sms and the metric is sent. | In-app only |
customer subscribed | Fires when a person subscribes. The object_type is customer and the metric is subscribed. | In-app only |
customer unsubscribed | Fires when a person unsubscribes. The object_type is customer and the metric is unsubscribed. | In-app only |
Customer.io limits how fast an app or AI agent can call, with separate ceilings for the two APIs, and caps the size of each request the Track API accepts.
Customer.io rate-limits each API separately and applies a sliding window. The Track API allows about 1,000 requests per second across both its v1 and v2 paths, for live integrations and backfills alike, though that rate is not strictly enforced and consistently exceeding it can lead to throttling or dropped data. The App API is tighter: most endpoints allow 10 requests per second, with the transactional email send endpoint raised to 100 requests per second. Going over a limit returns 429 Too Many Requests, so a caller should slow down and retry after a short pause.
List endpoints on the App API page through their results, typically with a start cursor and a limit parameter, returning the next cursor in the response to fetch the following page. The Track API is an ingestion API and does not paginate; its v2 batch endpoint instead accepts many operations in one request.
On the Track API v2 path, a single entity request must be smaller than 32kb, and a batch request must be smaller than 500kb with each operation inside it also 32kb or smaller. Requests and responses are JSON.
The status codes an agent should handle, and what to do about each.
| Status | Code | Meaning | What to do |
|---|---|---|---|
| 400 | Bad Request | The request is malformed, most often invalid JSON such as a mismatched bracket or a missing comma or quote. The Track API returns a 400 with details to help troubleshoot the request. | Fix the JSON or the named field, then resend. |
| 401 | Unauthorized | The credential is missing, incorrect, or invalid. For the App API this is usually a bad Bearer token; for the Track API a bad Site ID and key pair. | Check the credential reaches the right workspace and has the access the call needs, then resend. |
| 404 | Not Found | The resource does not exist, such as a broadcast trigger id that cannot be found. | Confirm the id and the path are correct. |
| 422 | Unprocessable Entity | The request was well-formed but failed a validation check, such as a broadcast trigger that did not pass validation. | Read the validation detail in the body, correct the request, and resend. |
| 429 | Too Many Requests | A rate limit was exceeded. Customer.io applies a sliding-window limit per API and returns 429 when the rate is over budget. | Slow the request rate and retry after a short pause. |
Customer.io does not version its APIs by date. The Track API exposes a v1 and a v2 path, the App API a v1 path, and changes ship continuously through dated release notes rather than a new version string.
Customer.io does not stamp its APIs with a dated version. The Track API exposes a v1 and a v2 path, and the App API a v1 path, while changes ship continuously and are announced through the release notes rather than a new version string. Recent additions include Design Studio email and component management on the App API and tighter MCP security controls.
Customer.io launched its hosted MCP server in 2025, exposing the Journeys UI API and CDP Data Pipelines API to AI tools over OAuth. The Track API's v2 path consolidated single-entity and batch operations for people and objects, with a 32kb per-request and 500kb per-batch ceiling.
An integration tracks changes through the release notes rather than pinning a version.
Customer.io release notes ↗Bollard AI sits between a team's AI agents and Customer.io. Grant each agent exactly the access it needs, read or write, area by area, and every call is checked and logged.