You're in the right place! Segment documentation is now part of Twilio Docs. The content you are used to is still here—just in a new home with a refreshed look.

Spec: Alias

The Alias method is an advanced method used to merge 2 unassociated user identities, effectively connecting 2 sets of user data in one profile.

(information)

Alias and Unify

Alias calls can't be used to merge profiles in Unify. For more information on how Unify merges user profiles, view the Identity Resolution documentation.

(information)

Alias is an advanced method

The Alias method allows you to explicitly change the ID of a tracked user. This should only be done when it's required for downstream destination compatibility. See the Best Practices for Identifying Users docs for more information.

Syntax

The Alias call has the following fields:

Field		Type	Description
`userId`		String	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 detail.
`previousId`	optional	String	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 Segment's Identify call.
`options`	optional	Object	A dictionary of options. For example, enable or disable specific destinations for the call.
`callback`	optional	Function	A function that is executed after a timeout of 300 ms, giving the browser time to make outbound requests first.

The Alias method follows the format below:

analytics.alias(userId, [previousId], [options], [callback]);

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

1{
2  "type": "alias",
3  "previousId": "jen@email.com",
4  "userId": "507f191e81"
5}

Here's the corresponding JavaScript event that would generate the above payload. If you're using Segment's JavaScript library, Segment automatically passes in the user's anonymousId as previousId for you:

analytics.alias("507f191e81");

If you're instrumenting a website, the Anonymous ID is generated in the browser so you must call Alias from the client-side. If you're using a server-side session ID as the Anonymous ID, then you must call Alias from the server-side.

(information)

Info

Based on the library you use, the syntax in the examples might be different. You can find library-specific documentation on the Sources Overview page.

Examples

Here's a complete example of an Alias call:

1{
2  "anonymousId": "507f191e810c19729de860ea",
3  "channel": "browser",
4  "context": {
5    "ip": "8.8.8.8",
6    "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_9_5) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/40.0.2214.115 Safari/537.36"
7  },
8  "integrations": {
9    "All": true,
10    "Mixpanel": false,
11    "Salesforce": false
12  },
13  "messageId": "022bb90c-bbac-11e4-8dfc-aa07a5b093db",
14  "previousId": "39239-239239-239239-23923",
15  "receivedAt": "2015-02-23T22:28:55.387Z",
16  "sentAt": "2015-02-23T22:28:55.111Z",
17  "timestamp": "2015-02-23T22:28:55.111Z",
18  "type": "alias",
19  "userId": "507f191e81",
20  "version": "1.1"
21}