openapi: 3.2.0
info:
  title: Amplitude Attribution Annotations User Mapping API
  description: The Amplitude Attribution API allows developers to send attribution campaign events to Amplitude from ad networks, attribution providers, or custom marketing tools. It associates users with the campaigns, channels, and creatives that drove their acquisition or re-engagement. This API is used to enrich Amplitude user profiles with marketing attribution data for campaign performance analysis and ROI measurement.
  version: '2'
  contact:
    name: Amplitude Support
    url: https://amplitude.com/contact
  termsOfService: https://amplitude.com/terms
servers:
- url: https://api2.amplitude.com
  description: Amplitude US Production Server
- url: https://api.eu.amplitude.com
  description: Amplitude EU Production Server
security: []
tags:
- name: User Mapping
  description: User identity mapping and aliasing operations
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:
  schemas:
    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.
    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.
    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'
externalDocs:
  description: Amplitude Attribution API Documentation
  url: https://amplitude.com/docs/apis/analytics/attribution