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.
Saytics.identify('user_789', {
name: 'Alice Smith',
email: 'alice@example.com',
plan: 'team',
created_at: '2024-01-01T00:00:00Z'
});
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 tiermrr — monthly recurring revenue attributed to this userrole — the user’s role within their organizationdepartment — 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.
// Only the plan trait is updated; all other traits remain as-is
Saytics.identify('user_789', {
plan: 'enterprise'
});
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.
await saytics.identify({
userId: 'user_789',
traits: {
plan: 'enterprise',
seats: 50
}
});
Sync traits that change over time (like plan or mrr) from your backend to keep user profiles accurate.