Pinterest Events API

openapi: 3.0.3
info:
  version: 5.13.0
  title: Pinterest Events API
  description: This is the description of your API.
  contact:
    name: Pinterest, Inc.
    url: https://developers.pinterest.com/
  license:
    name: MIT
    url: https://spdx.org/licenses/MIT
  termsOfService: https://developers.pinterest.com/terms/
servers:
- url: https://api.pinterest.com/v5
tags:
- name: Events
paths:
  /ad_accounts/{ad_account_id}/events:
    post:
      summary: Send conversions
      description: 'The Pinterest API offers advertisers a way to send Pinterest their conversion information (including web conversions, in-app conversions, or even offline conversions) based on their <code>ad_account_id</code>. The request body should be a JSON object.

        - This endpoint requires an <code>access_token</code> be generated through Ads Manager. Review the <a href="/docs/conversions/conversions/">Conversions Guide</a> for more details.

        - The token''s <code>user_account</code> must either be the Owner of the specified ad account, or have one of the necessary roles granted to them via <a href="https://help.pinterest.com/en/business/article/share-and-manage-access-to-your-ad-accounts">Business Access</a>: Admin, Analyst, Audience, Campaign. (Note that the token can be used across multiple ad accounts under an user ID.)

        - This endpoint has a rate limit of 5,000 calls per minute per ad account.

        - If the merchant is submitting this information using both Pinterest conversion tags and the Pinterest API, Pinterest will remove duplicate information before reporting. (Note that events that took place offline cannot be deduplicated.)'
      operationId: events/create
      tags:
      - Events
      security:
      - pinterest_oauth2:
        - ads:write
      - conversion_token: []
      x-ratelimit-category: ads_conversions
      x-sandbox: disabled
      parameters:
      - $ref: '#/components/parameters/path_ad_account_id'
      - name: test
        description: 'Include query param ?test=true to mark the request as a test request. The events will not be recorded but the API will still return the same response messages. Use this mode to verify your requests are working and your events are constructed correctly.

          Warning: If you use this query parameter, be certain that it is off (set to false or deleted) before sending a legitimate (non-testing) request.'
        in: query
        required: false
        schema:
          type: boolean
      requestBody:
        description: Conversion events.
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ConversionEvents'
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConversionApiResponse'
          description: Success
        '400':
          description: The request was invalid.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                code: 4196
                message: The request was invalid.
        '401':
          description: Not authorized to send conversion events
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                UnauthorizedAccess:
                  value:
                    code: 2
                    message: Authentication failed.
        '403':
          description: Unauthorized access.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                UnauthorizedAccess:
                  value:
                    code: 29
                    message: You are not permitted to access that resource.
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DetailedError'
          description: Not all events were successfully processed.
        '429':
          description: 'This request exceeded a rate limit. This can happen if the client exceeds one

            of the published rate limits within a short time window.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                code: 8
                message: 'This request exceeded a rate limit. This can happen if the client exceeds one

                  of the published rate limits within a short time window.'
        '503':
          description: The endpoint has been ramped down and is currently not accepting any traffic.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                code: 4197
                message: The endpoint has been ramped down and is currently not accepting any traffic.
        default:
          description: Unexpected errors
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  schemas:
    DetailedError:
      title: Detailed Error
      description: Used for including extra details to a base error
      type: object
      properties:
        code:
          type: integer
        message:
          type: string
        details:
          type: object
      required:
      - code
      - message
      - details
    ConversionEvents:
      description: A list of events (one or more) encapsulated by a data object.
      type: object
      additionalProperties: false
      properties:
        data:
          type: array
          minItems: 1
          maxItems: 1000
          items:
            type: object
            additionalProperties: false
            properties:
              event_name:
                description: The type of the user event. Please use the right event_name otherwise the event wont be accepted and show up correctly in reports. <li><code>add_to_cart</code> <li><code>checkout</code> <li><code>custom</code> <li><code>lead</code> <li><code>page_visit</code> <li><code>search</code> <li><code>signup</code> <li><code>view_category</code> <li><code>watch_video</code>
                type: string
                example: checkout
              action_source:
                description: The source indicating where the conversion event occurred. <li><code>app_android</code> <li><code>app_ios</code> <li><code>web</code> <li><code>offline</code>
                type: string
                example: app_ios
              event_time:
                description: The time when the event happened. Unix timestamp in seconds.
                example: 1451431341
                type: integer
                format: int64
              event_id:
                description: A unique id string that identifies this event and can be used for deduping between events ingested via both the conversion API and Pinterest tracking. Without this, event's data is likely to be double counted and will cause report metric inflation. Third-party vendors make sure this field is updated on both Pinterest tag and Conversions API side before rolling out template for Conversions API.
                type: string
                example: eventId0001
              event_source_url:
                description: URL of the web conversion event.
                type: string
                example: https://www.my-clothing-shop.org/
                nullable: true
              opt_out:
                description: When action_source is web or offline, it defines whether the user has opted out of tracking for web conversion events. While when action_source is app_android or app_ios, it defines whether the user has enabled Limit Ad Tracking on their iOS device, or opted out of Ads Personalization on their Android device.
                type: boolean
                example: false
              partner_name:
                description: The third party partner name responsible to send the event to Conversions API on behalf of the advertiser. The naming convention is "ss-partnername" lowercase. E.g ss-shopify
                type: string
                example: ss-partnername
                nullable: true
              user_data:
                $ref: '#/components/schemas/ConversionEventsUserData'
              custom_data:
                description: Object containing other custom data.
                type: object
                additionalProperties: false
                properties:
                  currency:
                    description: The ISO-4217 currency code. If not provided, we will default to the advertiser's currency set during account creation. Your campaign performance needs this field to report right ROAS/CPA.
                    example: USD
                    type: string
                    nullable: true
                  value:
                    description: Total value of the event. Accepted as a string in the request; it will be parsed into a double. For example, if there are two items in a checkout event, the value should be the total price. We recommend to use pre-tax, pre-shipping final value.
                    example: '72.39'
                    type: string
                    nullable: true
                  content_ids:
                    description: List of products IDs. We recommend using this if you are a merchant for PageVisit, AddToCart and Checkouts. For detail, please check <a href="https://help.pinterest.com/en/business/article/before-you-get-started-with-catalogs" target="_blank">here</a> (Install the Pinterest tag section).
                    type: array
                    items:
                      type: string
                    example:
                    - red-pinterest-shirt-logo-1
                    - purple-pinterest-shirt-logo-3
                  content_name:
                    description: The name of the page or product associated with the event.
                    type: string
                    nullable: true
                    example: pinterest-themed-clothing
                  content_category:
                    description: The category of the content associated with the event.
                    type: string
                    nullable: true
                    example: shirts
                  content_brand:
                    description: The brand of the content associated with the event.
                    type: string
                    nullable: true
                    example: pinterest-brand
                  contents:
                    description: A list of objects containing information about products, such as price and quantity. We recommend using this if you are a merchant for PageVisit, AddToCart and Checkouts. For detail, please check <a href="https://help.pinterest.com/en/business/article/before-you-get-started-with-catalogs" target="_blank">here</a> (Install the Pinterest tag section).
                    type: array
                    items:
                      type: object
                      additionalProperties: false
                      properties:
                        id:
                          description: The id of a product. We recommend using this if you are a merchant for AddToCart and Checkouts. For detail, please check <a href="https://help.pinterest.com/en/business/article/before-you-get-started-with-catalogs" target="_blank">here</a> (Install the Pinterest tag section).
                          example: red-pinterest-shirt-logo-1
                          type: string
                        item_price:
                          description: The price of a product. Accepted as a string in the request; it will be parsed into a double. This is the original item value before any discount. We recommend using this if you are a merchant for PageVisit, AddToCart and Checkouts. For detail, please check <a href="https://help.pinterest.com/en/business/article/before-you-get-started-with-catalogs" target="_blank">here</a> (Install the Pinterest tag section).
                          example: '1325.12'
                          type: string
                        quantity:
                          description: The amount of a product. We recommend using this if you are a merchant for AddToCart and Checkouts. For detail, please check <a href="https://help.pinterest.com/en/business/article/before-you-get-started-with-catalogs" target="_blank">here</a> (Install the Pinterest tag section).
                          type: integer
                          format: int64
                          example: 5
                        item_name:
                          description: The name of a product.
                          example: pinterest-clothing-shirt
                          type: string
                        item_category:
                          description: The category of a product.
                          example: pinterest-entertainment
                          type: string
                        item_brand:
                          description: The brand of a product.
                          example: pinterest
                          type: string
                  num_items:
                    description: Total number of products of the event. For example, the total number of items purchased in a checkout event. We recommend using this if you are a merchant for AddToCart and Checkouts. For detail, please check <a href="https://help.pinterest.com/en/business/article/before-you-get-started-with-catalogs" target="_blank">here</a> (Install the Pinterest tag section).
                    type: integer
                    format: int64
                    example: 2
                  order_id:
                    description: The order ID. We recommend sending order_id to help us deduplicate events when necessary. This also helps to run other measurement products at Pinterest.
                    type: string
                    nullable: true
                    example: my_order_id
                  search_string:
                    description: The search string related to the user conversion event.
                    type: string
                    nullable: true
                    example: sample string
                  opt_out_type:
                    description: Flags for different privacy rights laws to opt out users of sharing personal information. Values should be comma separated. Please follow the <a href="https://help.pinterest.com/en/business/article/limited-data-processing" target="_blank">Help Center</a> and <a href="https://developers.pinterest.com/docs/conversions/conversion-management/#Understanding%20Limited%20Data%20Processing" target="_blank">dev site</a> for specific opt_out_type set up.
                    example: LDP
                    type: string
                    nullable: true
                  np:
                    description: Named partner. Not required, this is for Pinterest internal use only. Please do not use this unless specifically guided.
                    type: string
                    nullable: true
                    example: ss-company
              app_id:
                description: The app store app ID.
                type: string
                nullable: true
                example: '429047995'
              app_name:
                description: Name of the app.
                type: string
                nullable: true
                example: Pinterest
              app_version:
                description: Version of the app.
                type: string
                nullable: true
                example: '7.9'
              device_brand:
                description: Brand of the user device.
                type: string
                nullable: true
                example: Apple
              device_carrier:
                description: User device's mobile carrier.
                type: string
                nullable: true
                example: T-Mobile
              device_model:
                description: Model of the user device.
                type: string
                nullable: true
                example: iPhone X
              device_type:
                description: Type of the user device.
                type: string
                nullable: true
                example: iPhone
              os_version:
                description: Version of the device operating system.
                type: string
                nullable: true
                example: 12.1.4
              wifi:
                description: Whether the event occurred when the user device was connected to wifi.
                example: false
                type: boolean
              language:
                description: Two-character ISO-639-1 language code indicating the user's language.
                example: en
                type: string
                nullable: true
            required:
            - event_name
            - action_source
            - event_time
            - user_data
            - event_id
      required:
      - data
    ConversionEventsUserData:
      description: Object containing customer information data. Note, It is required at least one of 1) em, 2) hashed_maids or 3) pair client_ip_address + client_user_agent.
      type: object
      anyOf:
      - properties:
          em:
            description: Sha256 hashes of lowercase version of user's email addresses. Used for matching. We highly recommend this on checkout events at least. It may improve reporting performance such as ROAS/CPA.
            type: array
            items:
              type: string
            example:
            - 411e44ce1261728ffd2c0686e44e3fffe413c0e2c5adc498bc7da883d476b9c8
            - 09831ea51bd1b7b32a836683a00a9ccaf3d05f59499f42d9883412ed79289969
          hashed_maids:
            description: Sha256 hashes of user's "Google Advertising IDs" (GAIDs) or "Apple's Identifier for Advertisers" (IDFAs). Used for matching. We highly recommend this on checkout events at least. It may improve reporting performance such as ROAS/CPA.
            type: array
            items:
              type: string
            example:
            - 0192518eb84137ccfe82c8b6322d29631dae7e28ed9d0f6dd5f245d73a58c5f1
            - 837b850ac46d62b2272a71de73c27801ff011ac1e36c5432620c8755cf90db46
          client_ip_address:
            description: The user's IP address, which can be either in IPv4 or IPv6 format. Used for matching. We highly recommend this for all events. It may improve reporting performance such as ROAS/CPA.
            type: string
            example: 216.3.128.12
          client_user_agent:
            description: The user agent string of the user's web browser. We highly recommend this for all events. It may improve reporting performance such as ROAS/CPA.
            type: string
            example: Mozilla/5.0 (Macintosh; Intel Mac OS X 10_13_6) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/67.0.3396.87 Safari/537.36
        required:
        - em
      - properties:
          em:
            description: Sha256 hashes of lowercase version of user's email addresses. Used for matching. We highly recommend this on checkout events at least. It may improve reporting performance such as ROAS/CPA.
            type: array
            items:
              type: string
            example:
            - 411e44ce1261728ffd2c0686e44e3fffe413c0e2c5adc498bc7da883d476b9c8
            - 09831ea51bd1b7b32a836683a00a9ccaf3d05f59499f42d9883412ed79289969
          hashed_maids:
            description: Sha256 hashes of user's "Google Advertising IDs" (GAIDs) or "Apple's Identifier for Advertisers" (IDFAs). Used for matching. We highly recommend this on checkout events at least. It may improve reporting performance such as ROAS/CPA.
            type: array
            items:
              type: string
            example:
            - 0192518eb84137ccfe82c8b6322d29631dae7e28ed9d0f6dd5f245d73a58c5f1
            - 837b850ac46d62b2272a71de73c27801ff011ac1e36c5432620c8755cf90db46
          client_ip_address:
            description: The user's IP address, which can be either in IPv4 or IPv6 format. Used for matching. We highly recommend this for all events. It may improve reporting performance such as ROAS/CPA.
            type: string
            example: 216.3.128.12
          client_user_agent:
            description: The user agent string of the user's web browser. We highly recommend this for all events. It may improve reporting performance such as ROAS/CPA.
            type: string
            example: Mozilla/5.0 (Macintosh; Intel Mac OS X 10_13_6) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/67.0.3396.87 Safari/537.36
        required:
        - hashed_maids
      - properties:
          em:
            description: Sha256 hashes of lowercase version of user's email addresses. Used for matching. We highly recommend this on checkout events at least. It may improve reporting performance such as ROAS/CPA.
            type: array
            items:
              type: string
            example:
            - 411e44ce1261728ffd2c0686e44e3fffe413c0e2c5adc498bc7da883d476b9c8
            - 09831ea51bd1b7b32a836683a00a9ccaf3d05f59499f42d9883412ed79289969
          hashed_maids:
            description: Sha256 hashes of user's "Google Advertising IDs" (GAIDs) or "Apple's Identifier for Advertisers" (IDFAs). Used for matching. We highly recommend this on checkout events at least. It may improve reporting performance such as ROAS/CPA.
            type: array
            items:
              type: string
            example:
            - 0192518eb84137ccfe82c8b6322d29631dae7e28ed9d0f6dd5f245d73a58c5f1
            - 837b850ac46d62b2272a71de73c27801ff011ac1e36c5432620c8755cf90db46
          client_ip_address:
            description: The user's IP address, which can be either in IPv4 or IPv6 format. Used for matching. We highly recommend this for all events. It may improve reporting performance such as ROAS/CPA.
            type: string
            example: 216.3.128.12
          client_user_agent:
            description: The user agent string of the user's web browser. We highly recommend this for all events. It may improve reporting performance such as ROAS/CPA.
            type: string
            example: Mozilla/5.0 (Macintosh; Intel Mac OS X 10_13_6) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/67.0.3396.87 Safari/537.36
        required:
        - client_ip_address
        - client_user_agent
      properties:
        ph:
          description: Sha256 hashes of user's phone numbers, only digits with country code, area code, and number. Remove any symbols, letters, spaces and leading zeros. We highly recommend this on checkout events at least. It may improve reporting performance such as ROAS/CPA.
          type: array
          items:
            type: string
          example:
          - 45df139772a81b6011bdc1c9cc3d1cb408fc0b10ec0c5cb9d4d4e107f0ddc49d
        ge:
          description: Sha256 hashes of user's gender, in lowercase. Either "f" or "m" or "n" for non-binary gender.
          type: array
          items:
            type: string
          example:
          - 0d248e82c62c9386878327d491c762a002152d42ab2c391a31c44d9f62675ddf
        db:
          description: Sha256 hashes of user's date of birthday, given as year, month, and day.
          type: array
          items:
            type: string
          example:
          - d4426a0086d10f12ad265539ae8d54221dc67786053d511407204b76e99d7739
        ln:
          description: Sha256 hashes of user's last name, in lowercase. We highly recommend this on checkout events at least. It may improve reporting performance such as ROAS/CPA.
          type: array
          items:
            type: string
          example:
          - 7e546b3aa43f989dd359672e6c3409d4f9d4e8f155ae1e9b90ee060985468c19
        fn:
          description: Sha256 hashes of user's first name, in lowercase. We highly recommend this on checkout events at least. It may improve reporting performance such as ROAS/CPA.
          type: array
          items:
            type: string
          example:
          - ec1e6a072231703f1bc41429052fff8c00a7e0c6aaec2e7107241ca8f3ceb6b2
        ct:
          description: Sha256 hashes of user's city, in lowercase, and without spaces or punctuation. User residency city (mostly billing).
          type: array
          items:
            type: string
          example:
          - 4ac01a129bfd10385c9278c2cf2c46fac5ab57350841234f587c8522a2e4ce36
        st:
          description: Sha256 hashes of user's state, given as a two-letter code in lowercase. User residency state (mostly billing).
          type: array
          items:
            type: string
          example:
          - 49a6d05b8e4b516656e464271d9dd38d0a7e0142f7f49546f4dabd2720cafc34
        zp:
          description: Sha256 hashes of user's zipcode, only digits. User residency zipcode (mostly billing).
          type: array
          items:
            type: string
          example:
          - fd5f56b40a79a385708428e7b32ab996a681080a166a2206e750eb4819186145
        country:
          description: Sha256 hashes of two-character ISO-3166 country code indicating the user's country, in lowercase.
          type: array
          items:
            type: string
          example:
          - 9b202ecbc6d45c6d8901d989a918878397a3eb9d00e8f48022fc051b19d21a1d
        external_id:
          description: Sha256 hashes of the unique id from the advertiser that identifies a user in their space, e.g. user id, loyalty id, etc. We highly recommend this on all events. It may improve reporting performance such as ROAS/CPA.
          type: array
          items:
            type: string
          example:
          - 6a7a73766627eb611720883d5a11cc62b5bfee237b00a6658d78c50032ec4aee
        click_id:
          description: The unique identifier stored in _epik cookie on your domain or &epik= query parameter in the URL. We highly recommend this on checkout events at least. It may improve reporting performance such as ROAS/CPA.
          type: string
          example: dj0yJnU9b2JDcFFHekV4SHJNcmVrbFBkUEdqakh0akdUT1VjVVUmcD0yJm49cnNBQ3F2Q2dOVDBXWWhkWklrUGxBUSZ0PUFBQUFBR1BaY3Bv
          nullable: true
        partner_id:
          description: A unique identifier of visitors' information defined by third party partners. e.g RampID
          type: string
          example: BUJrTlRRzGJmWhRXFZdkioV6wKPBve7Lom__GU9J74hq2NIQj4O3nOZJrp3mcUr5MptkXsI14juMOIM9mNZnM4zEUFT2JLVaFhcOfuuWz3IWEDtBf6I0DPc
          nullable: true
    Error:
      title: Error
      type: object
      properties:
        code:
          type: integer
        message:
          type: string
      required:
      - code
      - message
    ConversionApiResponse:
      description: Schema describing the object in the response, which contains information about the events that were received and processed.
      type: object
      properties:
        num_events_received:
          description: Total number of events received in the request.
          type: integer
        num_events_processed:
          description: Number of events that were successfully processed from the events.
          type: integer
        events:
          description: Specific messages for each event received. The order will match the order in which the events were received in the request.
          type: array
          items:
            type: object
            properties:
              status:
                description: Whether the event was processed successfully.
                type: string
                example: processed
                enum:
                - failed
                - processed
              error_message:
                description: Error message containing more information about why the event failed to be processed.
                type: string
                nullable: true
              warning_message:
                description: Warning messages about any fields in the event which are not standard. These are not critical to event processing.
                type: string
                nullable: true
            required:
            - status
      required:
      - num_events_received
      - num_events_processed
      - events
  parameters:
    path_ad_account_id:
      name: ad_account_id
      description: Unique identifier of an ad account.
      in: path
      required: true
      schema:
        type: string
        pattern: ^\d+$
        maxLength: 18
  securitySchemes:
    pinterest_oauth2:
      type: oauth2
      flows:
        authorizationCode:
          authorizationUrl: https://www.pinterest.com/oauth/
          tokenUrl: https://api.pinterest.com/v5/oauth/token
          scopes:
            ads:read: See all of your advertising data, including ads, ad groups, campaigns etc.
            ads:write: Create, update, or delete ads, ad groups, campaigns etc.
            billing:read: See all of your billing data, billing profile, etc.
            billing:write: Create, update, or delete billing data, billing profiles, etc.
            biz_access:read: See business access data
            biz_access:write: Create, update, or delete business access data
            boards:read: See your public boards, including group boards you join
            boards:read_secret: See your secret boards
            boards:write: Create, update, or delete your public boards
            boards:write_secret: Create, update, or delete your secret boards
            catalogs:read: See all of your catalogs data
            catalogs:write: Create, update, or delete your catalogs data
            pins:read: See your public Pins
            pins:read_secret: See your secret Pins
            pins:write: Create, update, or delete your public Pins
            pins:write_secret: Create, update, or delete your secret Pins
            user_accounts:read: See your user accounts and followers
            user_accounts:write: Update your user accounts and followers
    conversion_token:
      type: http
      scheme: bearer
      description: This security scheme only applies to the conversion events endpoint (POST /ad_accounts/{ad_account_id}/events). This endpoint requires a bearer token generated via Ads Manager (ads.pinterest.com).
    basic:
      type: http
      scheme: basic
x-tagGroups:
- name: Pin and Boards
  tags:
  - pins
  - boards
  - media
  - aggregated_comments
  - aggregated_pin_data
  - user_account
- name: Campaign Management
  tags:
  - ad_accounts
  - campaigns
  - ad_groups
  - ads
  - product_group_promotions
  - bulk
- name: Targeting
  tags:
  - audiences
  - customer_lists
  - keywords
  - targeting_template
  - audience_insights
  - audience_sharing
- name: Ad Formats
  tags:
  - lead_forms
  - lead_ads
  - leads_export
- name: Billing
  tags:
  - billing
  - order_lines
  - terms_of_service
- name: Business Access
  tags:
  - business_access_assets
  - business_access_invite
  - business_access_relationships
- name: Conversions
  tags:
  - conversion_events
  - conversion_tags
- name: Others
  tags:
  - integrations
  - oauth
  - resources
  - search
  - terms
- name: Shopping
  tags:
  - catalogs
- name: Deprecated
  tags:
  - product_groups