Product Analytics

Aliasing Users

Aliasing links an additional ID to the current identity. Use it to associate multiple identifiers with the same user—such as linking IDs across platforms, migrating ID formats, or connecting external systems.

`identify()` vs `alias()`

Most identity resolution is handled by identify(). Use alias() only for specific cases.

Scenario	Method	Why
User logs in or signs up	`identify()`	Automatically links anonymous activity to the known user
User switches devices	`identify()`	Call with the same user ID on each device
Linking a Stripe or CRM ID	`alias()`	Connects an external system identifier to your user
Migrating from old to new ID format	`alias()`	Preserves history when changing ID schemes
User already identified on two platforms with different IDs	`alias()`	Merges two existing identified profiles

When to Use `alias()`

Call alias() after the user is identified. It links a secondary ID to their current identity.

Linking External System IDs

Connect third-party identifiers to your user profile:

// After a Stripe payment
altertable.alias(`stripe:${stripeCustomerId}`);

// After HubSpot sync
altertable.alias(`hubspot:${hubspotContactId}`);

ID Migration

When transitioning to a new ID format, alias the new ID to preserve historical data:

// User is identified with the legacy ID
altertable.identify('12345');

// Link the new ID format
altertable.alias('user_123');

Cross-Platform Linking

When users are already identified with different IDs on different platforms:

// On mobile: user is identified as user_123
// On web: same user is identified as user_456
// Link them together from either platform:
altertable.alias('user_456');

SDK Reference

JavaScript

altertable.alias('user_456');

React

const { alias } = useAltertable();

alias('user_456');

API Reference

POST https://api.altertable.ai/alias

{
  "distinct_id": "user_123",
  "alias_id": "stripe:cus_abc123"
}

Returns 200 OK on success.

Best Practices

Identify first: Only alias after the user has a primary identity
Use prefixes: stripe:, hubspot:, legacy: help distinguish ID sources
Alias once: Don't repeatedly alias the same ID
Avoid chains: Link all IDs directly to the primary user ID, not to each other