Amplitude User Mapping API

openapi: 3.1.0
info:
  title: Amplitude User Mapping API
  description: >-
    The Amplitude User Mapping (Aliasing) API allows developers to merge
    users with different user IDs together in Amplitude. This is useful
    when a user initially interacts with a product anonymously and later
    creates an account, or when users have multiple identifiers across
    different systems. The API maps these distinct identities into a single
    unified user profile to ensure accurate analytics and attribution.
  version: '2'
  contact:
    name: Amplitude Support
    url: https://amplitude.com/contact
  termsOfService: https://amplitude.com/terms
externalDocs:
  description: Amplitude User Mapping API Documentation
  url: https://amplitude.com/docs/apis/analytics/user-mapping
servers:
- url: https://amplitude.com
  description: Amplitude Production Server
tags:
- name: User Mapping
  description: User identity mapping and aliasing operations
security:
- basicAuth: []
paths:
  /api/2/usermap:
    post:
      operationId: mapUser
      summary: Amplitude Map User Identities
      description: >-
        Merge two user identities together by mapping one user_id to another.
        After mapping, all events and user properties from both identities
        are consolidated into a single user profile. This is typically used
        when an anonymous user creates an account.
      tags:
      - User Mapping
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UserMapRequest'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserMapResponse'
              examples:
                mapUser200Example:
                  summary: Default mapUser 200 response
                  x-microcks-default: true
                  value:
                    code: 100
                    success: true
        '400':
          description: Bad request - invalid mapping data
        '401':
          description: Unauthorized
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /api/2/userunmap:
    post:
      operationId: unmapUser
      summary: Amplitude Unmap User Identities
      description: >-
        Reverse a previously created user identity mapping. After unmapping,
        the two identities are treated as separate users again. This does
        not retroactively separate events that were already merged.
      tags:
      - User Mapping
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UserUnmapRequest'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserMapResponse'
              examples:
                unmapUser200Example:
                  summary: Default unmapUser 200 response
                  x-microcks-default: true
                  value:
                    code: 100
                    success: true
        '400':
          description: Bad request - invalid unmap data
        '401':
          description: Unauthorized
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
components:
  securitySchemes:
    basicAuth:
      type: http
      scheme: basic
      description: >-
        Use your Amplitude API key as the username and your secret key as the
        password. Encode them as base64 in the format api_key:secret_key.
  schemas:
    UserMapRequest:
      type: object
      required:
      - mapping
      properties:
        mapping:
          type: array
          description: >-
            An array of user mapping objects, each mapping a global_user_id
            to one or more user_ids.
          items:
            $ref: '#/components/schemas/UserMapping'
    UserMapping:
      type: object
      required:
      - global_user_id
      - user_id
      properties:
        global_user_id:
          type: string
          description: >-
            The primary user ID that other identities will be mapped to.
        user_id:
          type: string
          description: >-
            The user ID to map to the global_user_id.
        unmap:
          type: boolean
          description: >-
            When true, removes the mapping instead of creating it.
    UserUnmapRequest:
      type: object
      required:
      - mapping
      properties:
        mapping:
          type: array
          description: >-
            An array of user mapping objects to reverse.
          items:
            $ref: '#/components/schemas/UserMapping'
    UserMapResponse:
      type: object
      properties:
        code:
          type: integer
          description: >-
            The HTTP status code of the response.
          example: 200
        success:
          type: boolean
          description: >-
            Whether the mapping operation was successful.