Skip to main content
Identities allow you to attach permanent traits to a user_id. When you send logs with that user_id, SeerStack automatically associates the log with these traits.

​
Identifying Users

Call users.identify when a user signs up or updates their profile. You only need to send the fields that have changed. 
import Seerstack from 'seerstack';

const client = new Seerstack({
  apiKey: process.env['SEERSTACK_API_KEY'],
});

await client.users.identify({
  user_id: 'user_123', // Your internal ID
  email: '[email protected]',
  name: 'Grace Hopper',
  attributes: {
    plan: 'enterprise',
    team_size: 15,
    is_admin: true
  }
});

​
Identity Fields

FieldTypeRequiredDescription
user_idstringYesYour internal user ID (database primary key).
emailstringNo*The user’s email address.
namestringNo*The user’s display name.
attributesobjectNoCustom attributes for filtering and segmentation.
Either email or name must be provided when identifying a user.

​
Automatic Enrichment

Once a user is identified, you can use their attributes in your dashboard filters.
If you filter by attributes.plan = 'enterprise', SeerStack will find all logs triggered by users with that plan, even if the log payload itself didn’t contain the plan name.

​
Updating User Attributes

You can call identify multiple times. Each call merges new attributes with existing ones. 
// Initial identification
await client.users.identify({
  user_id: 'user_123',
  email: '[email protected]',
  attributes: { plan: 'free' }
});

// Later, when user upgrades
await client.users.identify({
  user_id: 'user_123',
  attributes: { plan: 'enterprise', upgraded_at: new Date().toISOString() }
});

​
Best Practices

Use Stable IDs

Use your database’s primary key (e.g., UUID) as the user_id, not an email address or username which might change.

Identify Early

Call identify as soon as your user logs in to ensure subsequent logs are correctly attributed.

Keep Attributes Clean

Use consistent naming for attributes across your codebase. Prefer snake_case for attribute keys.

Don't Over-Identify

You don’t need to call identify on every request. Once is enough until attributes change.