Skip to main content

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.

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'
});
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.
TraitTypeDescription
namestringFull name
emailstringEmail address
created_atISO 8601 dateAccount creation date
avatarstring (URL)Profile image URL
companystringCompany 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. 
// 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. 
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.