# Identify Users

Use `identify` when you know who a user is. Identification connects anonymous or device-level activity to a stable user ID and stores traits such as plan, role, or account tier.

In practice, `identify()` is the moment when analytics move from "someone did this" to "this user did this".

## When to call it

Call `identify()` as soon as your application establishes or restores authenticated user state:

- after sign-up
- after login
- on application load when the user is already authenticated

Client-side SDKs can link the anonymous activity that happened before login to the stable user ID. Server-side SDKs and direct API clients should pass the `distinct_id` and traits explicitly.

## SDK examples

Call `identify()` again when user or account traits change. Keep traits focused on fields you expect to analyze, filter, or join against.

Client-side SDKs also provide a helper for trait updates:

### TypeScript

```typescript
altertable.updateTraits({ plan: 'enterprise', onboarding_completed: true });
```

### Python

```python
client.identify(distinct_id="user_123", options={"traits": {"plan": "enterprise"}})
```

### Ruby

```ruby
Altertable.identify('user_123', traits: { plan: 'enterprise' })
```

### Swift

```swift
client.updateTraits(["plan": "enterprise"])
```

### Kotlin

```kotlin
Altertable.shared?.updateTraits(mapOf("plan" to "enterprise"))
```

### CLI

```bash
curl -X POST https://api.altertable.ai/identify \
  -H "Authorization: Bearer {{API_KEY}}" \
  -d '{"distinct_id": "user_123", "traits": {"plan": "enterprise"}}'
```

Call `reset()` on logout so later activity is not attributed to the previous user:

### TypeScript

```typescript
// Reset identity, keep device ID
altertable.reset();

// Reset all IDs including device ID
altertable.reset({ resetDeviceId: true });
```

### Swift

```swift
client.reset()
```

### Kotlin

```kotlin
// Reset identity, keep device ID
Altertable.shared?.reset()

// Reset all IDs including device ID
Altertable.shared?.reset(resetDeviceId = true)
```

## API reference

For HTTP request details, batching behavior, response shape, and error codes, see [`POST /identify`](/docs/api-references/product-analytics.md#post-identify).

## Best practices

- Use stable, immutable IDs from your own user system.
- Avoid mutable identifiers such as email addresses as `distinct_id`.
- Keep traits current as account state changes.
- Avoid secrets and regulated sensitive data in traits.