Altertable

Aliasing Users

Aliasing links multiple identifiers to the same user profile. Use it when you need to explicitly say that two existing IDs refer to the same person.

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

Reach for alias() when you are intentionally merging identifiers, such as a legacy ID and a new ID format, or an external system identifier and your internal user ID.

`identify()` vs `alias()`

identify() is the default path for login and signup flows. Use alias() for explicit identity merges.

Scenario	Recommended method	Why
Login or signup	`identify()`	Automatically links anonymous activity to the known user.
Known user on another device	`identify()`	Call with the same user ID on each device.
Migrate from old ID format to new ID format	`alias()`	Preserves history when changing ID schemes.
Attach CRM or billing identifier	`alias()`	Connects an external system identifier to your user.
Merge profiles across platforms	`alias()`	Links two existing identified profiles together.

When you probably do not need aliasing

You usually do not need alias() for:

a user logging in on the web for the first time
a user signing in on multiple devices with the same account
updating traits such as plan, email, or account role

In those cases, call identify() with the same stable distinct_id wherever the user is authenticated.

SDK examples

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

# link a CRM identifier
client.alias(
    distinct_id="user_123",
    new_user_id="stripe:cus_abc123"
)

Recommended aliasing rules

Pick one canonical distinct_id and alias secondary IDs to it.
Identify the user first, then alias secondary IDs.
Add source prefixes to alias IDs, for example stripe:, crm:, or legacy:.
Link aliases directly to the primary user ID, not to each other.
Avoid repeatedly sending the same alias pair.

Direct API usage

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

1
2
3
4
5
6
7
curl -X POST https://api.altertable.ai/alias \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "distinct_id":"user_123",
    "alias_id":"stripe:cus_abc123"
  }'

Returns 200 OK on success.

Best practices

Use aliasing sparingly and only when you are merging meaningful IDs.
Keep your primary distinct_id stable over time.
Use source prefixes to make alias IDs self-explanatory, for example stripe:, crm:, or legacy:.
Link aliases directly to a primary user ID, not to each other.
Avoid repeatedly sending the same alias pair.