openapi: 3.0.3
info:
  version: 5.13.0
  title: Pinterest Resources 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: Resources
paths:
  /resources/ad_account_countries:
    get:
      summary: Get ad accounts countries
      description: Get Ad Accounts countries
      operationId: ad_account_countries/get
      security:
      - pinterest_oauth2:
        - ads:read
      x-ratelimit-category: ads_read
      x-sandbox: enabled
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AdAccountsCountryResponse'
          description: Success
        default:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unexpected error
      tags:
      - Resources
  /resources/delivery_metrics:
    get:
      summary: Get available metrics' definitions
      description: 'Get the definitions for ads and organic metrics available across both synchronous and asynchronous report endpoints.

        The `display_name` attribute will match how the metric is named in our native tools like Ads Manager.

        See <a href=''/docs/content/analytics/''>Organic Analytics</a> and <a href=''/docs/ads/ad-analytics-reporting/''>Ads Analytics</a> for more information.'
      operationId: delivery_metrics/get
      security:
      - pinterest_oauth2:
        - ads:read
        - pins:read
        - user_accounts:read
      x-ratelimit-category: ads_read
      x-sandbox: enabled
      parameters:
      - $ref: '#/components/parameters/query_report_type'
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeliveryMetricsResponse'
          description: Success
        default:
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      tags:
      - Resources
  /resources/lead_form_questions:
    get:
      summary: Get lead form questions
      description: 'Get a list of all lead form question type names. Some questions might not be used.


        <strong>This endpoint is currently in beta and not available to all apps. <a href=''/docs/new/about-beta-access/''>Learn more</a>.</strong>'
      operationId: lead_form_questions/get
      security:
      - pinterest_oauth2:
        - ads:read
      x-ratelimit-category: ads_read
      x-sandbox: enabled
      responses:
        '200':
          description: Success
        default:
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      tags:
      - Resources
  /resources/metrics_ready_state:
    get:
      summary: Get metrics ready state
      description: Learn whether conversion or non-conversion metrics are finalized and ready to query.
      operationId: metrics_ready_state/get
      security:
      - pinterest_oauth2:
        - ads:read
      x-ratelimit-category: ads_analytics
      x-sandbox: enabled
      parameters:
      - name: date
        description: 'Analytics reports request date (UTC). Format: YYYY-MM-DD'
        in: query
        required: true
        style: form
        schema:
          type: string
          pattern: ^(\d{4})-(\d{2})-(\d{2})$
          example: '2022-07-13'
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BookClosedResponse'
          description: Success
        default:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unexpected error
      tags:
      - Resources
  /resources/targeting/interests/{interest_id}:
    get:
      summary: Get interest details
      description: <p>Get details of a specific interest given interest ID.</p> <p>Click <a href="https://docs.google.com/spreadsheets/d/1HxL-0Z3p2fgxis9YBP2HWC3tvPrs1hAuHDRtH-NJTIM/edit#gid=118370875" target="_blank">here</a> for a spreadsheet listing interests and their IDs.</p>
      operationId: interest_targeting_options/get
      security:
      - pinterest_oauth2:
        - ads:read
      x-ratelimit-category: ads_read
      x-sandbox: enabled
      parameters:
      - $ref: '#/components/parameters/path_interest_id'
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SingleInterestTargetingOptionResponse'
          description: Success
        default:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unexpected error
      tags:
      - Resources
  /resources/targeting/{targeting_type}:
    get:
      summary: Get targeting options
      description: '<p>You can use targeting values in ads placement to define your intended audience. </p> <p>Targeting metrics are organized around targeting specifications.</p> <p>For more information on ads targeting, see <a class="reference external" href="https://help.pinterest.com/en/business/article/audience-targeting" target="_blank">Audience targeting</a>.</p>

        <p><b>Sample return:</b></p> <pre class="literal-block"> [{&quot;36313&quot;: &quot;Australia: Moreton Bay - North&quot;, &quot;124735&quot;: &quot;Canada: North Battleford&quot;, &quot;36109&quot;: &quot;Australia: Murray&quot;, &quot;36108&quot;: &quot;Australia: Mid North Coast&quot;, &quot;36101&quot;: &quot;Australia: Capital Region&quot;, &quot;811&quot;: &quot;U.S.: Reno&quot;, &quot;36103&quot;: &quot;Australia: Central West&quot;, &quot;36102&quot;: &quot;Australia: Central Coast&quot;, &quot;36105&quot;: &quot;Australia: Far West and Orana&quot;, &quot;36104&quot;: &quot;Australia: Coffs Harbour - Grafton&quot;, &quot;36107&quot;: &quot;Australia: Illawarra&quot;, &quot;36106&quot;: &quot;Australia: Hunter Valley Exc Newcastle&quot;, &quot;554017&quot;: &quot;New Zealand: Wanganui&quot;, &quot;554016&quot;: &quot;New Zealand: Marlborough&quot;, &quot;554015&quot;: &quot;New Zealand: Gisborne&quot;, &quot;554014&quot;: &quot;New Zealand: Tararua&quot;, &quot;554013&quot;: &quot;New Zealand: Invercargill&quot;, &quot;GR&quot;: &quot;Greece&quot;, &quot;554011&quot;: &quot;New Zealand: Whangarei&quot;, &quot;554010&quot;: &quot;New Zealand: Far North&quot;, &quot;717&quot;: &quot;U.S.: Quincy-Hannibal-Keokuk&quot;, &quot;716&quot;: &quot;U.S.: Baton Rouge&quot;,...}] </pre>'
      operationId: targeting_options/get
      security:
      - pinterest_oauth2:
        - ads:read
      x-ratelimit-category: ads_read
      x-sandbox: enabled
      parameters:
      - $ref: '#/components/parameters/path_targeting_type'
      - $ref: '#/components/parameters/query_client_id'
      - $ref: '#/components/parameters/query_oauth_signature'
      - $ref: '#/components/parameters/query_timestamp'
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TargetingOptionResponse'
          description: Success
        default:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unexpected error
      tags:
      - Resources
