Skip to main content
events.track records one identified backend business event as a durable UserEvent. Segmentflow resolves an existing Profile, applies any profile.properties as durable Profile Properties, stores the one-event data payload, and evaluates active Journeys that listen for the event. It never creates a Profile; use an identify or trusted Profile-producing operation first. Journey-triggered email templates can reference event payload values under /event/*, for example { "$state": "/event/orderId" }. Event data is not copied into Profile Properties and remains separate from EmailSend /data/* state. Use this for facts like order.created, trial.started, or payment.failed when Journey configuration should decide whether to enroll the Profile. To send orders with their products, and refunds, use Order transactions. If you already know that you need one expected email, use Emails. If you are choosing between email sending, event-triggered Journeys, direct Journey trigger, Broadcasts, and Newsletter Issues, start with Which API should I use?.
events.track uses API Keys with events:write. The WriteKey-authenticated Ingest API remains separate for browser SDKs, plugins, and Segment-compatible userId / properties traffic.

Track an event

Request fields

Every request requires Idempotency-Key. Retrying the same key with the same request replays the original response. Reusing it with different request parameters returns 409 Conflict. The API derives the external-ID namespace from authenticated trusted context. Requests cannot supply a namespace, and provider customer IDs are never looked up by scanning every value in Profile.externalIds.

Response

events.track returns 202 Accepted after Segmentflow durably accepts the event.
When no active Journey listens to the event, the request still succeeds and the Journey counts are all zero.

Processing model

Segmentflow resolves identity synchronously before accepting the event. Profile.id is the canonical internal identifier, and every internal Profile reference is scoped as (organizationId, profileId). Provider identifiers remain namespaced external handles; userId and source are event metadata rather than routing authority. Every accepted customer event stores a non-null profileId and a durable occurrence key. A committed retry returns its original result before Profile Resolution or any Profile, consent, metric, subscription, or Journey side effect is repeated. Active event-entry Journeys are evaluated immediately. Segment membership changes use a transactional, durable Journey handoff so enrollment work cannot be lost. Metrics and segment projections run hourly from the resolved event/Profile data.