Skip to content

Developer Platform

Search docs & API
Log in
Sign up

Generate shareable ad previews

You can generate previews for ads and product group promotions that users can open in browsers without needing Ads Manager access. By sharing a web URL, you can show your internal team members or clients exactly how each creative will look and feel in the Pinterest environment.
When you post ad group IDs in a request to the preview endpoint, it returns a preview URL for every ad or product group promotion within each ad group in the request.
Shareable ad preview
You do not have to call the preview endpoint each time you update your creative. The preview always displays the current ad.
You do not have to call the preview endpoint each time you update your creative. The preview always displays the current ad.
The API supports standard pin, video ad, carousel, collections, shopping ads, and other ad formats.
Previews are for illustrative purposes only, and final ad appearance may vary.

Generate a preview

POST
Create ad preview records for one or more ad groups
Any parameters and code examples that appear in this section support this use case, but may not represent the full endpoint specification. See the endpoint reference page for the comprehensive spec.
Any parameters and code examples that appear in this section support this use case, but may not represent the full endpoint specification. See the endpoint reference page for the comprehensive spec.

Request parameters to keep in mind

Shareable previews request table
ParameterDescription
ad_group_id

string
Required
Identify every ad group that you want to generate previews for.
100 maximum ad groups per request.

Example request

Each ad group is an object within an array:
curl --request POST \
  --url https://api.pinterest.com/v5/ad_accounts/123456789012/campaign_ad_preview \
  --header 'authorization: Bearer pina_ABCD1234...' \
  --header 'content-type: application/json' \
  --data '[
  {
    "ad_group_id": "2680085790110"
  },
  {
    "ad_group_id": "2680087870156"
  }
]'

Response fields to keep in mind

Shareable previews response table
FieldDescription
data

object
Container for each returned ad preview and associated metadata.
data.uuid

string
Unique identifier for the preview within the object.
data.url

string
URL for the preview within the object.
data.expires_at

integer
Unix time in milliseconds for when the preview expires, which is in 30 days.
After the preview expires, you need to rerun the request to generate preview URLs again.
data.ad_group_id

string
Identifier for the parent ad group for the ad or product group promotion in the object.
data.pin_id

string
Identifier for the organic Pin, if the preview is for an ad.
data.pin_promotion_id

string
Identifier for the promoted Pin, if the preview is for an ad.
data.promoted_product_group_id

string
Identifier for the product group promotion, if the preview is for a product group promotion.
data.is_active

boolean
Whether the preview is active and can be viewed (
true
).
data.exceptions

object
Container for errors that the endpoint reports with any ad groups in the request.
A request can partially fail. For example, if a request includes two ad groups, the endpoint can return previews for one ad group and exceptions/errors for the other.
Previews for each ad group are all generated in batch, so if there is an exception with any of ads within the ad group, no previews will be generated for that ad group.
See Troubleshoot exceptions.
data.exceptions.code

integer
Code for an error.
data.exceptions.message

string
Explanation of the error.

Example response with multiple ads in an ad group

In this example, the ad group with the ID ending in
0110
includes three ads, so there are three returned objects in the array, each with its own preview.
[
  {
    "data": {
      "uuid": "283d5bc1-c1db-4a84-9a28-73bbdc77f64b",
      "url": "https://ads.pinterest.com/web-ad-preview/283d5bc1-c1db-4a84-9a28-73bbdc77f64b/",
      "expires_at": 1776957856993,
      "advertiser_id": 549765694862,
      "user_id": 956944758230631867,
      "ad_group_id": "2680085790110",
      "is_active": true,
      "pin_id": 956944620824666359,
      "pin_promotion_id": 687283938179
    }
  },
  {
    "data": {
      "uuid": "7f2d9a3b-0a64-4f89-9c6a-1e6f6b7d9c21",
      "url": "https://ads.pinterest.com/web-ad-preview/7f2d9a3b-0a64-4f89-9c6a-1e6f6b7d9c21/",
      "expires_at": 1776957858200,
      "advertiser_id": 549765694862,
      "user_id": 956944758230631867,
      "ad_group_id": "2680085790110",
      "is_active": true,
      "pin_id": 956944620824666360,
      "pin_promotion_id": 687283938180
    }
  },
  {
    "data": {
      "uuid": "c1b5f2a6-3f7d-4a49-8b32-4c5a4d92d8ef",
      "url": "https://ads.pinterest.com/web-ad-preview/c1b5f2a6-3f7d-4a49-8b32-4c5a4d92d8ef/",
      "expires_at": 1776957859300,
      "advertiser_id": 549765694862,
      "user_id": 956944758230631867,
      "ad_group_id": "2680085790110",
      "is_active": true,
      "pin_id": 956944620824666361,
      "pin_promotion_id": 687283938181
    }
  },
  {
    "data": {
      "uuid": "10710eff-8638-4d11-8111-0d67669eb4b8",
      "url": "https://ads.pinterest.com/web-ad-preview/10710eff-8638-4d11-8111-0d67669eb4b8/",
      "expires_at": 1776957857911,
      "advertiser_id": 549765694862,
      "user_id": 956944758230631867,
      "ad_group_id": "2680087870156",
      "is_active": true,
      "pin_id": 956944620830868834,
      "pin_promotion_id": 687295612761
    }
  }
]

Example response with partial failure

This request with two ad groups returns previews for one ad group and an error for the other.
[
  {
    "data": {
      "uuid": "aa5d8586-9de9-441b-a544-6137c1b543bd",
      "url": "https://ads.pinterest.com/web-ad-preview/aa5d8586-9de9-441b-a544-6137c1b543bd/",
      "expires_at": 1777055255104,
      "advertiser_id": 549765694862,
      "user_id": 956944758230631867,
      "ad_group_id": "2680085790110",
      "is_active": true,
      "pin_id": 956944620824666359,
      "pin_promotion_id": 687283938179
    }
  },
  {
    "data": {
      "exceptions": {
        "code": 29,
        "message": "Ad group 1111111111111 is not owned by advertiser 549765694862"
      }
    }
  }
]

Troubleshoot exceptions

See this section for actions you can take to address some of the exceptions that the endpoint may return.
Shareable previews error codes and actions
CodeMessageAction
400
Invalid request

Invalid parameters.
References the entire request.
Do the following and rerun the request for the ad group:
  • Check for missing
    ad_group_id
    .
  • Validate and correct, if necessary, the payload shape.
  • Make sure the request includes 100 or fewer ad groups.
29
Ad group <AD_GROUP_ID> is not owned by advertiser <ADVERTISER_ID>

References a
data
response object.
Rerun the request without the ad group.
0
Failed to create preview for ad group <AD_GROUP_ID>

Unexpected failure.
References a
data
response object.
Try running the request again. If this error continues to occur, contact Support.\
Was this page helpful?