openapi: 3.0.2
x-readme-deploy-id: identity
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
tags:
  - name: Identities
    description: Register or merge users with a new identity.
paths:
  /track#create-identity:
    post:
      tags:
        - Identities
      summary: Create Identity
      operationId: create-identity
      description: ''
      security:
        - {}
      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": "$identify",
                              "properties": {
                                  "$identified_id": "ORIGINAL_ID",
                                  "$anon_id": "NEW_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'
  /track#identity-create-alias:
    post:
      tags:
        - Identities
      summary: Create Alias
      operationId: identity-create-alias
      description: ''
      security:
        - {}
      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'
  /import:
    post:
      tags:
        - Identities
      summary: Merge Identities
      operationId: identity-merge
      description: ''
      security:
        - ServiceAccount: []
        - ProjectSecret: []
        - OAuthToken: []
      parameters:
        - in: query
          name: strict
          required: true
          schema:
            type: string
            default: '1'
            enum:
              - '0'
              - '1'
          description: >-
            When set to 1 (recommended), Mixpanel will validate the batch and
            return errors per event that failed.
        - in: query
          name: project_id
          required: false
          schema:
            type: string
          description: >-
            The Mixpanel project_id, used to authenticate service account
            credentials (do not provide if using secret auth).
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: array
              items:
                type: object
                required:
                  - event
                  - properties
                properties:
                  event:
                    type: string
                    title: event
                    description: >-
                      This is the name of the event. If you're loading data from
                      a data warehouse, we recommend using the name of the table
                      as the name of the event.
                    default: $merge
                  properties:
                    type: object
                    title: properties
                    required:
                      - $distinct_ids
                      - token
                    properties:
                      $distinct_ids:
                        type: array
                        minItems: 2
                        maxItems: 2
                        items:
                          type: string
                        description: The two distinct_ids to merge together.
      responses:
        '200':
          $ref: '#/components/responses/StrictReceived'
        '400':
          $ref: '#/components/responses/StrictInvalid'
        '401':
          $ref: '#/components/responses/StrictUnauthorized'
components:
  securitySchemes:
    ServiceAccount:
      type: http
      scheme: basic
      description: Service Account
    ProjectSecret:
      type: http
      scheme: basic
      description: Project Secret
    OAuthToken:
      type: http
      scheme: bearer
      description: OAuth Token
  schemas:
    IntegerPropertyAsBooleanFlag:
      type: integer
      minimum: 0
      maximum: 1
    ImportRequestParameters:
      type: object
      properties:
        strict:
          allOf:
            - $ref: '#/components/schemas/IntegerPropertyAsBooleanFlag'
          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
          description: Details about the error that occurred
        status:
          type: string
          enum:
            - error
    ResponseStatusOk:
      type: string
      description: '"ok" if the request succeeded, "error" otherwise.'
      example: ok
      enum:
        - ok
  responses:
    400BadRequest:
      description: Bad request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    401Unauthorized:
      description: Unauthorized
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    403Forbidden:
      description: Forbidden
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    404NotFound:
      description: Not Found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    StrictReceived:
      description: A 200 response indicates all events were successfully ingested.
      content:
        application/json:
          schema:
            type: object
            properties:
              code:
                type: integer
              num_records_imported:
                type: integer
              status:
                type: string
            example:
              code: 200
              num_records_imported: 2000
              status: OK
    StrictInvalid:
      description: A 400 response indicates that some events failed validation.
      content:
        application/json:
          schema:
            type: object
            properties:
              code:
                type: integer
              error:
                type: string
              status:
                type: string
              num_records_imported:
                type: integer
              failed_records:
                type: array
                items:
                  type: object
                  properties:
                    index:
                      type: number
                    insert_id:
                      type: string
                    field:
                      type: string
                    message:
                      type: string
            example:
              code: 400
              num_records_imported: 999
              status: Bad Request
              failed_records:
                - index: 0
                  insert_id: 13c0b661-f48b-51cd-ba54-97c5999169c0
                  field: properties.time
                  message: >-
                    'properties.time' is invalid: must be specified as seconds
                    since epoch
    StrictUnauthorized:
      description: A 401 response indicates invalid service account credentials.
      content:
        application/json:
          schema:
            type: object
            properties:
              code:
                type: integer
              error:
                type: string
              status:
                type: string
            example:
              code: 401
              error: Invalid service account credentials
              status: Unauthorized
    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'
x-explorer-enabled: true
x-proxy-enabled: true
x-samples-enabled: true
x-samples-languages:
  - curl
  - node
  - ruby
  - javascript
  - python