# 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()`](/docs/product-analytics/ingest-data/identify.md) 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:

### TypeScript

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

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

### Python

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

### Ruby

```ruby
# link a CRM identifier
Altertable.alias('user_123', 'stripe:cus_abc123')
```

### Swift

```swift
client.identify(userId: "12345")
client.alias(newUserId: "user_12345")
```

### Kotlin

```kotlin
Altertable.shared?.identify(userId = "12345")
Altertable.shared?.alias(newUserId = "user_12345")
```

## API reference

For HTTP request details, batching behavior, response shape, and error codes, see [`POST /alias`](/docs/api-references/product-analytics.md#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.