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:

TypeScriptPythonRubySwiftKotlinCLI

Copy

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

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

TypeScriptSwiftKotlin

Copy

1

2

3

4

5

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

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

API reference

For HTTP request details, batching behavior, response shape, and error codes, see 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.