Alias

Updated

 See our API documentation for code samples

This page can help you better understand when and how to use this API method. But, if you already know how it works and are ready to get started, you can go straight to our Data Pipelines API documentation and start writing code.

How it works

An alias call helps you merge two user profiles—a userId and a previousId. The userId inherits the traits and activity of the previousId, so you can track activity going forward against the canonical userId.

Alias calls are typically useful in two situations:

  1. You send data to a destination that doesn’t automatically associate anonymous activity (under an anonymousId) with an identified person (a userId).
  2. A person generates multiple user IDs and you need to unify them under a single userId value.

You should send the alias call immediately before the identify call for a person.

flowchart LR subgraph z [Anonymous Activity] a(Person visits website)-->b(page views) end c(Person logs in)-->d(Alias anonymousId
to userId)-->e(Identify user
by userId) z-->f[(Identified User
Activity)] e-->f z-->c

What comes first: alias or identify?

You should send the alias call immediately before the identify call for a person. This ensures that the anonymous activity is associated with the identified user before the identified user starts generating new activity.

Associating anonymous activity with a user ID

Most of our libraries and destinations automatically associate anonymous activity with a userId when you identify a person, so you won’t need to implement Alias calls.

You should send the alias call immediately before the identify call for a person. This ensures that the anonymous activity is associated with the identified user before the identified user starts generating new activity.

 Mixpanel users: check your Identity Merge settings

Before March 2023, Mixpanel required you to use the alias method to merge anonymous data with an identified person. Now Mixpanel has a Simplified API for identity merging, so it’ll automatically merge anonymous and identified data! If you created your Mixpanel account before April 2024, you’ll need to enable the Simplified API to support identity merging without alias calls.

A typical call

A typical identify call is straightforward. It contains a userId and a previousId object. The userId is a person’s canonical identifier and the previousId is the identifier you want to remove or ignore in your downstream destinations.

analytics.alias("userId","previousId");

The full payload

While your requests are typically short, our libraries capture much more information. This helps us provide context, not only for the person you aliased, but the service you aliased them from.

Customer.io and our libraries typically populate integrations and timestamp values as shown in the payload below. If you use our JavaScript or mobile libraries, they’ll also populate context for you. If you use our server-side libraries, you’ll need to populate context yourself.

See common fields for more information about context, integrations, and timestamps in source payloads.

{
  "type": "identify",
  "userId": "97980cfea0067",
  "previousId": "97980cfea0067",
  "integrations": {
    "All": true
  },
  "messageId": "string",
  "receivedAt": "2019-08-24T14:15:22Z",
  "sentAt": "2019-08-24T14:15:22Z",
  "timestamp": "2019-08-24T14:15:22Z",
  "version": 0,
  "context": {
    "active": true,
    "ip": "string",
    "locale": "string",
    "userAgent": "string",
    "channel": "browser",
    "campaign": {
      "name": "string",
      "source": "string",
      "medium": "string",
      "term": "string",
      "content": "string"
    }
  }
}
  • previousId string
    Required The userId that you want to merge into the canonical profile.
  • userId string
    Required The userId that you want to keep. This is required if you haven’t already identified someone with one of our web or server-side libraries.
Copied to clipboard!
  Contents
Is this page helpful?