The alias method is used to merge the events of an Anonymous user (i.e. a user identified with an Anonymous ID) with the identity of a known user (i.e. a user identified with a User ID).

☝ Keep in mind! Currently, we only merge events – not traits – of an Anonymous user with the identity of known user.

How to make an alias call

Here’s the payload of a basic alias call that will associate this user’s existing id with a new one (a database ID), with most common fields removed:

  "type": "alias",
  "previousId": "anon-orwel1987",
  "userId": "79a1c782f370"

You can call the alias server-side or using our Plainflow.js client.

Here’s the corresponding Javascript event that would generate the above payload.


Note: Plainflow.js will automatically pass in the user’s anonymousId as previousId for you.

Alias fields

Beyond the common fields, the alias call takes the following fields:

userId requiredStringUnique identifier for the user in your database. A userId or anonymousId is required. See the Identities docs for more detail
previousId requiredStringPrevious unique identifier for the user. See the Previous ID field docs for more detail

Previous ID

The previousId is the existing ID you’ve referred to the user by. It might be an Anonymous ID assigned to that user or a User ID you previously identified them with using our identify call.

User ID

The userId is a string that will be the user’s new identity, or an existing identity that you wish to merge with the previousId. See the User ID docs for more details.


Here’s a complete example of an alias call:

  "anonymousId": "59f75a945b289f44d6e8aca5",
  "channel": "browser",
  "context": {
    "ip": "",
    "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_11) AppleWebKit/601.1.32 (KHTML, like Gecko) Version/8.1 Safari/601.1.32"
  "messageId": "aaf06138-2ceb-4881-9c73-79a1c782f370",
  "previousId": "anon-orwel1987",
  "receivedAt": "2017-02-09T12:08:32.387Z",
  "sentAt": "2017-02-23T22:28:55.111Z",
  "timestamp": "2017-02-23T22:28:55.111Z",
  "type": "alias",
  "userId": "79a1c782f370",
  "version": "1.1"

Not using Plainflow yet? Get your free account here. 👈