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:\n  * `api` - The default (US) servers used for most projects\n  * `api-eu`\
        \ - EU servers if you are enrolled in EU Data Residency\n  * `api-in` - India servers if you are enrolled in India\
        \ Data Residency\n"
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: "{\n      \"event\": \"$identify\",\n      \"properties\": {\n          \"$identified_id\": \"\
                      ORIGINAL_ID\",\n          \"$anon_id\": \"NEW_ID\",\n          \"token\": \"YOUR_PROJECT_TOKEN\"\n \
                      \     }\n}\n"
              - $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: "{\n    \"event\": \"$create_alias\",\n    \"properties\": {\n        \"distinct_id\": \"other_distinct_id\"\
                      ,\n        \"alias\": \"your_id\",\n        \"token\": \"YOUR_PROJECT_TOKEN\"\n    }\n}\n"
              - $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:
    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:
    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