> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mixpanel.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Create Alias

<Note>
  The `$create_alias` event payload is only useful for projects using the Original ID Merge system and the Legacy ID Management System; it has no functionality in the Simplified ID Merge system. Please review [this section of our documentation](/docs/tracking-methods/id-management#identity-merge-apis) for more information.
</Note>

<Note>
  You can also use the import endpoint: [https://api.mixpanel.com/import/](https://api.mixpanel.com/import/)
</Note>

Mixpanel supports adding an alias to a distinct id. An alias is a new value that will be interpreted by Mixpanel as an existing value. That means that you can send messages to Mixpanel using the new value, and Mixpanel will continue to use the old value for calculating funnels and retention reports, or applying updates to user profiles.

**Alias Criteria:**

<Frame className="bg-white">
  <img alt="960" src="https://mintcdn.com/mixpanel-edb78807/ogXlzma9enlXzenB/images/reference/d16f1d3-ID_management_alias_3-HTTP.png?fit=max&auto=format&n=ogXlzma9enlXzenB&q=85&s=a8133326f57b6229570d5a59de6e2fde" title="Identity Management - Alias" width="1600" height="1162" data-path="images/reference/d16f1d3-ID_management_alias_3-HTTP.png" />
</Frame>

**Required [Event Object](/docs/data-structure/concepts#anatomy-of-an-event) attributes**

<table>
  <thead>
    <tr>
      <th>Event Object property</th>
      <th>Type</th>
      <th>Description</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>**event**</td>

      <td>
        <span style={{ fontFamily: "courier" }}>String</span><br /><span style={{ color: "red" }}>required</span>
      </td>

      <td>value must be: <br />`$create_alias`</td>
    </tr>

    <tr>
      <td>**properties**</td>

      <td>
        <span style={{ fontFamily: "courier" }}>Object</span><br /><span style={{ color: "red" }}>required</span>
      </td>

      <td />
    </tr>

    <tr>
      <td>**properties.distinct\_id**</td>

      <td>
        <span style={{ fontFamily: "courier" }}>String</span><br /><span style={{ color: "red" }}>required</span>
      </td>

      <td>A distinct\_id to be merged with the alias.</td>
    </tr>

    <tr>
      <td>**properties.alias**</td>

      <td>
        <span style={{ fontFamily: "courier" }}>String</span><br /><span style={{ color: "red" }}>required</span>
      </td>

      <td>A new distinct\_id to be merged with the original distinct\_id. Each alias can only map to one distinct\_id.</td>
    </tr>

    <tr>
      <td>**properties.token**</td>

      <td>
        <span style={{ fontFamily: "courier" }}>String</span><br /><span style={{ color: "red" }}>required</span>
      </td>

      <td>The project token.</td>
    </tr>
  </tbody>
</table>


## OpenAPI

````yaml openapi/identity.openapi.yaml POST /track#identity-create-alias
openapi: 3.0.2
info:
  title: Identity API
  description: APIs to identify anonymous user IDs to their canonical user ID.
  license:
    name: MIT
    url: https://opensource.org/licenses/MIT
  version: 1.0.0
  contact:
    url: https://mixpanel.com/get-support
servers:
  - url: https://{region}.mixpanel.com
    description: Mixpanel's data collection server.
    variables:
      region:
        default: api
        enum:
          - api
          - api-eu
          - api-in
        description: |
          The server location to be used:
            * `api` - The default (US) servers used for most projects
            * `api-eu` - EU servers if you are enrolled in EU Data Residency
            * `api-in` - India servers if you are enrolled in India Data Residency
security: []
tags:
  - name: Identities
    description: Register or merge users with a new identity.
paths:
  /track#identity-create-alias:
    post:
      tags:
        - Identities
      summary: Create Alias
      operationId: identity-create-alias
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              allOf:
                - type: object
                  required:
                    - data
                  properties:
                    data:
                      type: string
                      format: blob
                      description: >-
                        A JSON object with the required Event Object fields and
                        any additional event properties.
                      default: |
                        {
                            "event": "$create_alias",
                            "properties": {
                                "distinct_id": "other_distinct_id",
                                "alias": "your_id",
                                "token": "YOUR_PROJECT_TOKEN"
                            }
                        }
                - $ref: '#/components/schemas/ImportRequestParameters'
      responses:
        '200':
          $ref: '#/components/responses/Received'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
      security:
        - {}
components:
  schemas:
    ImportRequestParameters:
      allOf:
        - type: object
          properties:
            strict:
              allOf:
                - type: integer
                  minimum: 0
                  maximum: 1
                - description: >-
                    If present and equal to 1, Mixpanel will validate the
                    provided records and return a JSON object with per-record
                    error messages for records that fail validation.
    ErrorResponse:
      type: object
      properties:
        error:
          type: string
        status:
          type: string
          enum:
            - error
  responses:
    Received:
      content:
        text/plain:
          schema:
            type: integer
            enum:
              - 1
              - 0
          examples:
            Valid Data:
              value: 1
            Invalid Data:
              value: 0
      description: >

        * `1` - All data objects provided are valid. This does not signify a
        valid project token or secret.

        * `0` - One or more data objects in the body are invalid.
    Unauthorized:
      description: Unauthorized
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    Forbidden:
      description: Forbidden
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'

````