Events - SegmentFlow.ai

events.track records one identified backend business event as a durable UserEvent. Segmentflow resolves the Profile, applies any profile.properties as durable Profile Properties, stores the one-event data payload, and evaluates active Journeys that listen for the event. 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. 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

import Segmentflow from "@segmentflow/segmentflow-typescript";

const client = new Segmentflow({
  apiKey: process.env.SEGMENTFLOW_API_KEY,
});

const result = await client.v1.events.track({
  "idempotency-key": "order.created:ord_9421",
  event: "order.created",
  profile: {
    email: "alex@example.com",
    externalId: "cus_123",
    properties: {
      firstName: "Alex",
      plan: "Pro",
    },
  },
  data: {
    orderId: "ord_9421",
    total: 49,
    payment: {
      token: "tok_live_abc",
    },
  },
  redactedDataPaths: ["/event/payment/token"],
  referenceId: "ord_9421",
  occurredAt: "2026-05-31T12:00:00.000Z",
});

console.log(result.eventId, result.profileId, result.matchedJourneys);

Request fields

Field	Purpose
`event`	Free-form business event name. Unknown names are accepted.
`profile.email`	Email identity used to resolve or create the Profile.
`profile.externalId`	Caller-owned Profile identifier.
`profile.properties`	Durable Profile Property updates. Not copied into the event payload.
`data`	One-event payload exposed to Journey email templates under `/event/*`.
`redactedDataPaths`	Optional `/event/*` paths to redact before durable retention.
`referenceId`	Safe caller correlation id. Not used for idempotency.
`occurredAt`	Event time. If omitted, Segmentflow uses receipt time.

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.

Response

events.track returns 202 Accepted after Segmentflow durably accepts the event.

{
  "eventId": "019bf964-302b-7a7f-add2-589343ef9f32",
  "profileId": "019bf964-302b-7a7f-add2-589343ef9f31",
  "matchedJourneys": 0,
  "enrolledJourneys": 0,
  "skippedJourneys": 0
}

When no active Journey listens to the event, the request still succeeds and the Journey counts are all zero.

​Track an event

​Request fields

​Response

Track an event

Request fields

Response