Snapchat Conversion Events API

openapi: 3.1.0
info:
  title: Snapchat Ads Ad Accounts Conversion Events API
  description: The Snapchat Ads API allows developers to programmatically create, manage, and optimize advertising campaigns on the Snapchat platform. It provides endpoints for managing organizations, ad accounts, campaigns, ad squads, ads, creatives, media, funding sources, audience segments, and measurement reporting. The API supports the full advertising lifecycle from campaign setup through reporting and optimization.
  version: '1.0'
  contact:
    name: Snap for Developers
    url: https://developers.snap.com
  termsOfService: https://snap.com/en-US/terms
servers:
- url: https://adsapi.snapchat.com/v1
  description: Production Server
security:
- bearerAuth: []
tags:
- name: Conversion Events
  description: Endpoints for sending web, app, and offline conversion events to Snap for campaign measurement and optimization.
paths:
  /{pixel_id}/events:
    post:
      operationId: sendWebConversionEvents
      summary: Send Web Conversion Events
      description: Sends one or more web conversion events to Snap using a Pixel ID. Events can include purchases, page views, add-to-cart actions, sign-ups, and other custom conversion events. Multiple events can be sent in a single request (up to 2,000 per request). Events can have a timestamp of up to 37 days in the past.
      tags:
      - Conversion Events
      parameters:
      - $ref: '#/components/parameters/pixelId'
      - $ref: '#/components/parameters/accessTokenQuery'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ConversionEventRequest'
      responses:
        '200':
          description: Events received successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConversionEventResponse'
        '400':
          description: Bad request - invalid event data
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized - invalid or missing access token
        '429':
          description: Rate limit exceeded
  /{snap_app_id}/events:
    post:
      operationId: sendAppConversionEvents
      summary: Send App Conversion Events
      description: Sends one or more app conversion events to Snap using a Snap App ID. Used for tracking in-app events such as app installs, purchases, level completions, and other app-specific conversion events. Multiple events can be sent in a single request (up to 2,000 per request).
      tags:
      - Conversion Events
      parameters:
      - $ref: '#/components/parameters/snapAppId'
      - $ref: '#/components/parameters/accessTokenQuery'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ConversionEventRequest'
      responses:
        '200':
          description: Events received successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConversionEventResponse'
        '400':
          description: Bad request - invalid event data
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized - invalid or missing access token
        '429':
          description: Rate limit exceeded
