Skip to content

Developer Platform

Search docs & API
Log in
Sign up

Create dynamic CTAs in ads

You can enable dynamic call-to-action (CTA) selection for your ads and product group promotions. This allows Pinterest's rules-based model to automatically serve the most effective CTA based on context, such as placement and device type, to improve click volume and post-click engagement.

Endpoints

POST
Create ads
PATCH
Update ads
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.

Eligibility requirements for ads

Note these requirements when using this feature. A request that violates any of them is rejected:
  • Campaign objective must be
    TRAFFIC
    ,
    WEB_CONVERSION
    , or
    AWARENESS
    .
  • Creative type must be one of
    REGULAR
    ,
    VIDEO
    ,
    CAROUSEL
    ,
    STORY
    ,
    MAX_VIDEO
    , or
    SHOPPING
    .
  • You cannot use dynamic CTAs in the following scenarios:
    • For lead ads (no lead form)
    • For ads with carting-enabled products
    • With Dynamic Standard Ads enabled (
      "is_dsa"="true"
      ), which optimize among multiple candidate images

Request parameters to keep in mind

Dynamic CTA parameters
ParameterDescription
is_dynamic_cta

Boolean
Optional but necessary for this use case
If set to
true
, Pinterest automatically selects the best CTA from the
cta_types
list based on contextual signals, such as placement and device. For example, a user on Android viewing a search ad may see "Take a closer look" instead of a generic CTA.
If set to
false
(default), Pinterest serves the CTA that you set in the
customizable_cta_type
parameter.
If you do not specify a CTA type in either case, we determine a default CTA based on the ad's campaign objective and destination.
cta_types

Array of strings
Optional but necessary if
is_dynamic_cta
is set to
true
CTAs that you want dynamically served.
For consideration and conversion campaigns:
Select any of
ADD_TO_CART
,
BOOK_NOW
,
BUY_NOW
,
GET_OFFER
,
LEARN_MORE
(default for mobile deep links),
ORDER_NOW
SHOP_NOW
,
SIGN_UP
, or
VISIT_SITE
(default, except for mobile deep links).
For catalog sales campaigns:
The array must include at least two CTAs, one of which is
SHOP_NOW
.
Additionally, select any of
BUY_NOW
,
GET_IT_NOW
,
SHOP_NOW
,
SHOP_ON_ADVERTISER
,
SHOP_THE_COLLECTION
,
TAKE_A_CLOSER_LOOK
TAKE_A_PEEK
.
Make sure not to include duplicate values, which cause the request to fail.
As part of objective simplification, the
WEB_CONVERSION
and
CATALOG_SALES
are being deprecated, to be replaced by
LEAD
and
SALES
objectives respectively. See the details and timeline for objective simplification.
As part of objective simplification, the
WEB_CONVERSION
and
CATALOG_SALES
are being deprecated, to be replaced by
LEAD
and
SALES
objectives respectively. See the details and timeline for objective simplification.

Example request to create an ad with dynamic CTAs enabled

curl -X POST "https://api.pinterest.com/v5/ad_accounts/123456789012345678/ads" \
 -H "Authorization: Bearer <access_token>" \
 -H "Content-Type: application/json" \
 -d '[
   {
     "ad_group_id": "AG123456789012345678",
     "pin_id": "987654321098765432",
     "creative_type": "REGULAR",

     "is_dynamic_cta": true,
     "cta_types": [
       "LEARN_MORE",
       "GET_OFFER",
       "VISIT_SITE",
       "ORDER_NOW"
     ]
   }
 ]'

Example response for the request with dynamic CTAs enabled

{
  "items": [
    {
      "data": {
        "id": "112233445566778899",
        "ad_group_id": "AG123456789012345678",
        "pin_id": "987654321098765432",
        "creative_type": "REGULAR",
        "ad_account_id": "123456789012345678",
        "campaign_id": "223344556677889900",
        "rejected_reasons": [],
        "rejection_labels": [],
        "review_status": "PENDING",
        "type": "ad",
        "summary_status": "PENDING",
        "is_dynamic_cta": true,
        "cta_types": ["LEARN_MORE", "GET_OFFER", "VISIT_SITE", "ORDER_NOW"]
      }
    }
  ]
}

Example request to create an ad without dynamic CTAs

When
is_dynamic_cta
set to
false
, provide a CTA for the
customizable_cta_type
parameter, and omit the
cta_types
array.
curl -X POST "https://api.pinterest.com/v5/ad_accounts/123456789012345678/ads" \
 -H "Authorization: Bearer <access_token>" \
 -H "Content-Type: application/json" \
 -d '[
   {
     "ad_group_id": "AG123456789012345678",
     "pin_id": "987654321098765432",
     "creative_type": "REGULAR",
     "is_dynamic_cta": false,
     "customizable_cta_type": "VISIT_SITE"
   }
 ]'

Example response for an ad without dynamic CTAs

{
  "items": [
    {
      "data": {
        "id": "112233445566778899",
        "ad_group_id": "AG123456789012345678",
        "pin_id": "987654321098765432",
        "creative_type": "REGULAR",
        "ad_account_id": "123456789012345678",
        "campaign_id": "223344556677889900",
        "rejected_reasons": [],
        "rejection_labels": [],
        "review_status": "PENDING",
        "type": "ad",
        "summary_status": "PENDING",
        "is_dynamic_cta": false,
        "customizable_cta_type": "VISIT_SITE"
      }
    }
  ]
}