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

# Identify

> Associate the current session with a known user using identify().

Call `identify()` to link the current session to a user in your system — typically right after the user signs in. This is the simplest entry point for user association; it unlocks user-level filtering in the dashboard and enables AI queries to reason about specific users.

<Tip>
  `identify()` requires a `userId` **and** an `email`. For partial user updates later in the session (e.g. plan changes), use [`updateUser()`](/sdk/update-user) — it leaves `email` optional. For session-level metadata, use [`updateSession()`](/sdk/update-session).
</Tip>

<Tabs>
  <Tab title="React">
    Use the `useMilana()` hook:

    ```tsx theme={null}
    import { useEffect } from "react";
    import { useMilana } from "milana-js/react";

    function SignedInRoutes() {
      const { user } = useAuth();
      const { identify } = useMilana();

      useEffect(() => {
        if (user) {
          void identify({
            userId: user.id,
            email: user.email,
            name: user.name,
            metadata: {
              plan: user.plan,
              createdAt: user.createdAt,
            },
          });
        }
      }, [user, identify]);

      return <>{/* ... */}</>;
    }
    ```
  </Tab>

  <Tab title="JavaScript">
    ```typescript theme={null}
    import { identify } from "milana-js";

    await identify({
      userId: "usr_12345",
      email: "jane@example.com",
      name: "Jane",
      metadata: {
        createdAt: "2024-03-15T00:00:00Z",
        plan: "pro",
      },
    });
    ```
  </Tab>

  <Tab title="Script Tag">
    ```javascript theme={null}
    Milana("identify", {
      userId: "usr_12345",
      email: "jane@example.com",
      name: "Jane",
      metadata: {
        plan: "pro",
      },
    });
    ```
  </Tab>
</Tabs>

***

## Parameters

<ParamField path="userId" type="string" required>
  A stable, unique identifier for the user in your system. This is the primary key Milana uses to link sessions to a user. Use your database user ID or a similar permanent identifier — do not use an email address as the primary ID.
</ParamField>

<ParamField path="email" type="string" required>
  The user's email address. Used to connect user identity across your systems (e.g. support tools, CRM, data warehouse) and displayed in the dashboard.
</ParamField>

<ParamField path="name" type="string">
  The user's display name.
</ParamField>

<ParamField path="metadata" type="object">
  Arbitrary key-value pairs to attach to the user. Keys are strings, values can be `string`, `number`, `boolean`, `null`, or nested objects/arrays of the same types. e.g. `plan`, `team`, `country`, `role`, `accountType`.

  We strongly recommend including a `createdAt` key (ISO 8601 timestamp, e.g. `"2024-03-15T00:00:00Z"`) so Milana can distinguish new users from returning users and support cohort analysis.
</ParamField>

## Return value

<ResponseField name="success" type="boolean">
  `true` if the identification was applied to the session. `false` if the session was not active, the network request failed, or the session was not sampled.
</ResponseField>

## Timing

`identify()` is safe to call before `init()` completes — the SDK queues the call and replays it once the session is ready.