openapi: 3.1.0
info:
  title: Amplitude Attribution 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
externalDocs:
  description: Amplitude Attribution API Documentation
  url: https://amplitude.com/docs/apis/analytics/attribution
servers:
- url: https://api2.amplitude.com
  description: Amplitude US Production Server
- url: https://api.eu.amplitude.com
  description: Amplitude EU Production Server
tags:
- name: Attribution
  description: Campaign attribution event operations
security: []
paths:
  /attribution:
    post:
      operationId: sendAttribution
      summary: Amplitude Send Attribution Data
      description: >-
        Send a campaign attribution event to Amplitude to associate a user
        with the marketing campaign, channel, or creative that drove their
        acquisition or re-engagement. The event object should contain
        attribution-specific fields such as campaign name, source, medium,
        and ad creative.
      tags:
      - Attribution
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AttributionRequest'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AttributionResponse'
              examples:
                sendAttribution200Example:
                  summary: Default sendAttribution 200 response
                  x-microcks-default: true
                  value:
                    code: 100
                    events_ingested: 100
                    server_upload_time: 1718153645993
        '400':
          description: Bad request - missing required fields
        '429':
          description: Too many requests - rate limit exceeded
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
components:
  schemas:
    AttributionRequest:
      type: object
      required:
      - api_key
      - event
      properties:
        api_key:
          type: string
          description: >-
            The API key for the Amplitude project.
        event:
          $ref: '#/components/schemas/AttributionEvent'
    AttributionEvent:
      type: object
      required:
      - event_type
      properties:
        user_id:
          type: string
          description: >-
            The user ID to attribute the campaign event to. Required unless
            device_id is present.
        device_id:
          type: string
          description: >-
            The device ID. Required unless user_id is present.
        event_type:
          type: string
          description: >-
            The type of attribution event, typically a campaign-related event
            such as install or re-engage.
        platform:
          type: string
          description: >-
            The platform of the device, such as iOS or Android.
        os_name:
          type: string
          description: >-
            The operating system name.
        os_version:
          type: string
          description: >-
            The operating system version.
        device_brand:
          type: string
          description: >-
            The brand of the device.
        device_manufacturer:
          type: string
          description: >-
            The manufacturer of the device.
        device_model:
          type: string
          description: >-
            The model of the device.
        carrier:
          type: string
          description: >-
            The carrier of the device.
        country:
          type: string
          description: >-
            The country of the user.
        region:
          type: string
          description: >-
            The region or state of the user.
        city:
          type: string
          description: >-
            The city of the user.
        language:
          type: string
          description: >-
            The language setting of the user.
        adid:
          type: string
          description: >-
            The Google Play Services advertising ID (Android).
        idfa:
          type: string
          description: >-
            The Identifier for Advertiser (iOS).
        idfv:
          type: string
          description: >-
            The Identifier for Vendor (iOS).
        user_properties:
          type: object
          description: >-
            User property operations to set alongside the attribution event.
            Typically used to set campaign-related properties like
            utm_source, utm_medium, utm_campaign, utm_term, and utm_content.
          additionalProperties: true
        event_properties:
          type: object
          description: >-
            Additional properties associated with the attribution event such
            as campaign name, ad group, ad creative, and network.
          additionalProperties: true
        time:
          type: integer
          format: int64
          description: >-
            The timestamp of the event in milliseconds since epoch.
    AttributionResponse:
      type: object
      properties:
        code:
          type: integer
          description: >-
            The HTTP status code of the response.
          example: 200
        events_ingested:
          type: integer
          description: >-
            The number of events successfully ingested.
        server_upload_time:
          type: integer
          format: int64
          description: >-
            The time the server received the upload in milliseconds since epoch.