canonical: https://jentic.com/apis/customer.io

# Customer.io APIs

Customer.io is a marketing automation platform for behavioural messaging, combining customer identification, event tracking, segmentation, campaigns, and transactional email. Jentic publishes and maintains OpenAPI specifications for two Customer.io surfaces: the broader App API (customerio-api) covering customer lifecycle, campaign and newsletter metrics, segment listing, data exports, and transactional email sending; and the Track API (main), the data-ingestion surface for adding and updating people, recording attributed and anonymous events, managing push devices, submitting forms, merging duplicates, suppressing profiles, and sending batched or v2 entity requests. Both surfaces authenticate with HTTP Basic using a workspace site ID and API key.

## For AI agents

An agent can ingest behavioural data into Customer.io by identifying people, tracking events, registering push devices, and sending batched payloads, then act on that data by sending transactional email, pulling campaign and newsletter metrics, exporting customer and delivery datasets, and managing suppression across the App and Track APIs.

## Scope

Use for: Ingesting people, events, and devices into Customer.io and acting on that data through transactional email, campaign and newsletter metrics, segment listing, exports, and suppression

Not supported:
- campaign authoring
- SMS sending
- in-app messages
- push payload delivery
- workflow builder editing

## APIs

| API | Category | Endpoints | Description |
| --- | --- | --- | --- |
| Customer.io API | marketing | 21 | Identify and track customers, send transactional email, manage devices, list campaigns and segments, and export delivery and customer data through Customer.io. |
| Customer.io Track API | marketing | 16 | Ingest behavioural data into Customer.io: identify people, track events, manage devices, submit forms, suppress profiles, and send batched or v2 entity requests. |

## Which API to use

| Need | API | Why |
| --- | --- | --- |
| Add or update people, record events, or register push devices | main | The Track API is the ingestion surface for identify, event, device, form, merge, and batched requests. |
| Send transactional email or pull campaign and newsletter metrics | customerio-api | The App API covers transactional sends, campaign and newsletter metrics, segment listing, and data exports. |
| Identify a customer or track a single event | main | Prefer the Track API for high-throughput ingestion; the App API also identifies and tracks but is broader than needed for pure ingestion. |
| Suppress, unsuppress, or delete a profile | main | The Track API exposes suppression and deletion for compliance; the App API also suppresses if you already hold that surface. |

## Cross-API use cases

### Ingest behaviour then trigger transactional email

Identify a customer and track an event through the Track API to drive a campaign trigger, then send a related transactional email through the App API. The Track API records the signal and the App API sends the receipt, reset, or confirmation off the back of it.

Example prompt: Call PUT /api/v1/customers/{identifier} and POST /api/v1/customers/{identifier}/events on the Track API, then POST /send/email on the App API with the matching transactional template

### Track events and report on campaign performance

Feed behavioural events into Customer.io through the Track API so campaigns fire, then pull the resulting campaign and newsletter metrics through the App API to populate a reporting dashboard. This closes the loop from signal ingestion to performance measurement.

Example prompt: Post events via POST /api/v1/customers/{identifier}/events on the Track API, then call GET /campaigns and GET /campaigns/{campaign_id}/metrics on the App API for a weekly report

### Bulk backfill then export for audit

Backfill historical people and events through the Track API batch endpoint during a migration, then start a customer or delivery export through the App API to verify the load or produce an audit archive. Ingestion and export live on separate surfaces but combine into one migration workflow.

Example prompt: POST a mixed payload to /api/v2/batch on the Track API, then POST /exports/customers on the App API and poll GET /activities until the export completes

### Compliance suppression with delivery evidence

Honour an unsubscribe or deletion request by suppressing or deleting a profile through the Track API, then export delivery data through the App API to document what was sent before the request. This produces a defensible record for data subject requests.

Example prompt: Call POST /api/v1/customers/{identifier}/suppress on the Track API, then POST /exports/deliveries on the App API to archive prior sends for the record

## Why Jentic

- **Setup:** Wiring Customer.io by hand means encoding a site ID and key into a Basic auth header per surface, choosing the right regional track host, and mapping the customer, event, campaign, and export routes yourself. Through Jentic you install Jentic One once, add the Customer.io APIs from the Jentic directory, store the credential pairs once, and your agent calls them.
- **Permission scoping:** Customer.io puts the person identifier in the URL path across both surfaces (/customers/{customer_id}/... and /api/v1/customers/{identifier}/...), so your own rules in Jentic One can pin an agent to one person and let it identify, track, and register devices while withholding suppress, delete, merge, or export operations unless you add them.
- **Credential handling:** Your Customer.io site ID and API keys are stored encrypted by your own Jentic One instance and injected at execution time. They never enter the agent's prompt, logs, or context, and the tracking key and App API key stay scoped to their respective surfaces.
- **Discovery method:** Agents search the Jentic directory by intent such as 'track a customer event', 'send a transactional email', or 'export delivery data', and Jentic returns the matching Customer.io operation with its input schema so the agent calls the right endpoint on the right surface without browsing the reference docs.

## Related vendors

- **Klaviyo** — Marketing automation platform with behavioural email and SMS, strong for e-commerce and native Shopify integration.
- **Braze** — Customer engagement platform for large-scale cross-channel orchestration across push, in-app, and content cards.
- **Segment** — Customer data platform that fans identify and track calls out to many destinations instead of going direct.
- **SendGrid** — Pure transactional email delivery to pair with Customer.io when splitting lifecycle and transactional traffic.

## FAQ

### What is the difference between the Customer.io API and the Track API?

The Track API is the data-ingestion surface: it identifies people, records attributed and anonymous events, manages push devices, submits forms, merges duplicates, suppresses profiles, and sends batched or v2 entity requests. The Customer.io API is the broader App surface: it lists campaigns and segments, returns campaign and newsletter metrics, starts customer and delivery exports, and sends transactional email. Most automations write signals through the Track API and read or send through the App API.

### Do both Customer.io APIs use the same credentials?

Both use HTTP Basic with a workspace site ID and an API key, but the key differs by surface. The Track API expects a tracking API key while the App API expects an App API key, so you provide the matching pair for each surface you call.

### Which API should an agent use to send email?

Use the Customer.io API. Transactional sends go through its POST /send/email endpoint with a transactional message ID, recipient, and template variables. The Track API does not send email; it only ingests the behavioural data that can trigger a campaign to send.

### Are these OpenAPI specifications official?

Customer.io does not publish canonical OpenAPI specifications covering these surfaces. Jentic generates and maintains both specs, validates them against the live API, and keeps them current so that agents and developers can call Customer.io through structured tooling.

### How do I handle large data loads across the two APIs?

For high-volume ingestion use the Track API POST /api/v2/batch endpoint, which accepts an array of mixed identify, track, and device operations in one request. For extracting large datasets use the App API exports, which start async jobs for customer and delivery data that you download once complete.

### Does Customer.io support US and EU regions?

Yes. Workspaces live in either the US or EU region, which determines the host your calls should target. The Track API exposes GET /api/v1/accounts/region to discover which region a workspace belongs to so subsequent calls route to the correct host.