Skip to content

Developer Platform

Search docs & API
Log in
Sign up

Managing ads

The Pinterest API allows you to create ads directly from the tools of your choice. This guide will help you understand which ad formats are available in the API as well as other concepts to understand when creating ads on Pinterest.

Before you begin

Make sure to do the following before creating an ad:
  • Set up your business account and billing.
  • Generate an access token with the
    ads:read
    and
    ads:write
    scopes.
  • Create a campaign. Keep in mind that some ad formats are only available for
    certain campaign objectives
     .
  • Create an ad group that is a child of the campaign.
  • If you are creating a Pin-based ad, make sure you have available an ad-only Pin, which other Pinners cannot save or distribute organically. Learn how to create an ad-only Pin.
  • If you are creating a shopping ad, make sure you have a catalog set up. Learn how to build and manage catalogs.
  • Learn about Pinterest entities to understand the relationship between Pins and boards, as well as ad groups and ads.

API availability

Due to the nature of some ads, not all formats are available in the API. Below is a table of supported formats.
Ad formatAvailable in API
Standard imageYes
VideoYes
Max videoYes
IdeaYes
LeadYes
CarouselYes
CollectionYes
ShoppingYes
QuizYes
SpotlightReach out to your Pinterest sales team to create a Spotlight ad

Create an ad

Each ad sits within an ad group and has a unique URL. You can create multiple ads in a single ad group to test which variations work best with your targeted audience.
To create an ad, call the
POST
Create ads
with the following per ad:
  1. Specify the
    ad_group_id
    of your desired ad group
  2. Specify the type of ad with
    creative_type
    . Remember that only certain ad formats are available with certain campaign objectives.
  3. Specify the
    pin_id
    of the organic Pin you're turning into an ad.
  4. Set the
    is_removable
    parameter to
    true
    to make the specified Pin ad-only. This prevents the Pin from being saved by other Pinners or distributed organically, and enables you to use the Pin for the ad.
  5. In particular, the
    source_type
    and
    is_standard
    parameters determine the type of ads that can be made from the organic pin - see the “Ad formats” section below for more information.
  6. Specify any other desired parameters

Ad formats

Pinterest offers several types of ads to engage Pinners on our platforms. See the table for a summary, with more details for each ad type in each of the subsections below.
Ad Typeorganic Pin's source_typeAd's creative_type
Standard image
image_URL
or
image_base_64
REGULAR
Carousel
multi_img_URL
or
multi_img_base64
CAROUSEL
Standard video
video_ID
VIDEO
Max video
video_ID
(see Creating a Video Pin)
MAX_VIDEO
Lead
image_URL
image_base_64
or
video_ID
(see Creating a Video Pin)
REGULAR or VIDEO

Standard image ads

Standard ads feature only one image.

Carousel ads

Carousel ads feature multiple images for people to swipe through.
Creating a carousel ad on Pinterest involves several steps similar to creating a standard image ad, but includes additional components to handle multiple images or items in the carousel.
  • carousel_destination_urls
    should be set to the click through links for each image as a comma separated list.
  • Provide mobile deep links through
    carousel_android_deep_links
    and
    carousel_ios_deep_links
    . If the Pinner doesn't have your app installed, the destination URLs will be the fall back link.

Standard video and max video ads

Standard width video ads are videos that are the same size as a regular Pin, whereas max width video ads expand across the entire feed on mobile.
See Creating a Video Pin for how to create the organic pin.

Idea ads

Idea ads appear as a set of multiple videos, images, lists and custom text in a single Pin. You can promote an organic Pin as an Idea ad in countries where ads are available.
Important: The organic pin for an idea ad must have its
is_standard
parameter (found within the
media_source
parameter) set to FALSE.

Quiz ads

A quiz ad has multiple-choice questions and answers. Within each quiz result, advertisers can add outbound links to more content, products, and more.
Before creating a Quiz ad, first create an organic Pin using
POST
Create Pin
for each result in the quiz. Quiz ads cannot be saved by a Pinner, but Quiz ad results can be saved.
Next, use the
quiz_pin_data
field to set the Pin's questions and results.
  • Advertisers can create 2-3 questions per ad, and each question can have 2-3 options for Pinners to select.
  • Map the ID associated with each question option to the result_id of the result you'd like shown to the Pinner.
  • If a Pinner selects options with different result IDs, we consider this a tie and the result will be a randomized selection within the possible result IDs.
  • The number of question options should be equal to the number of results.
  • The order of options a Pinner can select within a quiz will be randomized each time it's served.
Here's an example
quiz_pin_data
payload:
{
  "quiz_pin_data": {
    "questions": [
      {
        "question_id": 1,
        "question_text": "Where do you thrive?",
        "options": [
          {
            "text": "Hangout vibes",
            "id": 1
          },
          {
            "text": "Time to party!",
            "id": 2
          },
          {
            "text": "Keeping it lowkey",
            "id": 3
          }
        ]
      },
      {
        "question_id": 2,
        "question_text": "Where would you nap?",
        "options": [
          {
            "text": "Hammock in the mountains",
            "id": 2
          },
          {
            "text": "Beach towel in the sand",
            "id": 3
          },
          {
            "text": "Tent under the stars",
            "id": 1
          }
        ]
      }
    ],
    "results": [
      {
        "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,
        "organicPinId": "1234",
        "android_deep_link": "https://www.pinterest.com/",
        "iOS_deep_link": "https://www.pinterest.com/",
        "destination_url": "https://www.pinterest.com/"
      }
    ]
  }
}
For more info, please see How Quiz Ads Work.

[Beta] Lead ads

Lead ads allow you to qualified prospects on the platform. Pinners actively looking for your services can share their information with a few taps on our native lead form.
Lead ads are a beta ad format. Reach out to your Pinterest sales representative to gain access.
In addition to creating a lead ad through the API, you're also able to seamlessly transfer lead data from Ads Manager to your CRM system with the following features.
  • Lead data subscription
  • Encrypted data transfer
  • Testing API
To learn more, please visit our Lead Ads page.

How can I use MDL in the Pinterest API?

For a general overview of Mobile Deep Links (MDLs), see this article on the Pinterest Help Center. There are two ways to add MDL via the Pinterest API depending on the type of ad.

Standard ad

Mobile deep links are set within the API request schema.
Use the
android_deep_link
and
ios_deep_link
parameters on the
POST
Create ads
.

Shopping ad

Mobile deep links are set within the catalog feed file.
In
POST
Create product group promotions
set
is_mdl
as true.
Within the catalog feed file, paste the mobile deep link in either the
link
or
ad_link
fields of the catalog feed.
Was this page helpful?