Pinterest Ads API

openapi: 3.2.0
info:
  version: 5.13.0
  title: Pinterest Ads 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: Ads
paths:
  /ad_accounts/{ad_account_id}/ad_previews:
    post:
      summary: Create ad preview with pin or image
      description: 'Create an ad preview given an ad account ID and either an existing organic pin ID or the URL for an image to be used to create the Pin and the ad. <p/>

        If you are creating a preview from an existing Pin, that Pin must be promotable: that is, it must have a clickthrough link and meet other requirements. (See <a href="https://help.pinterest.com/en/business/article/promoted-pins-overview" target="_blank">Ads Overview</a>.) <p/>

        You can view the returned preview URL on a webpage or iframe for 7 days, after which the URL expires. Collection ads are not currently supported ad preview.'
      tags:
      - Ads
      operationId: ad_previews/create
      security:
      - pinterest_oauth2:
        - ads:write
      x-ratelimit-category: ads_write
      x-sandbox: enabled
      parameters:
      - $ref: '#/components/parameters/path_ad_account_id'
      requestBody:
        description: Create ad preview with pin or image.
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AdPreviewRequest'
      responses:
        '200':
          description: Successful ad preview creation.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AdPreviewURLResponse'
        '400':
          description: Invalid Pin parameters response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                InvalidPinUrl:
                  value:
                    code: 1
                    message: Whoops! It looks like you entered an invalid URL. Try creating a Pin again with a valid URL.
        default:
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /ad_accounts/{ad_account_id}/ads:
    get:
      summary: List ads
      description: "List ads that meet the filters provided:\n  - Listed campaign ids or ad group ids or ad ids\n  - Listed entity statuses <p/>\nIf no filter is provided, all ads in the ad account are returned. <p/>\n<strong>Note:</strong><p/>\nProvide only campaign_id or ad_group_id or ad_id. Do not provide more than one type. <p/>\nReview status is provided for each ad; if review_status is REJECTED, the rejected_reasons field will contain additional information.\nFor more, see <a href=\"https://policy.pinterest.com/en/advertising-guidelines\">Pinterest advertising standards</a>."
      operationId: ads/list
      security:
      - pinterest_oauth2:
        - ads:read
      x-ratelimit-category: ads_read
      x-sandbox: enabled
      parameters:
      - $ref: '#/components/parameters/path_ad_account_id'
      - $ref: '#/components/parameters/query_campaign_ids'
      - $ref: '#/components/parameters/query_ad_group_ids'
      - $ref: '#/components/parameters/query_ad_ids'
      - $ref: '#/components/parameters/query_entity_statuses'
      - $ref: '#/components/parameters/query_page_size'
      - $ref: '#/components/parameters/query_order'
      - $ref: '#/components/parameters/query_bookmark'
      responses:
        '200':
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/Paginated'
                - type: object
                  properties:
                    items:
                      type: array
                      items:
                        $ref: '#/components/schemas/AdResponse'
          description: Success
        '400':
          description: Invalid ad account ads parameters.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                code: 400
                message: Invalid ad account ads parameters.
        default:
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      tags:
      - Ads
    post:
      description: Create multiple new ads. Request must contain ad_group_id, creative_type, and the source Pin pin_id.
      operationId: ads/create
      security:
      - pinterest_oauth2:
        - ads:write
      x-ratelimit-category: ads_write
      x-sandbox: enabled
      parameters:
      - $ref: '#/components/parameters/path_ad_account_id'
      requestBody:
        content:
          application/json:
            schema:
              items:
                $ref: '#/components/schemas/AdCreateRequest'
              maxItems: 30
              minItems: 1
              type: array
        description: List of ads to create, size limit [1, 30].
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AdArrayResponse'
          description: Success
        default:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unexpected error
      summary: Create ads
      tags:
      - Ads
    patch:
      description: Update multiple existing ads
      operationId: ads/update
      security:
      - pinterest_oauth2:
        - ads:write
      x-ratelimit-category: ads_write
      x-sandbox: enabled
      parameters:
      - $ref: '#/components/parameters/path_ad_account_id'
      requestBody:
        content:
          application/json:
            schema:
              items:
                $ref: '#/components/schemas/AdUpdateRequest'
              maxItems: 30
              minItems: 1
              type: array
        description: List of ads to update, size limit [1, 30]
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AdArrayResponse'
          description: Success
        default:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unexpected error
      summary: Update ads
      tags:
      - Ads
  /ad_accounts/{ad_account_id}/ads/analytics:
    get:
      summary: Get ad analytics
      description: 'Get analytics for the specified ads in the specified <code>ad_account_id</code>, filtered by the specified options.

        - The token''s user_account 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, Campaign Manager.

        - If granularity is not HOUR, the furthest back you can are allowed to pull data is 90 days before the current date in UTC time and the max time range supported is 90 days.

        - If granularity is HOUR, the furthest back you can are allowed to pull data is 8 days before the current date in UTC time and the max time range supported is 3 days.'
      operationId: ads/analytics
      security:
      - pinterest_oauth2:
        - ads:read
      x-ratelimit-category: ads_analytics
      x-sandbox: enabled
      parameters:
      - $ref: '#/components/parameters/path_ad_account_id'
      - $ref: '#/components/parameters/query_start_date'
      - $ref: '#/components/parameters/query_end_date'
      - $ref: '#/components/parameters/query_ad_ids_required'
      - $ref: '#/components/parameters/query_columns'
      - $ref: '#/components/parameters/query_granularity'
      - $ref: '#/components/parameters/query_conversion_attribution_click_window_days'
      - $ref: '#/components/parameters/query_conversion_attribution_engagement_window_days'
      - $ref: '#/components/parameters/query_conversion_attribution_view_window_days'
      - $ref: '#/components/parameters/query_conversion_attribution_conversion_report_time'
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AdsAnalyticsResponse'
          description: Success
        '400':
          description: Invalid ad account ads analytics parameters.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                code: 400
                message: Invalid ad account ads analytics parameters.
        default:
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      tags:
      - Ads
  /ad_accounts/{ad_account_id}/ads_credit/discounts:
    get:
      summary: Get ads credit discounts
      description: 'Returns the list of discounts applied to the account.


        <strong>This endpoint might not be available to all apps. <a href=''/docs/new/about-beta-access/''>Learn more</a>.</strong>'
      operationId: ads_credits_discounts/get
      security:
      - pinterest_oauth2:
        - ads:read
        - billing:read
      x-ratelimit-category: ads_read
      x-sandbox: disabled
      tags:
      - Ads
      parameters:
      - $ref: '#/components/parameters/path_ad_account_id'
      - $ref: '#/components/parameters/query_bookmark'
      - $ref: '#/components/parameters/query_page_size'
      responses:
        '200':
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/Paginated'
                - type: object
                  properties:
                    items:
                      type: array
                      items:
                        $ref: '#/components/schemas/AdsCreditDiscountsResponse'
          description: Success
        default:
          description: Unexpected error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /ad_accounts/{ad_account_id}/ads_credit/redeem:
    post:
      summary: Redeem ad credits
      description: 'Redeem ads credit on behalf of the ad account id and apply it towards billing.


        <strong>This endpoint might not be available to all apps. <a href=''/docs/new/about-beta-access/''>Learn more</a>.</strong>'
      tags:
      - Ads
      operationId: ads_credit/redeem
      security:
      - pinterest_oauth2:
        - ads:write
        - billing:write
      x-ratelimit-category: ads_write
      x-sandbox: disabled
      parameters:
      - $ref: '#/components/parameters/path_ad_account_id'
      requestBody:
        description: Redeem ad credits request.
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AdsCreditRedeemRequest'
      responses:
        '200':
          description: Successfully redeemed ad credits.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AdsCreditRedeemResponse'
        '400':
          description: Error thrown when unable to redeem offer code.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                ValidationError:
                  value:
                    code: 15
                    message: Unable to redeem offer code. Try again later.
        default:
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /ad_accounts/{ad_account_id}/ads/targeting_analytics:
    get:
      summary: Get targeting analytics for ads
      description: 'Get targeting analytics for one or more ads. For the requested ad(s) and metrics,

        the response will include the requested metric information (e.g. SPEND_IN_DOLLAR) for the requested target type

        (e.g. "age_bucket") for applicable values (e.g. "45-49"). <p/>

        - The token''s user_account 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, Campaign Manager.

        - If granularity is not HOUR, the furthest back you can are allowed to pull data is 90 days before the current date in UTC time and the max time range supported is 90 days.

        - If granularity is HOUR, the furthest back you can are allowed to pull data is 8 days before the current date in UTC time and the max time range supported is 3 days.'
      operationId: ad_targeting_analytics/get
      security:
      - pinterest_oauth2:
        - ads:read
      x-ratelimit-category: ads_analytics
      x-sandbox: enabled
      parameters:
      - $ref: '#/components/parameters/path_ad_account_id'
      - $ref: '#/components/parameters/query_ad_ids_required'
      - $ref: '#/components/parameters/query_start_date'
      - $ref: '#/components/parameters/query_end_date'
      - $ref: '#/components/parameters/query_targeting_types'
      - $ref: '#/components/parameters/query_columns'
      - $ref: '#/components/parameters/query_granularity'
      - $ref: '#/components/parameters/query_conversion_attribution_click_window_days'
      - $ref: '#/components/parameters/query_conversion_attribution_engagement_window_days'
      - $ref: '#/components/parameters/query_conversion_attribution_view_window_days'
      - $ref: '#/components/parameters/query_conversion_attribution_conversion_report_time'
      - $ref: '#/components/parameters/query_attribution_types'
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MetricsResponse'
          description: Success
        default:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unexpected error
      tags:
      - Ads
  /ad_accounts/{ad_account_id}/ads/{ad_id}:
    get:
      summary: Get ad
      description: 'Get a specific ad given the ad ID. If your pin is rejected, rejected_reasons will

        contain additional information from the Ad Review process.

        For more information about our policies and rejection reasons see the <a href="https://www.pinterest.com/_/_/policy/advertising-guidelines/"

        target="_blank">Pinterest advertising standards</a>.'
      operationId: ads/get
      security:
      - pinterest_oauth2:
        - ads:read
      x-ratelimit-category: ads_read
      x-sandbox: enabled
      parameters:
      - $ref: '#/components/parameters/path_ad_account_id'
      - $ref: '#/components/parameters/path_ad_id'
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AdResponse'
          description: Success
        default:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unexpected error
      tags:
      - Ads
