openapi: 3.1.0
info:
  title: Amplitude Attribution Annotations Data Deletion 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: Data Deletion
  description: User data deletion request operations
paths:
  /api/2/deletions/users:
    post:
      operationId: createDeletionRequest
      summary: Amplitude Request User Data Deletion
      description: Submit a request to delete all event data and user properties for one or more users identified by Amplitude IDs or user IDs. Each HTTP request can contain up to 100 amplitude_ids or user_ids. Rate limited to 1 request per second. Amplitude emails all account admins with deletion details when a request is submitted.
      tags:
      - Data Deletion
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DeletionRequest'
      responses:
        '200':
          description: Success - deletion request accepted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeletionResponse'
              examples:
                createDeletionRequest200Example:
                  summary: Default createDeletionRequest 200 response
                  x-microcks-default: true
                  value:
                    day: '2025-03-15'
                    status: active
        '400':
          description: Bad request - invalid identifiers or exceeds 100 IDs
        '401':
          description: Unauthorized
        '429':
          description: Too many requests - rate limit of 1 per second exceeded
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    get:
      operationId: listDeletionRequests
      summary: Amplitude List Deletion Requests
      description: Retrieve a list of previously submitted deletion requests and their processing status.
      tags:
      - Data Deletion
      parameters:
      - name: start_day
        in: query
        description: The start date to filter deletion requests in YYYY-MM-DD format.
        schema:
          type: string
          format: date
      - name: end_day
        in: query
        description: The end date to filter deletion requests in YYYY-MM-DD format.
        schema:
          type: string
          format: date
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeletionListResponse'
              examples:
                listDeletionRequests200Example:
                  summary: Default listDeletionRequests 200 response
                  x-microcks-default: true
                  value:
                    deletions:
                    - day: {}
                      status: {}
                      amplitude_ids: {}
                      user_ids: {}
        '401':
          description: Unauthorized
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
components:
  schemas:
    DeletionResponse:
      type: object
      properties:
        day:
          type: string
          format: date
          description: The day the deletion job is scheduled for processing.
        status:
          type: string
          description: The status of the deletion request.
    DeletionRequest:
      type: object
      properties:
        amplitude_ids:
          type: array
          description: Array of Amplitude internal user IDs to delete data for. Maximum 100 per request.
          maxItems: 100
          items:
            type: integer
            format: int64
        user_ids:
          type: array
          description: Array of user IDs to delete data for. Maximum 100 per request.
          maxItems: 100
          items:
            type: string
        requester:
          type: string
          description: The email address of the person requesting the deletion for audit purposes.
    DeletionListResponse:
      type: object
      properties:
        deletions:
          type: array
          description: Array of deletion request records.
          items:
            type: object
            properties:
              day:
                type: string
                format: date
                description: The day the deletion job was scheduled.
              status:
                type: string
                description: The processing status of the deletion.
                enum:
                - staging
                - submitted
                - done
              amplitude_ids:
                type: array
                description: Array of Amplitude IDs included in the deletion.
                items:
                  type: integer
                  format: int64
              user_ids:
                type: array
                description: Array of user IDs included in the deletion.
                items:
                  type: string
externalDocs:
  description: Amplitude Attribution API Documentation
  url: https://amplitude.com/docs/apis/analytics/attribution