Sign in

v29

latestOpenAPI 3.0.3MITraw.githubusercontent.com2026-06-042661,1122.5 MB
ads

Create ads

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

post/ad_accounts/{ad_account_id}/ads

Path parameters

ad_account_idstring required

Unique identifier of an ad account.

Request body

ad_group_idstring required

ID of the ad group that contains the ad.

android_deep_linkstring nullable

Deep link URL for Android devices.

carousel_android_deep_linksstring[] nullable

Comma-separated deep links for the carousel pin on Android.

carousel_destination_urlsstring[] nullable

Comma-separated destination URLs for the carousel pin to promote.

carousel_ios_deep_linksstring[] nullable

Comma-separated deep links for the carousel pin on iOS.

click_tracking_urlstring nullable

Tracking url for the ad clicks.

collection_items_destination_url_templatestring 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_urlstring 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_urlstring 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_linkstring nullable

Deep link URL for iOS devices.

is_cartingboolean

Is the ad a carting/WTB ad?

is_collage_accepted_termsboolean

Whether the advertiser has accepted the terms and conditions for collage ad.

is_collage_single_destinationboolean

Whether the collage ad has a single destination url override.

is_pin_deletedboolean

Is original pin deleted?

is_removableboolean

Is pin repinnable?

lead_form_idstring nullable

Lead form ID for lead ad generation.

namestring nullable

Name of the ad - 255 chars max.

pin_idstring required

Pin ID. This field may only be updated for draft ads.

status'ACTIVE' | 'PAUSED' | 'ARCHIVED' | 'DRAFT' | 'DELETED_DRAFT'

Entity status

view_tracking_urlstring nullable

Tracking URL for ad impressions.

Example request

[
  {
    "collections_header_type": "SHOP_THIS_COLLECTION",
    "customizable_cta_type": "LEARN_MORE",
    "disclosure_type": "MED_GUIDE",
    "grid_click_type": "CLOSEUP",
    "quiz_pin_data": {
      "questions": [
        {
          "question_id": 1,
          "question_text": "Where do you thrive?",
          "options": [
            {
              "text": "Hangout vibes"
            },
            {
              "text": "Time to party!"
            },
            {
              "text": "Keeping it lowkey"
            }
          ]
        },
        {
          "question_id": 2,
          "question_text": "Where would you nap?",
          "options": [
            {
              "text": "Hammock in the mountains"
            },
            {
              "text": "Beach towel in the sand"
            },
            {
              "text": "Tent under the stars"
            }
          ]
        },
        {
          "question_id": 2,
          "question_text": "Who are you taking?",
          "options": [
            {
              "text": "No one—solo trip!"
            },
            {
              "text": "My best friend"
            },
            {
              "text": "The family"
            }
          ]
        }
      ],
      "results": [
        {
          "organicPinId": "1234",
          "android_deep_link": "https://www.pinterest.com/",
          "iOS_deep_link": "https://www.pinterest.com/",
          "destination_url": "https://www.pinterest.com/",
          "result_id": 1
        },
        {
          "organicPinId": "1234",
          "android_deep_link": "https://www.pinterest.com/",
          "iOS_deep_link": "https://www.pinterest.com/",
          "destination_url": "https://www.pinterest.com/",
          "result_id": 2
        },
        {
          "organicPinId": "1234",
          "android_deep_link": "https://www.pinterest.com/",
          "iOS_deep_link": "https://www.pinterest.com/",
          "destination_url": "https://www.pinterest.com/",
          "result_id": 3
        }
      ]
    },
    "status": "ACTIVE",
    "tracking_urls": {
      "impression": [
        "URL1",
        "URL2"
      ],
      "click": [
        "URL1",
        "URL2"
      ],
      "engagement": [
        "URL1",
        "URL2"
      ],
      "buyable_button": [
        "URL1",
        "URL2"
      ],
      "audience_verification": [
        "URL1",
        "URL2"
      ]
    }
  }
]

Response

The request has succeeded.

Example response

{
  "items": [
    {
      "data": {
        "collections_header_type": "SHOP_THIS_COLLECTION",
        "customizable_cta_type": "LEARN_MORE",
        "disclosure_type": "MED_GUIDE",
        "grid_click_type": "CLOSEUP",
        "quiz_pin_data": {
          "questions": [
            {
              "question_id": 1,
              "question_text": "Where do you thrive?",
              "options": [
                {
                  "text": "Hangout vibes"
                },
                {
                  "text": "Time to party!"
                },
                {
                  "text": "Keeping it lowkey"
                }
              ]
            },
            {
              "question_id": 2,
              "question_text": "Where would you nap?",
              "options": [
                {
                  "text": "Hammock in the mountains"
                },
                {
                  "text": "Beach towel in the sand"
                },
                {
                  "text": "Tent under the stars"
                }
              ]
            },
            {
              "question_id": 2,
              "question_text": "Who are you taking?",
              "options": [
                {
                  "text": "No one—solo trip!"
                },
                {
                  "text": "My best friend"
                },
                {
                  "text": "The family"
                }
              ]
            }
          ],
          "results": [
            {
              "organicPinId": "1234",
              "android_deep_link": "https://www.pinterest.com/",
              "iOS_deep_link": "https://www.pinterest.com/",
              "destination_url": "https://www.pinterest.com/",
              "result_id": 1
            },
            {
              "organicPinId": "1234",
              "android_deep_link": "https://www.pinterest.com/",
              "iOS_deep_link": "https://www.pinterest.com/",
              "destination_url": "https://www.pinterest.com/",
              "result_id": 2
            },
            {
              "organicPinId": "1234",
              "android_deep_link": "https://www.pinterest.com/",
              "iOS_deep_link": "https://www.pinterest.com/",
              "destination_url": "https://www.pinterest.com/",
              "result_id": 3
            }
          ]
        },
        "status": "ACTIVE",
        "summary_status": "APPROVED",
        "tracking_urls": {
          "impression": [
            "URL1",
            "URL2"
          ],
          "click": [
            "URL1",
            "URL2"
          ],
          "engagement": [
            "URL1",
            "URL2"
          ],
          "buyable_button": [
            "URL1",
            "URL2"
          ],
          "audience_verification": [
            "URL1",
            "URL2"
          ]
        }
      },
      "exceptions": {
        "code": 2,
        "message": "AdAccount not found."
      }
    }
  ]
}