components:
  parameters:
    accessTokenQuery:
      name: access_token
      in: query
      required: true
      description: The static long-lived access token for authentication.
      schema:
        type: string
    pixelId:
      name: pixel_id
      in: path
      required: true
      description: The Snap Pixel ID used for tracking web conversion events.
      schema:
        type: string
    snapAppId:
      name: snap_app_id
      in: path
      required: true
      description: The Snap App ID used for tracking app conversion events.
      schema:
        type: string
  schemas:
    AppData:
      type: object
      description: App-specific data for mobile app conversion events.
      properties:
        advertiser_tracking_enabled:
          type: boolean
          description: Whether the user has enabled advertiser tracking.
        application_tracking_enabled:
          type: boolean
          description: Whether the app has tracking enabled.
        extinfo:
          type: array
          description: Extended device information array.
          items:
            type: string
    ConversionEvent:
      type: object
      description: A single conversion event with event details, user data, and optional custom data.
      required:
      - event_name
      - event_time
      - action_source
      properties:
        event_name:
          type: string
          description: The name of the conversion event being reported.
          enum:
          - PAGE_VIEW
          - VIEW_CONTENT
          - ADD_CART
          - ADD_TO_WISHLIST
          - SIGN_UP
          - SEARCH
          - PURCHASE
          - ADD_BILLING
          - COMPLETE_TUTORIAL
          - SUBSCRIBE
          - AD_CLICK
          - AD_VIEW
          - START_CHECKOUT
          - RATE
          - LIST_VIEW
          - ADD_TO_CART
          - LEVEL_COMPLETE
          - ACHIEVEMENT_UNLOCKED
          - SPEND_CREDITS
          - SAVE
          - SHARE
          - INVITE
          - LOGIN
          - RESERVE
          - START_TRIAL
          - CUSTOM_EVENT_1
          - CUSTOM_EVENT_2
          - CUSTOM_EVENT_3
          - CUSTOM_EVENT_4
          - CUSTOM_EVENT_5
        event_time:
          type: integer
          description: Unix timestamp in seconds when the event occurred. Events can be up to 37 days in the past.
        event_source_url:
          type: string
          format: uri
          description: The URL of the web page where the event occurred. Required for web events.
        event_id:
          type: string
          description: A unique identifier for the event, used for deduplication.
        action_source:
          type: string
          description: The source of the conversion event.
          enum:
          - WEB
          - MOBILE_APP
          - OFFLINE
        user_data:
          $ref: '#/components/schemas/UserData'
        custom_data:
          $ref: '#/components/schemas/CustomData'
        app_data:
          $ref: '#/components/schemas/AppData'
    UserData:
      type: object
      description: User identification data for matching conversion events to Snapchat users. All personally identifiable information should be hashed using SHA-256 before sending.
      properties:
        em:
          type: string
          description: SHA-256 hashed lowercase email address of the user.
        ph:
          type: string
          description: SHA-256 hashed phone number in E.164 format.
        fn:
          type: string
          description: SHA-256 hashed lowercase first name of the user.
        ln:
          type: string
          description: SHA-256 hashed lowercase last name of the user.
        ge:
          type: string
          description: SHA-256 hashed gender (m or f).
        db:
          type: string
          description: SHA-256 hashed date of birth in YYYYMMDD format.
        ct:
          type: string
          description: SHA-256 hashed lowercase city name.
        st:
          type: string
          description: SHA-256 hashed lowercase two-letter state code.
        zp:
          type: string
          description: SHA-256 hashed five-digit zip code.
        country:
          type: string
          description: SHA-256 hashed lowercase two-letter country code.
        external_id:
          type: string
          description: SHA-256 hashed external ID for the user.
        client_ip_address:
          type: string
          description: The IP address of the user's browser or device.
        client_user_agent:
          type: string
          description: The user agent string of the user's browser.
        sc_click_id:
          type: string
          description: The Snapchat click ID from the ad click URL parameter.
        sc_cookie1:
          type: string
          description: The Snapchat first-party cookie value.
        idfv:
          type: string
          description: iOS identifier for vendor.
        idfa:
          type: string
          description: iOS identifier for advertisers.
        madid:
          type: string
          description: Mobile advertising device ID (Android).
    ContentItem:
      type: object
      description: A product or content item associated with a conversion event.
      properties:
        id:
          type: string
          description: The product or content identifier.
        quantity:
          type: integer
          description: The quantity of the item.
          minimum: 1
        item_price:
          type: number
          format: double
          description: The price of the individual item.
        brand:
          type: string
          description: The brand name of the item.
        category:
          type: string
          description: The category of the item.
    ErrorResponse:
      type: object
      description: Error response returned when conversion event submission fails.
      properties:
        status:
          type: string
          description: The error status
        reason:
          type: string
          description: Human-readable error message
        param:
          type: string
          description: The parameter that caused the error
    CustomData:
      type: object
      description: Custom data associated with the conversion event, such as purchase amount, currency, and product information.
      properties:
        currency:
          type: string
          description: ISO 4217 currency code (e.g., USD, EUR).
          pattern: ^[A-Z]{3}$
        price:
          type: number
          format: double
          description: The value or price associated with the event.
        transaction_id:
          type: string
          description: A unique transaction identifier for deduplication.
        search_string:
          type: string
          description: The search query string for SEARCH events.
        sign_up_method:
          type: string
          description: The method used for sign-up (e.g., email, google, facebook).
        num_items:
          type: integer
          description: Number of items associated with the event.
        payment_info_available:
          type: integer
          description: Whether payment info is available (1 or 0).
          enum:
          - 0
          - 1
        contents:
          type: array
          description: Array of product or content items associated with the event.
          items:
            $ref: '#/components/schemas/ContentItem'
    ConversionEventResponse:
      type: object
      description: Response returned after successfully submitting conversion events.
      properties:
        status:
          type: string
          description: The status of the request
        reason:
          type: string
          description: Additional details about the response
    ConversionEventRequest:
      type: object
      description: The request body for sending conversion events. Contains an array of one or more event objects.
      required:
      - data
      properties:
        data:
          type: array
          description: Array of conversion event objects. Maximum 2,000 events per request.
          maxItems: 2000
          minItems: 1
          items:
            $ref: '#/components/schemas/ConversionEvent'
  securitySchemes:
    bearerAuth:
      type: oauth2
      description: OAuth 2.0 authorization. Access tokens are obtained via the authorization code flow and expire after 3600 seconds. Refresh tokens can be used to obtain new access tokens.
      flows:
        authorizationCode:
          authorizationUrl: https://accounts.snapchat.com/accounts/oauth2/auth
          tokenUrl: https://accounts.snapchat.com/login/oauth2/access_token
          scopes:
            snapchat-marketing-api: Access to the Snapchat Marketing API
externalDocs:
  description: Snapchat Ads API Documentation
  url: https://developers.snap.com/api/marketing-api/Ads-API/introduction