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

# Track

> Record a user action or business event

#### Description

Record a user action or business event. This is the most commonly used endpoint for custom event tracking.

Short alias: `POST /v1/t`

**When to use:**

* Any user action: button tapped, purchase completed, feature used
* Business events from your server: subscription renewed, payment failed
* Device lifecycle events such as `Application Installed` or `Application Opened` (SDKs send these automatically)

#### Headers

<ParamField header="Authorization" type="string" required placeholder="Basic <base64(api_key:)>">
  HTTP Basic Auth. See [Events Authentication](/api-reference/zixflow-ai/events/authentication).
</ParamField>

<ParamField header="Content-Type" type="string" required default="application/json">
  Must be `application/json`.
</ParamField>

#### Body

<ParamField body="userId" type="string" placeholder="user_12345">
  Identified user ID. At least one of `userId` or `anonymousId` is required.
</ParamField>

<ParamField body="anonymousId" type="string" placeholder="anon_abc-123">
  Anonymous user ID if the user is not identified. Required if `userId` is not provided.
</ParamField>

<ParamField body="event" type="string" required placeholder="Order Completed">
  Name of the event (for example `"Order Completed"`).
</ParamField>

<ParamField body="properties" type="object">
  Event-specific data (for example `order_id`, `revenue`, `currency`).
</ParamField>

<ParamField body="timestamp" type="string" placeholder="2026-05-04T14:32:15.000Z">
  When the event occurred, as ISO 8601.
</ParamField>

<ParamField body="context" type="object">
  Optional environment metadata (device, OS, app, IP, locale, and more). SDKs populate this automatically. See [Context Object](/api-reference/zixflow-ai/events/context).
</ParamField>

#### Semantic events

Certain event names trigger special handling beyond the standard event pipeline:

| Event name                  | Special behavior                                           |
| --------------------------- | ---------------------------------------------------------- |
| `Device Created or Updated` | Routes to device registration pipeline                     |
| `Device Deleted`            | Soft-deletes device record (`active=false`)                |
| `Device Registered`         | Routes to device logs table                                |
| `Device Updated`            | Routes to device logs table                                |
| `User Deleted`              | Sets `is_deleted=true` on profile, deactivates all devices |
| `User Suppressed`           | Sets `is_suppressed=true`, blocks all channel delivery     |
| `User Unsuppressed`         | Clears suppression flag                                    |
| `Application Installed`     | Routes to device logs table                                |
| `Application Opened`        | Routes to device logs table                                |
| `Application Backgrounded`  | Routes to device logs table                                |
| `Application Foregrounded`  | Routes to device logs table                                |
| `Application Crashed`       | Routes to device logs table                                |

#### Response

Successful requests return `HTTP 200` with an empty JSON object.

<ResponseExample>
  ```json 200-Success theme={null}
  {}
  ```

  ```json 400-Bad Request theme={null}
  {
    "error": "VALIDATION_FAILED",
    "details": [
      {
        "reason": "REQUIRED",
        "field": "event",
        "message": "event is required"
      }
    ]
  }
  ```

  ```json 401-Unauthorised theme={null}
  {
    "error": "UNAUTHORIZED",
    "details": []
  }
  ```
</ResponseExample>