---
title: "Create ads"
method: POST
path: "/ad_accounts/{ad_account_id}/ads"
tags: ["ads"]
---

# Create ads

`POST /ad_accounts/{ad_account_id}/ads`

## Request

- Base URL: `https://api.pinterest.com/v5`
- URL: `https://api.pinterest.com/v5/ad_accounts/{ad_account_id}/ads`
- Auth: OAuth 2
  - Authorization code: `https://www.pinterest.com/oauth/`
  - Token URL: `https://api.pinterest.com/v5/oauth/token` scopes: `ads:write`
- TypeScript: <https://skmtc.dev/pinterest/apis/pinterest-rest-api/docs/ad_accounts/:ad_account_id/ads/post.ts> (a function with typed inputs; its response is checked against the schema)

Create multiple new ads. Request must contain ad_group_id, creative_type, and the source Pin pin_id.

## Path parameters

- `ad_account_id` string, required

## Request body

- AdCreate[]
  - `ad_group_id` string, required: ID of the ad group that contains the ad.
  - `android_deep_link` string, nullable: Deep link URL for Android devices.
  - `carousel_android_deep_links` string[], nullable: Comma-separated deep links for the carousel pin on Android.
  - `carousel_destination_urls` string[], nullable: Comma-separated destination URLs for the carousel pin to promote.
  - `carousel_ios_deep_links` string[], nullable: Comma-separated deep links for the carousel pin on iOS.
  - `click_tracking_url` string, nullable: Tracking url for the ad clicks.
  - `collection_items_destination_url_template` string, nullable: Destination URL template for all items within a collections drawer.
  - `collections_header_type` 'SHOP_THIS_COLLECTION' | 'EXPLORE_THIS_COLLECTION' | 'NO_HEADER' | 'null', nullable: Collections ad header type for ads
  - `creative_type` 'REGULAR' | 'VIDEO' | 'SHOPPING' | 'CAROUSEL' | 'MAX_VIDEO' | 'SHOP_THE_PIN' | 'COLLECTION' | 'IDEA' | 'SHOWCASE' | 'QUIZ' | 'COLLAGE' | 'MAX_WIDTH_REGULAR_COLLECTION' | 'MAX_WIDTH_VIDEO_COLLECTION' | 'APP', required: Ad creative type enum. **Note:** SHOP_THE_PIN has been deprecated. Please use COLLECTION instead.
  - `customizable_cta_type` 'GET_OFFER' | 'LEARN_MORE' | 'ORDER_NOW' | 'SHOP_NOW' | 'SIGN_UP' | 'SUBSCRIBE' | 'BUY_NOW' | 'CONTACT_US' | 'GET_QUOTE' | 'VISIT_SITE' | 'APPLY_NOW' | 'BOOK_NOW' | 'REQUEST_DEMO' | 'REGISTER_NOW' | 'FIND_A_DEALER' | 'ADD_TO_CART' | 'WATCH_NOW' | 'READ_MORE' | 'BUY_TICKETS' | 'DONATE_NOW' | 'DOWNLOAD' | 'EXPLORE_MORE' | 'FIND_A_LOCATION' | 'FIND_RETAILERS' | 'GET_DEAL' | 'GET_RECIPE' | 'GET_SHOWTIMES' | 'ON_SALE' | 'PLAY_GAME' | 'TRY_IT' | 'TAKE_A_PEEK' | 'null', nullable: Select a call to action (CTA) to display below your ad. Available only for ads with direct links enabled. CTA options for consideration and conversion campaigns are LEARN_MORE, SHOP_NOW, BOOK_NOW, SIGN_UP, VISIT_SITE, BUY_NOW, GET_OFFER, ORDER_NOW, ADD_TO_CART (for conversion campaigns with add to cart conversion events only)
  - `destination_url` string, nullable: Destination URL.
  - `disclosure_type` 'NO_DISCLOSURE' | 'PRESCRIBING_INFORMATION' | 'PRESCRIBING_INFORMATION_BOX_WARNING' | 'IMPORTANT_SAFETY_INFO' | 'MED_GUIDE' | 'PATIENT_INFORMATION' | 'null', nullable: Type of information in the page referenced by `disclosure_url`, provided either by the Food and Drug Administration (FDA) or the manufacturer.
  - `disclosure_url` string, nullable: URL for a page that provides disclosures about a pharmaceutical product, such as potential side effects. Make sure the URL takes the user directly to the disclosure content and the referenced site is secure.
  - `grid_click_type` 'CLOSEUP' | 'DIRECT_TO_DESTINATION', nullable: Where a user is taken after clicking on an ad in grid. **Note:** 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.
  - `ios_deep_link` string, nullable: Deep link URL for iOS devices.
  - `is_carting` boolean: Is the ad a carting/WTB ad?
  - `is_collage_accepted_terms` boolean: Whether the advertiser has accepted the terms and conditions for collage ad.
  - `is_collage_single_destination` boolean: Whether the collage ad has a single destination url override.
  - `is_pin_deleted` boolean: Is original pin deleted?
  - `is_removable` boolean: Is pin repinnable?
  - `lead_form_id` string, nullable: Lead form ID for lead ad generation.
  - `name` string, nullable: Name of the ad - 255 chars max.
  - `pin_id` string, required: Pin ID. This field may only be updated for draft ads.
  - `quiz_pin_data` QuizPinData, nullable: This field includes all quiz data including questions, options, and results.
    - `questions` QuizPinQuestion[]
      - `options` QuizPinOption[]
        - `id` number
        - `text` string
      - `question_id` number
      - `question_text` string
    - `results` QuizPinResult[]
      - `android_deep_link` string
      - `destination_url` string
      - `ios_deep_link` string
      - `organic_pin_id` string
      - `result_id` number
    - `tie_breaker_custom_result` QuizPinResult, nullable: The result, and link out, based on the user’s choice.
      - `android_deep_link` string
      - `destination_url` string
      - `ios_deep_link` string
      - `organic_pin_id` string
      - `result_id` number
    - `tie_breaker_type` 'RANDOM' | 'CUSTOM': Quiz ad tie breaker type, default is RANDOM
  - `status` 'ACTIVE' | 'PAUSED' | 'ARCHIVED' | 'DRAFT' | 'DELETED_DRAFT': Entity status
  - `tracking_urls` TrackingUrls, nullable: Third-party tracking URLs. Up to three tracking URLs - with a max length of 2,000 - are supported for each event type. Tracking URLs set at the ad group or ad level can override those set at the campaign level. For more information, see [Third-party and dynamic tracking](https://help.pinterest.com/en/business/article/third-party-and-dynamic-tracking).
    - `audience_verification` string[]
    - `buyable_button` string[]
    - `click` string[]
    - `engagement` string[]
    - `impression` string[]
  - `view_tracking_url` string, nullable: Tracking URL for ad impressions.

## Response `200`

The request has succeeded.

- AdBatchWriteResponseModel
  - `items` AdBatchItem[], required
    - `data` Ad
      - `ad_account_id` string, required: The ID of the advertiser that this ad belongs to.
      - `ad_group_id` string, required: ID of the ad group that contains the ad.
      - `android_deep_link` string, nullable: Deep link URL for Android devices.
      - `campaign_id` string, required: ID of the ad campaign that contains this ad.
      - `carousel_android_deep_links` string[], nullable: Comma-separated deep links for the carousel pin on Android.
      - `carousel_destination_urls` string[], nullable: Comma-separated destination URLs for the carousel pin to promote.
      - `carousel_ios_deep_links` string[], nullable: Comma-separated deep links for the carousel pin on iOS.
      - `carting_platform_type` integer: The vendor platform type of the carting ad. 1 for MIKMAK, 2 for PEAR.
      - `carting_products` CartingProduct[]: Array of carting/WTB products for the ad.
        - `carting_product_id` string, required: the internal Pinterest carting product id (different from industry product id)
        - `display_preferred_retailers_only` boolean: Whether to display only the preferred retailers for the carting product
        - `display_product_price` boolean: Whether to display the price for the carting product
        - `preferred_retailers` CartingRetailer[]: A sorted array of preferred retailers for the carting product
          - `retailer_id` string, required: Unique identifier for the retailer
          - `retailer_name` string, required: Name of the retailer
        - `randomize_preferred_retailers` boolean: Whether to randomize preferred retailers for the carting product
      - `click_tracking_url` string, nullable: Tracking url for the ad clicks.
      - `collection_items_destination_url_template` string, nullable: Destination URL template for all items within a collections drawer.
      - `collections_header_type` 'SHOP_THIS_COLLECTION' | 'EXPLORE_THIS_COLLECTION' | 'NO_HEADER' | 'null', nullable: Collections ad header type for ads
      - `created_time` integer: Pin creation time. Unix timestamp in seconds.
      - `creative_type` 'REGULAR' | 'VIDEO' | 'SHOPPING' | 'CAROUSEL' | 'MAX_VIDEO' | 'SHOP_THE_PIN' | 'COLLECTION' | 'IDEA' | 'SHOWCASE' | 'QUIZ' | 'COLLAGE' | 'MAX_WIDTH_REGULAR_COLLECTION' | 'MAX_WIDTH_VIDEO_COLLECTION' | 'APP', required: Ad creative type enum. **Note:** SHOP_THE_PIN has been deprecated. Please use COLLECTION instead.
      - `customizable_cta_type` 'GET_OFFER' | 'LEARN_MORE' | 'ORDER_NOW' | 'SHOP_NOW' | 'SIGN_UP' | 'SUBSCRIBE' | 'BUY_NOW' | 'CONTACT_US' | 'GET_QUOTE' | 'VISIT_SITE' | 'APPLY_NOW' | 'BOOK_NOW' | 'REQUEST_DEMO' | 'REGISTER_NOW' | 'FIND_A_DEALER' | 'ADD_TO_CART' | 'WATCH_NOW' | 'READ_MORE' | 'BUY_TICKETS' | 'DONATE_NOW' | 'DOWNLOAD' | 'EXPLORE_MORE' | 'FIND_A_LOCATION' | 'FIND_RETAILERS' | 'GET_DEAL' | 'GET_RECIPE' | 'GET_SHOWTIMES' | 'ON_SALE' | 'PLAY_GAME' | 'TRY_IT' | 'TAKE_A_PEEK' | 'null', nullable: Select a call to action (CTA) to display below your ad. Available only for ads with direct links enabled. CTA options for consideration and conversion campaigns are LEARN_MORE, SHOP_NOW, BOOK_NOW, SIGN_UP, VISIT_SITE, BUY_NOW, GET_OFFER, ORDER_NOW, ADD_TO_CART (for conversion campaigns with add to cart conversion events only)
      - `destination_url` string, nullable: Destination URL.
      - `disclosure_type` 'NO_DISCLOSURE' | 'PRESCRIBING_INFORMATION' | 'PRESCRIBING_INFORMATION_BOX_WARNING' | 'IMPORTANT_SAFETY_INFO' | 'MED_GUIDE' | 'PATIENT_INFORMATION' | 'null', nullable: Type of information in the page referenced by `disclosure_url`, provided either by the Food and Drug Administration (FDA) or the manufacturer.
      - `disclosure_url` string, nullable: URL for a page that provides disclosures about a pharmaceutical product, such as potential side effects. Make sure the URL takes the user directly to the disclosure content and the referenced site is secure.
      - `grid_click_type` 'CLOSEUP' | 'DIRECT_TO_DESTINATION', nullable: Where a user is taken after clicking on an ad in grid. **Note:** 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.
      - `id` string, required: The ID of this ad.
      - `ios_deep_link` string, nullable: Deep link URL for iOS devices.
      - `is_carting` boolean: Is the ad a carting/WTB ad?
      - `is_collage_accepted_terms` boolean: Whether the advertiser has accepted the terms and conditions for collage ad.
      - `is_collage_single_destination` boolean: Whether the collage ad has a single destination url override.
      - `is_pin_deleted` boolean: Is original pin deleted?
      - `is_removable` boolean: Is pin repinnable?
      - `lead_form_id` string, nullable: Lead form ID for lead ad generation.
      - `name` string, nullable: Name of the ad - 255 chars max.
      - `pin_id` string, required: Pin ID. This field may only be updated for draft ads.
      - `quiz_pin_data` QuizPinData, nullable: This field includes all quiz data including questions, options, and results.
        - `questions` QuizPinQuestion[]
          - `options` QuizPinOption[]
            - `id` number
            - `text` string
          - `question_id` number
          - `question_text` string
        - `results` QuizPinResult[]
          - `android_deep_link` string
          - `destination_url` string
          - `ios_deep_link` string
          - `organic_pin_id` string
          - `result_id` number
        - `tie_breaker_custom_result` QuizPinResult, nullable: The result, and link out, based on the user’s choice.
          - `android_deep_link` string
          - `destination_url` string
          - `ios_deep_link` string
          - `organic_pin_id` string
          - `result_id` number
        - `tie_breaker_type` 'RANDOM' | 'CUSTOM': Quiz ad tie breaker type, default is RANDOM
      - `rejected_reasons` AdDisapprovalReasons[], required: Enum reason why the pin was rejected. Returned if `review_status` is "REJECTED".
      - `rejection_labels` string[], required: Text reason why the pin was rejected. Returned if `review_status` is "REJECTED".
      - `review_status` 'OTHER' | 'PENDING' | 'REJECTED' | 'APPROVED', required: Ad review status
      - `status` 'ACTIVE' | 'PAUSED' | 'ARCHIVED' | 'DRAFT' | 'DELETED_DRAFT': Entity status
      - `summary_status` 'APPROVED' | 'PAUSED' | 'PENDING' | 'REJECTED' | 'ADVERTISER_DISABLED' | 'ARCHIVED' | 'DRAFT' | 'DELETED_DRAFT', required: Summary status for pin promotions
      - `tracking_urls` TrackingUrls, nullable: Third-party tracking URLs. Up to three tracking URLs - with a max length of 2,000 - are supported for each event type. Tracking URLs set at the ad group or ad level can override those set at the campaign level. For more information, see [Third-party and dynamic tracking](https://help.pinterest.com/en/business/article/third-party-and-dynamic-tracking).
        - `audience_verification` string[]
        - `buyable_button` string[]
        - `click` string[]
        - `engagement` string[]
        - `impression` string[]
      - `type` string, required: Always "ad".
      - `updated_time` integer: Last update time. Unix timestamp in seconds.
      - `view_tracking_url` string, nullable: Tracking URL for ad impressions.
    - `exceptions` PinterestLibError: Default error response
      - `code` integer, required
      - `message` string, required

## Other responses

- `400`: The request could not be understood by the server due to unexpected data.
- `401`: Authentication is required and has either failed or not been provided.
- `403`: The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource.
- `404`: The requested resource could not be found on this server.
- `429`: The user has sent too many requests in a given amount of time and is being rate limited.
- `default`: An unexpected error response.

## Changes

- **2026-06-04** (v5) `b698c180678a`: 3 breaking, 1 warning, 72 info
  - added the new required request property `items/ad_group_id`
  - added the new required request property `items/creative_type`
  - added the new required request property `items/pin_id`
  - removed `#/components/schemas/AdCommon, #/components/schemas/AdPinId, subschema #3: Request schema for creating ads` from the `items/` request property `allOf` list
  - …72 more
- **2025-12-11** (v5) `537bde5a50b1`: 4 info
  - added the new optional request property `items/allOf[#/components/schemas/AdCommon]/disclosure_type`
  - added the new optional request property `items/allOf[#/components/schemas/AdCommon]/disclosure_url`
  - added the optional property `items/items/data/allOf[#/components/schemas/AdCommon]/disclosure_type` to the response with the `200` status
  - added the optional property `items/items/data/allOf[#/components/schemas/AdCommon]/disclosure_url` to the response with the `200` status
- …earlier changes not shown

[Operation history](https://skmtc.dev/pinterest/apis/pinterest-rest-api/changes/ad_accounts/:ad_account_id/ads/post.md)

---

[API](https://skmtc.dev/pinterest/apis/pinterest-rest-api.md) - [All operations](https://skmtc.dev/pinterest/apis/pinterest-rest-api/llms.txt) - [OpenAPI document](https://skmtc.dev/pinterest/apis/pinterest-rest-api/revisions/b698c180678a?raw)