Alias

Get started with the RudderStack Alias API call.

The alias call lets you merge different identities of a known user.

info
RudderStack supports sending alias events only to select downstream destinations. Refer to the destination-specific documentation for more details.
warning
The alias call is used only for merging user identitites. It does not update the user’s traits or other common properties.

Alias fields

In addition to the Common Fields, the alias call accepts the following fields:

FieldDescriptionData typePresence
userIdThe user’s unique identifier in the database. Either userId or anonymousId should be present.StringOptional, if anonymousId is already set.
previousIdThe user’s previous identifier.StringRequired

User ID vs Previous ID

  • The previousId attribute refers to the previous user identifier. It could be either:
    • An anonymousId assigned to the user (by the browser if the user is a new visitor or has not logged in yet, or the session ID if you’re using a server-side SDK).
    • A previously set userId to identify the user via the identify call.
  • The userId is the user’s new identity or an existing identity that you want to merge with previousId.

Sample payload

A sample payload of an alias call is shown below:

{
  "type": "alias",
  "previousId": "name@surname.com",
  "userId": "12345"
}

The corresponding event that generates the above payload via the JavaScript SDK is as shown:

rudderanalytics.alias("12345")
info
The RudderStack SDK automatically passes the user’s anonymousId as previousId in the payload.
warning
When instrumenting your website with the JavaScript SDK, the alias call must be made from the client-side as the anonymousId is generated via the browser. Similarly, if you’re using a server-side SDK, the alias call must be made from the server-side as the session ID is set as the anonymousId.

Questions? Contact us by email or on Slack