> ## 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.

# Identify

> Create or update a user profile

#### Description

Create or update a user profile. Call this when a user signs up, logs in, or when you want to update their attributes.

Short alias: `POST /v1/i`

**When to use:**

* User signs up or logs in → call identify with their `userId` and traits
* User updates their profile (name, email, plan) → call identify with updated traits
* Merging anonymous pre-signup activity → call identify with both `userId` and `anonymousId`

**What happens:**

1. If `userId` is new → creates a new user profile
2. If `userId` exists → merges `traits` with existing profile (additive, not replace)
3. If both `userId` and `anonymousId` are provided → links all anonymous events to the identified profile

#### 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">
  Your application's stable identifier for this user. At least one of `userId` or `anonymousId` is required.
</ParamField>

<ParamField body="anonymousId" type="string" placeholder="anon_abc-123">
  Anonymous ID from the SDK. Required if `userId` is not provided. Providing both triggers identity merge.
</ParamField>

<ParamField body="traits" type="object">
  Key-value user attributes to set or update (for example `email`, `name`, `plan`).
</ParamField>

<ParamField body="timestamp" type="string" placeholder="2026-05-04T10:00:00.000Z">
  When the identify happened, as ISO 8601. Defaults to server time if omitted.
</ParamField>

<ParamField body="messageId" type="string" placeholder="msg_unique_id">
  Deduplication ID. SDKs generate this automatically.
</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>

#### 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": "userId",
        "message": "userId is required"
      }
    ]
  }
  ```

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