Alias Users

Use alias to explicitly link two existing identifiers to the same user profile.

Most teams do not need alias() for normal sign-up or login flows. In the common case, identify() is enough.

When to call it

Use alias() when you are intentionally merging identifiers, such as:

• a legacy ID and a new ID format
• an external system identifier and your internal user ID
• two known profiles that should resolve to one person

SDK examples

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

TypeScriptPythonRubySwiftKotlin

Copy

1

2

3

4

5

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

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

API reference

For HTTP request details, batching behavior, response shape, and error codes, see POST /alias.

Best practices

• Use aliasing sparingly and only for meaningful identity merges.
• Pick one canonical distinct_id and alias secondary IDs to it.
• Add source prefixes to alias IDs, such as stripe:, crm:, or legacy:.
• Link aliases directly to the primary user ID, not to each other.