components:
  schemas:
    QuizPinResult:
      description: The result, and link out, based on the users choice.
      example:
        organic_pin_id: pinId
        android_deep_link: https://www.pinterest.com/
        ios_deep_link: https://www.pinterest.com/
        destination_url: https://www.pinterest.com/
      type:
      - object
      - 'null'
      properties:
        organic_pin_id:
          type: string
        android_deep_link:
          type: string
        ios_deep_link:
          type: string
        destination_url:
          type: string
        result_id:
          type: number
    Exception:
      title: Generic exception class to be used within schemas
      type: object
      properties:
        code:
          type: integer
          example: 2
          description: Exception error code.
        message:
          type: string
          example: Advertiser not found.
          description: Exception message.
    AdsCreditDiscountsResponse:
      type: object
      properties:
        active:
          description: True if the offer code is currently active.
          type: boolean
          example: true
        advertiser_id:
          description: Advertiser ID the offer was applied to.
          type: string
          pattern: ^\d+$
          example: '12312451231'
        discountType:
          description: The type of discount of this credit
          type:
          - string
          - 'null'
          enum:
          - COUPON
          - CREDIT
          - COUPON_APPLIED
          - CREDIT_APPLIED
          - MARKETING_OFFER_CREDIT
          - MARKETING_OFFER_CREDIT_APPLIED
          - GOODWILL_CREDIT
          - GOODWILL_CREDIT_APPLIED
          - INTERNAL_CREDIT
          - INTERNAL_CREDIT_APPLIED
          - PREPAID_CREDIT
          - PREPAID_CREDIT_APPLIED
          - SALES_INCENTIVE_CREDIT
          - SALES_INCENTIVE_CREDIT_APPLIED
          - CREDIT_EXPIRED
          - FUTURE_CREDIT
          - REFERRAL_CREDIT
          - INVOICE_SALES_INCENTIVE_CREDIT
          - INVOICE_SALES_INCENTIVE_CREDIT_APPLIED
          - PREPAID_CREDIT_REFUND
          - null
        discountInMicroCurrency:
          description: The discount applied in the offers currency value.
          type:
          - number
          - 'null'
          example: 125000000
        discountCurrency:
          type:
          - string
          - 'null'
          description: Currency value for the discount.
          example: USD
        title:
          description: Human readable title of the offer code.
          type:
          - string
          - 'null'
          example: Ads Credits
        remainingDiscountInMicroCurrency:
          type:
          - number
          - 'null'
          description: The credits left to spend.
          example: 125000000
    MetricsResponse:
      properties:
        data:
          items:
            type: object
          type: array
          example:
          - targeting_type: KEYWORD
            targeting_value: christmas decor ideas
            metrics:
              AD_GROUP_ID: 2680067996745
              DATE: '2022-04-26'
              SPEND_IN_DOLLAR: 240
          - targeting_type: APPTYPE
            targeting_value: iphone
            metrics:
              AD_GROUP_ID: 2680067996745
              DATE: '2022-04-26'
              SPEND_IN_DOLLAR: 240
          - targeting_type: APPTYPE
            targeting_value: ipad
            metrics:
              AD_GROUP_ID: 2680067996745
              DATE: '2022-04-26'
              SPEND_IN_DOLLAR: 240
          - targeting_type: APPTYPE
            targeting_value: web
            metrics:
              AD_GROUP_ID: 2680067996745
              DATE: '2022-04-26'
              SPEND_IN_DOLLAR: 240
          - targeting_type: APPTYPE
            targeting_value: web_mobile
            metrics:
              AD_GROUP_ID: 2680067996745
              DATE: '2022-04-26'
              SPEND_IN_DOLLAR: 240
          - targeting_type: APPTYPE
            targeting_value: android_mobile
            metrics:
              AD_GROUP_ID: 2680067996745
              DATE: '2022-04-26'
              SPEND_IN_DOLLAR: 240
          - targeting_type: APPTYPE
            targeting_value: android_tablet
            metrics:
              AD_GROUP_ID: 2680067996745
              DATE: '2022-04-26'
              SPEND_IN_DOLLAR: 240
          - targeting_type: GENDER
            targeting_value: female
            metrics:
              AD_GROUP_ID: 2680067996745
              DATE: '2022-04-26'
              SPEND_IN_DOLLAR: 240
          - targeting_type: LOCATION
            targeting_value: 500
            metrics:
              AD_GROUP_ID: 2680067996745
              DATE: '2022-04-26'
              SPEND_IN_DOLLAR: 240
          - targeting_type: PLACEMENT
            targeting_value: SEARCH
            metrics:
              AD_GROUP_ID: 2680067996745
              DATE: '2022-04-26'
              SPEND_IN_DOLLAR: 240
          - targeting_type: COUNTRY
            targeting_value: US
            metrics:
              AD_GROUP_ID: 2680067996745
              DATE: '2022-04-26'
              SPEND_IN_DOLLAR: 240
          - targeting_type: TARGETED_INTEREST
            targeting_value: Food and Drinks
            metrics:
              AD_GROUP_ID: 2680067996745
              DATE: '2022-04-26'
              SPEND_IN_DOLLAR: 240
          - targeting_type: PINNER_INTEREST
            targeting_value: Chocolate Cookies
            metrics:
              AD_GROUP_ID: 2680067996745
              DATE: '2022-04-26'
              SPEND_IN_DOLLAR: 240
          - targeting_type: AUDIENCE_INCLUDE
            targeting_value: 254261234567
            metrics:
              AD_GROUP_ID: 2680067996745
              DATE: '2022-04-26'
              SPEND_IN_DOLLAR: 240
          - targeting_type: GEO
            targeting_value: US:94102
            metrics:
              AD_GROUP_ID: 2680067996745
              DATE: '2022-04-26'
              SPEND_IN_DOLLAR: 240
          - targeting_type: AGE_BUCKET
            targeting_value: 45-49
            metrics:
              AD_GROUP_ID: 2680067996745
              DATE: '2022-04-26'
              SPEND_IN_DOLLAR: 240
          - targeting_type: REGION
            targeting_value: US-CA
            metrics:
              AD_GROUP_ID: 2680067996745
              DATE: '2022-04-26'
              SPEND_IN_DOLLAR: 240
      type: object
    AdPreviewURLResponse:
      example:
        url: https://ads.pinterest.com/ad-preview/58f1a0e9ab0bd0f99462a0e4c5dd7e8297888c8a36331e88f757abe8f0295d31/
      properties:
        url:
          description: '''Preview URL, expires in 7 days. Can be used in an iframe.

            For example: https://ads.pinterest.com/ad-preview/74667c814dd2b19/

            The preview object ID/key is the last param - 74667c814dd2b19'''
          example: https://ads.pinterest.com/ad-preview/58f1a0e9ab0bd0f99462a0e4c5dd7e8297888c8a36331e88f757abe8f0295d31/
          title: url
          type: string
      title: AdPreviewURLResponse
      type: object
    AdArrayResponse:
      type: object
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/AdArrayResponseElement'
      title: AdArrayResponse
    ConversionReportAttributionType:
      type: string
      description: Attribution type. Refers to the Pinterest Tag endpoints
      example: INDIVIDUAL
      enum:
      - INDIVIDUAL
      - HOUSEHOLD
    Paginated:
      type: object
      properties:
        items:
          type: array
          items:
            type: object
        bookmark:
          type:
          - string
          - 'null'
      required:
      - items
    AdPinId:
      type: object
      properties:
        pin_id:
          description: Pin ID.
          example: '394205773611545468'
          type: string
          pattern: ^\d+$
    AdsCreditRedeemResponse:
      type: object
      properties:
        success:
          description: Returns true if the offer code was successfully applied(validateOnly=false) or can be applied(validateOnly=true).
          type: boolean
          example: false
        errorCode:
          description: Error code type if error occurs
          type:
          - integer
          - 'null'
          example: 2708
        errorMessage:
          description: Reason for failure
          type:
          - string
          - 'null'
          example: The offer has already been redeemed by this advertiser
    AdsAnalyticsResponse:
      type: array
      items:
        type: object
        properties:
          AD_ID:
            description: The ID of the ad that this metrics belongs to.
            type: string
            pattern: ^\d+$
          DATE:
            description: Current metrics date. Only returned when granularity is a time-based value (`DAY`, `HOUR`, `WEEK`, `MONTH`)
            type: string
            format: date
        required:
        - AD_ID
        additionalProperties: true
        example:
          DATE: '2021-04-01'
          AD_ID: '547602124502'
          SPEND_IN_DOLLAR: 30
          TOTAL_CLICKTHROUGH: 216
    AdsAnalyticsTargetingType:
      type: string
      description: Reporting targeting type
      example: APPTYPE
      enum:
      - KEYWORD
      - APPTYPE
      - GENDER
      - LOCATION
      - PLACEMENT
      - COUNTRY
      - TARGETED_INTEREST
      - PINNER_INTEREST
      - AUDIENCE_INCLUDE
      - GEO
      - AGE_BUCKET
      - REGION
      - AGE_BUCKET_AND_GENDER
    Granularity:
      type: string
      description: Granularity
      enum:
      - TOTAL
      - DAY
      - HOUR
      - WEEK
      - MONTH
    AdResponse:
      type: object
      allOf:
      - $ref: '#/components/schemas/AdCommon'
      - $ref: '#/components/schemas/AdPinId'
      - type: object
        properties:
          ad_account_id:
            description: The ID of the advertiser that this ad belongs to.
            example: '549755885175'
            type: string
            pattern: ^\d+$
          campaign_id:
            description: ID of the ad campaign that contains this ad.
            example: '626735565838'
            type: string
            pattern: ^\d+$
          collection_items_destination_url_template:
            description: Destination URL template for all items within a collections drawer.
            type:
            - string
            - 'null'
          created_time:
            description: Pin creation time. Unix timestamp in seconds.
            example: 1451431341
            type: integer
          id:
            description: The ID of this ad.
            example: '687195134316'
            type: string
            pattern: ^\d+$
          rejected_reasons:
            description: Enum reason why the pin was rejected. Returned if <code>review_status</code> is "REJECTED".
            type: array
            items:
              type: string
              description: ad disapproval reasons
              enum:
              - HASHTAGS
              - PROMOTIONS_AND_PRICES
              - TARGETING
              - LANDING_PAGE
              - CAPS_AND_SYMBOLS
              - SHOCKING
              - WEIGHT_LOSS
              - PROHIBITED_PRODUCT
              - AUTHENTICITY
              - NUDITY
              - CONFUSING_DESIGN
              - URGENCY
              - RATINGS
              - APP
              - ALCOHOL
              - CONTESTS
              - POLITICAL
              - OTHER
              - IMAGE
              - NAR
              - INCONSISTENT
              - CLICKBAIT
              - NO_DESCRIPTION
              - LOW_QUALITY
              - EXAGGERATED_CLAIMS
              - PINTEREST_BRAND
              - ALCOHOL_NO_SALE
              - LANDING_PAGE_SPEED
              - LANDING_PAGE_HARDWALL
              - LANDING_PAGE_BROKEN
              - LANDING_PAGE_QUALITY
              - OUT_OF_STOCK
              - IMAGE_LOW_QUALITY
              - IMAGE_BUSY
              - IMAGE_POORLY_EDITED
              - IMAGE_BEFORE_AFTER
              - UGC
              - FAKE_BUTTONS
              - WEAPONS
              - SENSITIVE
              - UNACCEPTABLE_BUSINESS
              - SUSPICIOUS_CLAIMS
              - PHARMA
              - SUSPICIOUS_SUPPLEMENTS
              - ILLEGAL_RECREATIONAL_DRUG
              - LOW_QUALITY_LANDING_PAGE
              - RESTRICTED_HEALTHCARE
              - INCONSISTENT_LANG_FR
          rejection_labels:
            description: Text reason why the pin was rejected. Returned if <code>review_status</code> is "REJECTED".
            type: array
            items:
              type: string
          review_status:
            type: string
            description: Ad review status
            example: PENDING
            enum:
            - OTHER
            - PENDING
            - REJECTED
            - APPROVED
          type:
            description: Always "ad".
            example: pinpromotion
            type: string
          updated_time:
            description: Last update time. Unix timestamp in seconds.
            example: 1451431341
            type: integer
          summary_status:
            type: string
            allOf:
            - $ref: '#/components/schemas/PinPromotionSummaryStatus'
            description: Ad summary status
    GridClickType:
      type:
      - string
      - 'null'
      description: Where a user is taken after clicking on an ad in grid. </p><strong>Note:</strong>  This parameter is read-only and is set to DIRECT_TO_DESTINATION by default for direct links supported ads.  grid_click_type values provided will be ignored.
      example: CLOSEUP
      enum:
      - CLOSEUP
      - DIRECT_TO_DESTINATION
    QuizPinOption:
      description: ' This field contains multiple options to a quiz question.'
      example:
        id: 1
        text: Where do you thrive?
      type:
      - object
      - 'null'
      properties:
        id:
          type: number
        text:
          type: string
    AdCommon:
      type: object
      description: Creation fields
      properties:
        ad_group_id:
          description: ID of the ad group that contains the ad.
          example: '2680059592705'
          type: string
          pattern: ^(AG)?\d+$
        android_deep_link:
          description: Deep link URL for Android devices. Not currently available. Using this field will generate an error.
          type:
          - string
          - 'null'
        carousel_android_deep_links:
          description: Comma-separated deep links for the carousel pin on Android.
          type:
          - array
          - 'null'
          items:
            type: string
        carousel_destination_urls:
          description: Comma-separated destination URLs for the carousel pin to promote.
          type:
          - array
          - 'null'
          items:
            type: string
        carousel_ios_deep_links:
          description: Comma-separated deep links for the carousel pin on iOS.
          type:
          - array
          - 'null'
          items:
            type: string
        click_tracking_url:
          description: Tracking url for the ad clicks.
          type:
          - string
          - 'null'
        creative_type:
          $ref: '#/components/schemas/CreativeType'
        destination_url:
          description: Destination URL.
          type:
          - string
          - 'null'
        ios_deep_link:
          description: Deep link URL for iOS devices. Not currently available. Using this field will generate an error.
          type:
          - string
          - 'null'
        is_pin_deleted:
          description: Is original pin deleted?
          example: false
          type: boolean
        is_removable:
          description: Is pin repinnable?
          example: false
          type: boolean
        name:
          description: Name of the ad - 255 chars max.
          type:
          - string
          - 'null'
        status:
          $ref: '#/components/schemas/EntityStatus'
        tracking_urls:
          type:
          - object
          - 'null'
          allOf:
          - $ref: '#/components/schemas/TrackingUrls'
        view_tracking_url:
          description: Tracking URL for ad impressions.
          type:
          - string
          - 'null'
        lead_form_id:
          description: Lead form ID for lead ad generation.
          type:
          - string
          - 'null'
          pattern: ^(AG)?\d+$
        grid_click_type:
          $ref: '#/components/schemas/GridClickType'
        customizable_cta_type:
          type:
          - string
          - 'null'
          description: Select a call to action (CTA) to display 

# --- truncated at 32 KB (55 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/pinterest/refs/heads/main/openapi/pinterest-ads-api-openapi.yml