> This page is part of the [Customer.io documentation](https://docs-customerio.netlify.app). For the complete index, see [llms.txt](https://docs-customerio.netlify.app/llms.txt).
> Last updated: February 6, 2025

# Alias

 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 [API documentation](/integrations/api/cdp) and start writing code.

## How it works[](#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 out to a service 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.**

## What comes first: alias or identify?[](#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[](#associating-anonymous-activity-with-a-user-id)

Most of the services we integrate with 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*](https://docs.mixpanel.com/docs/tracking-methods/id-management/identifying-users#simplified-vs-original-id-merge) to support identity merging without `alias` calls.

## A typical call[](#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 integrations.

```javascript
cioanalytics.alias("userId","previousId");
```

## The full payload[](#complete-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](/integrations/data-in/source-spec/common-fields) for more information about context, integrations, and timestamps in source payloads.

```json
{
  "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.