> ## Documentation Index
> Fetch the complete documentation index at: https://segmentflow.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Events

> Use events.track to record one server-side business event and trigger matching Journeys.

`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](/docs/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?](/docs/which-api-should-i-use).

<Note>
  `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.
</Note>

## Track an event

```ts theme={null}
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.

```json theme={null}
{
  "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.