Identities | SeerStack

Identities allow you to attach permanent traits to a user_id. When you send events with that user_id, SeerStack automatically associates the event 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: 'grace@hopper.com',
  name: 'Grace Hopper',
  attributes: {
    plan: 'enterprise',
    team_size: 15,
    is_admin: true
  }
});

Identity Fields

Note

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.

Note

If you filter by attributes.plan = 'enterprise', SeerStack will find all events triggered by users with that plan, even if the event 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: 'grace@hopper.com',
  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 events 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.

PreviousWeb Analytics NextVisualization