components:
  schemas:
    TargetingOptionResponse:
      title: TargetingOptionResponse
      type: array
      nullable: true
      items:
        type: object
        example:
          '36313': 'Australia: Moreton Bay - North'
          '124735': 'Canada: North Battleford'
    BookClosedResponse:
      title: BookClosed
      description: Creation fields
      type: object
      properties:
        conversion_metrics_ready:
          title: conversion_metrics_ready
          description: Are conversion metrics ready?
          type: boolean
          example: false
        non_conversion_metrics_ready:
          title: non_conversion_metrics_ready
          description: Are non-conversion metrics ready?
          type: boolean
          example: false
    AdAccountsCountryResponse:
      type: object
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/AdAccountsCountryResponseData'
    SingleInterestTargetingOptionResponse:
      title: SingleInterestTargetingOptionData
      type: object
      properties:
        id:
          type: string
          title: id
          pattern: \d+
          example: '945391946569'
        name:
          type: string
          title: name
          example: Dress
        child_interests:
          type: array
          title: child_interests
          items:
            type: string
        level:
          type: integer
          title: level
          example: 2
    Error:
      title: Error
      type: object
      properties:
        code:
          type: integer
        message:
          type: string
      required:
      - code
      - message
    DeliveryMetricsResponse:
      type: object
      properties:
        items:
          type: array
          items:
            type: object
            properties:
              name:
                type: string
                description: Metric's name.
                example: AD_GROUP_ID
              category:
                enum:
                - ADS
                - ORGANIC
                description: Category name
                example: ADS
              definition:
                type: string
                description: How the metric is defined.
                example: Unique ID for your ad group
              display_name:
                type: string
                description: Display name, when available. If unavaible it will not be returned. Matches how the metric is named in our native tools like Pinterest Ads Manager.
                example: Ad group ID
    AdCountry:
      type: string
      description: Country ID from ISO 3166-1 alpha-2.
      example: US
      enum:
      - AD
      - AE
      - AF
      - AG
      - AI
      - AL
      - AM
      - AO
      - AQ
      - AR
      - AS
      - AT
      - AU
      - AW
      - AX
      - AZ
      - BA
      - BB
      - BD
      - BE
      - BF
      - BG
      - BH
      - BI
      - BJ
      - BL
      - BM
      - BN
      - BO
      - BQ
      - BR
      - BS
      - BT
      - BV
      - BW
      - BY
      - BZ
      - CA
      - CC
      - CD
      - CF
      - CG
      - CH
      - CI
      - CK
      - CL
      - CM
      - CN
      - CO
      - CR
      - CU
      - CV
      - CW
      - CX
      - CY
      - CZ
      - DE
      - DJ
      - DK
      - DM
      - DO
      - DZ
      - EC
      - EE
      - EG
      - EH
      - ER
      - ES
      - ET
      - FI
      - FJ
      - FK
      - FM
      - FO
      - FR
      - GA
      - GB
      - GD
      - GE
      - GF
      - GG
      - GH
      - GI
      - GL
      - GM
      - GN
      - GP
      - GQ
      - GR
      - GS
      - GT
      - GU
      - GW
      - GY
      - HK
      - HM
      - HN
      - HR
      - HT
      - HU
      - ID
      - IE
      - IL
      - IM
      - IN
      - IO
      - IQ
      - IR
      - IS
      - IT
      - JE
      - JM
      - JO
      - JP
      - KE
      - KG
      - KH
      - KI
      - KM
      - KN
      - KR
      - KW
      - KY
      - KZ
      - LA
      - LB
      - LC
      - LI
      - LK
      - LR
      - LS
      - LT
      - LU
      - LV
      - LY
      - MA
      - MC
      - MD
      - ME
      - MF
      - MG
      - MH
      - MK
      - ML
      - MM
      - MN
      - MO
      - MP
      - MQ
      - MR
      - MS
      - MT
      - MU
      - MV
      - MW
      - MX
      - MY
      - MZ
      - NA
      - NC
      - NE
      - NF
      - NG
      - NI
      - NL
      - 'NO'
      - NP
      - NR
      - NU
      - NZ
      - OM
      - PA
      - PE
      - PF
      - PG
      - PH
      - PK
      - PL
      - PM
      - PN
      - PR
      - PS
      - PT
      - PW
      - PY
      - QA
      - RE
      - RO
      - RS
      - RU
      - RW
      - SA
      - SB
      - SC
      - SD
      - SE
      - SG
      - SH
      - SI
      - SJ
      - SK
      - SL
      - SM
      - SN
      - SO
      - SR
      - SS
      - ST
      - SV
      - SX
      - SY
      - SZ
      - TC
      - TD
      - TF
      - TG
      - TH
      - TJ
      - TK
      - TL
      - TM
      - TN
      - TO
      - TR
      - TT
      - TV
      - TW
      - TZ
      - UA
      - UG
      - UM
      - US
      - UY
      - UZ
      - VA
      - VC
      - VE
      - VG
      - VI
      - VN
      - VU
      - WF
      - WS
      - YE
      - YT
      - ZA
      - ZM
      - ZW
    AdAccountsCountryResponseData:
      type: object
      properties:
        code:
          $ref: '#/components/schemas/AdCountry'
          type: string
        currency:
          description: Country currency.
          example: Dollars
          type: string
        index:
          type: number
          description: Country index
          example: 1
        name:
          type: string
          description: Country name
          example: United States of America
  parameters:
    query_timestamp:
      name: timestamp
      description: Timestamp
      in: query
      required: false
      schema:
        type: string
        example: '1618338184277'
        pattern: \d+
      style: form
    path_interest_id:
      name: interest_id
      description: Unique identifier of an interest.
      in: path
      required: true
      schema:
        type: string
        pattern: ^\d+$
        maxLength: 18
    query_client_id:
      name: client_id
      description: Client ID.
      in: query
      required: false
      schema:
        type: string
        pattern: ^\d+$
        maxLength: 18
        example: '1094834'
      style: form
    query_oauth_signature:
      name: oauth_signature
      description: Oauth signature
      in: query
      required: false
      schema:
        type: string
        example: 8209f
      style: form
    path_targeting_type:
      name: targeting_type
      description: Public targeting type.
      in: path
      required: true
      style: simple
      schema:
        title: PublicTargetingType
        description: Public ad targeting type with external names
        type: string
        example: APPTYPE
        enum:
        - APPTYPE
        - GENDER
        - LOCALE
        - AGE_BUCKET
        - LOCATION
        - GEO
        - INTEREST
        - KEYWORD
        - AUDIENCE_INCLUDE
        - AUDIENCE_EXCLUDE
    query_report_type:
      name: report_type
      description: Report type.
      in: query
      required: false
      schema:
        type: string
        enum:
        - SYNC
        - ASYNC
  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