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

# Identify Users and Set Traits in Saytics

> Link anonymous sessions to user accounts with Saytics identify. Learn when to call identify, what traits to set, and how to update user profiles.

Calling `identify()` tells Saytics who is performing actions in your app, linking events to a real user account. Until you call `identify`, events are recorded against an anonymous ID that Saytics generates automatically. Once you identify a user, all subsequent events — and any prior anonymous events in the same session — are associated with that user's profile.

## When to call identify

Calling `identify` at the right moments keeps your user data accurate without generating unnecessary API calls.

* **After a user logs in** — link the session to their existing account
* **After a user signs up** — create their profile with initial traits like name and email
* **When user profile data changes** — update traits such as plan tier, company, or role
* **Not on every page load** — call `identify` once per session after authentication, not on navigation

## Basic identify call

Pass the user's unique ID as the first argument, followed by an object of traits that describe the user.

```js theme={null}
Saytics.identify('user_789', {
  name: 'Alice Smith',
  email: 'alice@example.com',
  plan: 'team',
  created_at: '2024-01-01T00:00:00Z'
});
```

The `userId` you pass should match the ID from your own database so you can correlate Saytics data with your records.

## Reserved traits

Saytics recognizes the following trait names and uses them to populate user profiles in the dashboard. Use these exact keys when sending the corresponding information.

| Trait        | Type          | Description           |
| ------------ | ------------- | --------------------- |
| `name`       | string        | Full name             |
| `email`      | string        | Email address         |
| `created_at` | ISO 8601 date | Account creation date |
| `avatar`     | string (URL)  | Profile image URL     |
| `company`    | string        | Company name          |

## Custom traits

Beyond the reserved traits, you can include any additional key-value pairs that are relevant to your product. Common examples include:

* `plan` — the user's subscription tier
* `mrr` — monthly recurring revenue attributed to this user
* `role` — the user's role within their organization
* `department` — the team or department they belong to

Custom traits appear alongside reserved traits in the user profile view in Saytics and can be used to filter and segment your data.

## Updating traits

Calling `identify()` with new traits merges them into the existing profile. Traits that are not included in the call are left unchanged, so you only need to send the properties that have actually changed.

```js theme={null}
// Only the plan trait is updated; all other traits remain as-is
Saytics.identify('user_789', {
  plan: 'enterprise'
});
```

If you want to clear a trait, pass an explicit empty value such as `null` or an empty string.

## Server-side identify

You can also call `identify` from your backend using the Node.js SDK. This is useful when profile changes are driven by server-side events, such as a subscription upgrade processed by your billing system.

```js theme={null}
await saytics.identify({
  userId: 'user_789',
  traits: {
    plan: 'enterprise',
    seats: 50
  }
});
```

<Tip>
  Sync traits that change over time (like `plan` or `mrr`) from your backend to keep user profiles accurate.
</Tip>