Amplitude Attribution API

openapi: 3.1.0
info:
  title: Amplitude Annotations 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
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: Attribution
  description: Campaign attribution event operations
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.
externalDocs:
  description: Amplitude Attribution API Documentation
  url: https://amplitude.com/docs/apis/analytics/attribution