Detailed technical description of the Alias API call.

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

alias is an advanced method that lets you change the tracked user's ID explicitly. This method is useful when managing identities for some of the downstream destinations.

The following destinations support the alias call:

Sample Payload

A sample payload of an alias call with most of the Common Fields removed is as shown:

"type": "alias",
"previousId": "[email protected]",
"userId": "12345"

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


The RudderStack SDK automatically passes the user's anonymousId as previousId in the payload, as seen above.

When instrumenting a website with the JavaScript SDK, making the alias call via the client-side is important as the anonymousId is generated via the browser. Similarly, if you're using a server-side SDK, the aliascall must be made from the server-side as the session ID is set as the anonymousId.

Alias Fields

Apart from the Common Fields, the alias call accepts the following fields:







See below

The user's current identifier.




The user's new identifier.

  • RudderStack does not require previousId mandatorily in case of the SDKs that offer persistence (JavaScript, Flutter, iOS, Android, React Native) as they will automatically set the previous userId/anonymousId as the previousId during an alias call.

  • For SDKs that do not offer persistence support (server-side SDKs like Node.js, Python, Java, .NET, PHP, Ruby), previousId needs to be specified explicitly during the alias call.

userId vs previousId

  • 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.

Contact Us

For more information on any section covered in this doc, you can contact us or start a conversation on our Slack channel.