canonical: https://jentic.com/apis/customer.io/track-api # Customer.io Track API Jentic publishes the only available OpenAPI specification for Customer.io Track API, keeping it validated and agent-ready. This focused Track API surface covers customer identification and lifecycle, event tracking (attributed and anonymous), device registration, and suppression management. It is the minimal ingestion layer for sending behavioural data into Customer.io to drive messaging campaigns. Authentication uses HTTP Basic with a site ID and tracking API key. ## For AI agents Identify customers, track attributed and anonymous events, register devices, and manage suppression for Customer.io's behavioural messaging platform. ## Scope Does not handle campaign creation, transactional email sending, or reporting - use for identifying customers, tracking events, registering devices, and managing suppression only. ## Capabilities - Identify and update customers by customer_id with traits via PUT /customers/{customer_id} - Track named events for an identified customer to drive campaign triggers - Track anonymous events that can later be tied to a customer when they identify - Register and remove customer devices to enable push notification delivery - Suppress and unsuppress customer profiles for compliance and unsubscribe handling ## Use cases ### Server-Side Customer Tracking Send identification and event data from a server-side application into Customer.io to power behavioural campaigns. Use PUT /customers/{customer_id} to upsert profiles and POST /customers/{customer_id}/events to record actions like 'order_completed'. Suitable for backend services that own the source of truth for user behaviour and want a minimal ingestion surface. Example prompt: Call PUT /customers/{customer_id} with the user's email and signup_date, then POST /customers/{customer_id}/events with name='order_completed' and the order details ### Anonymous to Identified Stitching Capture pre-signup behaviour through POST /events with an anonymous_id, then identify the same user with PUT /customers/{customer_id} once they sign up so Customer.io can stitch the prior events to the new profile. Useful for funnel attribution and welcome sequences that reference pre-signup actions. Example prompt: Call POST /events with anonymous_id and name='trial_video_watched' before signup, then PUT /customers/{customer_id} with the same anonymous_id at signup to stitch history ### Push Notification Device Management Register and rotate device tokens so Customer.io campaigns can deliver push notifications. Use PUT /customers/{customer_id}/devices to add or update a token and DELETE /customers/{customer_id}/devices/{device_id} to revoke it on logout or app uninstall. Example prompt: Call PUT /customers/{customer_id}/devices with the FCM or APNs token after a user signs in on a new device ### AI Agent Event Tracking via Jentic An AI agent automating ingestion of customer signals uses Jentic to send identify and event payloads directly to Customer.io. The agent searches for 'track customer event', loads /customers/{customer_id}/events, supplies the event name, and posts it without bespoke integration code. Example prompt: Use Jentic to search 'track customer event' and execute /customers/{customer_id}/events for each row of an enrichment job's output ## Key endpoints | Method | Path | Description | | --- | --- | --- | | PUT | /customers/{customer_id} | Identify or update a customer | | DELETE | /customers/{customer_id} | Delete a customer profile | | POST | /customers/{customer_id}/events | Track a customer event | | POST | /events | Track an anonymous event | | PUT | /customers/{customer_id}/devices | Register a customer device | | POST | /customers/{customer_id}/suppress | Suppress a customer | ## Key resources - **Customers** — Identify, update, suppress, unsuppress, and delete customer profiles - **Events** — Attributed and anonymous event tracking that drives campaign triggers - **Devices** — Register and revoke push notification device tokens ## Why Jentic - **Setup:** Wiring the Customer.io Track API by hand means encoding a site ID and tracking key into a Basic auth header, targeting the track host, and mapping its customer, event, and device routes 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 customer id in the URL path (/customers/{customer_id}/...), so a rule can pin your agent to one customer: it can update that customer, add events, and register devices. You choose the operations it may call, so a delete 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 customer' or 'track a customer 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** — Broader Customer.io App API with campaigns, exports, and transactional sends - **Customer.io Track API (extended)** — Extended Track surface adding forms, segment ops, merge, metrics, and v2 batch - **Segment API** — CDP that fans identify and track calls to many destinations ## FAQ ### Why is there no official OpenAPI spec for Customer.io Track API? Customer.io does not publish a complete OpenAPI specification for this 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 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 track anonymous events with the Customer.io Track API? Yes. Call POST /events with an anonymous_id and event name. When the user later identifies, Customer.io stitches the anonymous history to the identified profile. ### What are the rate limits for the Customer.io Track API? Track endpoints accept high throughput; specific limits depend on the Customer.io plan and are not encoded in the spec. Use the broader Customer.io batch API for bulk loads when ingesting large volumes. ### How do I register a push device token through Jentic? Run pip install jentic, search for 'add customer device', load PUT /customers/{customer_id}/devices, and execute it with the token and platform. Jentic posts the device registration so push campaigns can reach the user. ### How do I delete a customer profile? Call DELETE /customers/{customer_id} with the customer identifier. Customer.io removes the profile and halts all subsequent processing for that ID, suitable for honouring data deletion requests. ### Can I limit what my agent is allowed to do with the Customer.io Track API? Yes. Because you run Jentic One yourself, your own rules decide which Track operations and credentials the agent may use. The Customer.io Track API puts the customer id in the URL path, so you can pin the agent to a specific customer and allow only the calls you want, such as identifying a customer via PUT /customers/{customer_id}, tracking events via POST /customers/{customer_id}/events, and registering devices via PUT /customers/{customer_id}/devices. Destructive calls like DELETE /customers/{customer_id} or POST /customers/{customer_id}/suppress stay out of reach unless you explicitly add them.