canonical: https://jentic.com/apis/customer.io/customerio-track

# Customer.io Track API

Jentic publishes the only available OpenAPI specification for Customer.io Track API, keeping it validated and agent-ready. The Track API is the data ingestion surface for Customer.io, used to add and update people, record events, manage devices, suppress profiles, submit forms, merge duplicates, and send batched requests. It also includes account region discovery and a v2 entity endpoint for unified ingestion. Authentication uses HTTP Basic with a site ID and tracking API key.

## For AI agents

Ingest behavioural data into Customer.io: identify people, track events, manage devices, submit forms, suppress profiles, and send batched or v2 entity requests.

## Scope

Does not handle campaign creation, sending transactional email, or pulling reporting metrics - use for ingesting people, events, devices, and batched data only.

## Capabilities

- Add or update people in Customer.io with traits and timestamps via PUT /api/v1/customers/{identifier}
- Track named customer events or anonymous events to drive campaign triggers
- Register and remove customer devices to enable push delivery
- Suppress, unsuppress, or delete people for compliance and lifecycle hygiene
- Submit forms, add or remove people from manual segments, and merge duplicate profiles
- Send a batched payload of mixed identify, track, and device operations through /api/v2/batch

## Use cases

### Server-Side Event Ingestion

Send identification and event data from a server-side application into Customer.io to drive campaigns. Use PUT /api/v1/customers/{identifier} for upsert, POST /api/v1/customers/{identifier}/events for attributed events, and POST /api/v1/events for anonymous traffic. Suitable for backend services that own the source of truth for user behaviour.

Example prompt: Call PUT /api/v1/customers/{identifier} with traits, then POST /api/v1/customers/{identifier}/events with name='checkout_completed' and properties for the order

### Mobile Device Registration for Push

Register and rotate device tokens so Customer.io campaigns can deliver push notifications to mobile customers. Use PUT /api/v1/customers/{identifier}/devices to add or update a token and DELETE /api/v1/customers/{identifier}/devices/{device_id} to revoke it on logout or app uninstall.

Example prompt: Call PUT /api/v1/customers/{identifier}/devices with the FCM or APNs token after a user signs in on a new device

### Batched Backfill or Sync

Backfill historical events or sync records from another system using POST /api/v1/segments/{segment_id}/add_customers for segment population, /api/v1/merge_customers for de-duplication, and POST /api/v2/batch for a high-throughput batched payload of mixed operations. Reduces request volume during one-off migrations and nightly syncs.

Example prompt: Construct a /api/v2/batch payload with 200 mixed identify and track requests and POST it in a single call during a nightly sync window

### Compliance and Suppression Workflow

Honour unsubscribe, deletion, and data subject requests by suppressing or deleting profiles via the Track API. POST /api/v1/customers/{identifier}/suppress halts messaging, POST /api/v1/customers/{identifier}/unsuppress reverses it, and DELETE /api/v1/customers/{identifier} removes the profile.

Example prompt: Call POST /api/v1/customers/{identifier}/suppress when a customer submits an unsubscribe and DELETE /api/v1/customers/{identifier} on a verified deletion request

### AI Agent Track Workflow via Jentic

An AI agent automating ingestion of customer signals uses Jentic to send identify and event payloads directly. The agent searches for 'track customer event', loads the operation, supplies the identifier and event name, and posts the event without bespoke integration glue.

Example prompt: Use Jentic to search 'track customer event' and execute /api/v1/customers/{identifier}/events for each row of an enrichment job's output

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| PUT | /api/v1/customers/{identifier} | Add or update a customer |
| POST | /api/v1/customers/{identifier}/events | Track a customer event |
| POST | /api/v1/events | Track an anonymous event |
| PUT | /api/v1/customers/{identifier}/devices | Register a customer device |
| POST | /api/v1/customers/{identifier}/suppress | Suppress a customer profile |
| POST | /api/v1/merge_customers | Merge duplicate customer profiles |
| POST | /api/v2/batch | Send a batched payload |
| GET | /api/v1/accounts/region | Find the workspace region |

## Key resources

- **Customers** — Add, update, suppress, unsuppress, and delete customer profiles
- **Events** — Attributed and anonymous event tracking that drives campaign triggers
- **Devices** — Register and revoke push device tokens
- **Segments** — Add or remove people from manual segments
- **Forms** — Submit form responses tied to a customer
- **Merge** — Merge duplicate customer profiles by identifier
- **Batch** — Send multiple identify, track, and device requests in one call
- **Account** — Discover the Customer.io region for the workspace

## Why Jentic

- **Setup:** Wiring the Customer.io Track API by hand means encoding a site ID and tracking key into a Basic auth header and choosing between the track.customer.io and track-eu.customer.io hosts for your region yourself. Through Jentic you install once, import the Customer.io Track API from the API Directory, store the credential pair once, and your agent calls it.
- **Permission scoping:** Customer.io puts the person identifier in the URL path (/api/v1/customers/{identifier}/...), so a rule can pin your agent to one person: it can update that person and add their events. You choose the operations it may call, so a merge or suppress call is not included unless you add it.
- **Credential handling:** Your Customer.io site ID and tracking key are stored once, encrypted, by your own Jentic One instance and injected at execution time. They never enter the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'identify a person' or 'track an event', and Jentic returns the matching Track API operation with its input schema so the agent calls the right endpoint without browsing the reference docs.

## Related APIs

- **Customer.io API** — Customer.io's broader App API surface covering campaigns, exports, and transactional sends
- **Segment API** — CDP that fans out identify and track calls to many destinations
- **Amplitude API** — Product analytics platform with similar identify and event ingestion
- **Mixpanel API** — Event analytics platform with track and identify endpoints

## FAQ

### Why is there no official OpenAPI spec for Customer.io Track API?

Customer.io does not publish a complete OpenAPI specification for the Track surface. Jentic generates and maintains this spec so that AI agents and developers can call Customer.io Track API via structured tooling. It is validated against the live API and kept up to date. Get started with Jentic One, the self-hosted execution layer.

### What authentication does the Customer.io Track API use?

The Track API uses HTTP Basic with a workspace site ID as the username and a tracking API key as the password. Through Jentic both values are held in the encrypted vault and injected into the Authorization header at call time.

### Can I send batched events to the Customer.io Track API?

Yes. POST /api/v2/batch accepts an array of mixed identify, track, and device operations in a single request, useful for backfills and nightly syncs.

### What are the rate limits for the Customer.io Track API?

Track endpoints accept high event throughput; specific limits depend on the Customer.io plan and are not encoded in the spec. Use /api/v2/batch for bulk loads to stay within per-request limits.

### How do I find which region my Customer.io workspace is in through Jentic?

Run pip install jentic, search for 'find account region', load GET /api/v1/accounts/region, and execute it. Jentic returns the region (US or EU) so you can route subsequent calls to the right host.

### How do I suppress a customer for GDPR compliance?

Call POST /api/v1/customers/{identifier}/suppress to stop messaging while keeping the profile. For full deletion call DELETE /api/v1/customers/{identifier}, which removes the profile and stops all subsequent processing.

### Can I limit what my agent is allowed to do with the Customer.io Track API?

Yes. Jentic One runs self-hosted, so your own rules decide which Track API operations and credentials the agent may use. Because Customer.io puts the person identifier in the URL path (/api/v1/customers/{identifier}/...), you can pin the agent to update one person and record their events while excluding calls you never add, such as POST /api/v1/merge_customers or POST /api/v1/customers/{identifier}/suppress. The site ID and tracking key stay with your instance and are injected only for the operations you have allowed.