account | DynamicAccount | Yes | - | Select Pinterest Ads account to create the video Pin and ad in. |
update_type | string or SelectableOption | Yes | - | Choose whether to create a single video ad or multiple at once. Options: single or bulk. |
ad_group_id | string or SelectItem | No | - | Pinterest ad group ID to create the ad under. Required unless pin_only is true. |
ad_name | string | No | - | Name of the Pinterest ad. Required unless pin_only is true. |
ad_status | string or SelectableOption | No | {'value': 'PAUSED', 'label': 'Paused'} | Status when the ad is created. Options: ACTIVE or PAUSED. Default: PAUSED. |
video_url | string | No | - | Video to upload for the Pin/ad. Accepts a direct video URL, Google Drive share link (set to ‘Anyone with the link’), or Markifact uploaded video. Markifact uploads it to Pinterest and waits for processing. |
cover_image_url | string | No | - | Optional cover image URL for the video Pin. Pinterest requires a cover; when this is omitted, cover_image_key_frame_time is sent instead (default 0, the first frame). |
cover_image_key_frame_time | integer | No | - | Optional video timestamp in seconds to use as the cover frame. Ignored when cover_image_url is set. Defaults to 0 (the first frame). |
pin_title | string | No | - | Title for the Pinterest Pin. Up to 100 characters. |
pin_description | string | No | - | Description for the Pinterest Pin. Up to 800 characters. |
destination_url | string | No | - | Landing page URL for the Pin and ad click-through. Pinterest appends its default utm_ parameters to ad URLs that have none unless the account opts out in Business Manager; parameters you include are kept. |
board_id | string or SelectItem | No | - | Board ID to save the Pin to. Required only when ad_only_pin is false. |
ad_only_pin | boolean | No | True | Create the Pin as ad-only so it does not appear organically. Default true. |
pin_only | boolean | No | False | Create only the Pinterest video Pin and skip ad creation. Default false. |
call_to_action | string or SelectableOption | No | - | Optional Pinterest customizable CTA type, for example LEARN_MORE, SHOP_NOW, SIGN_UP. |
click_tracking_url | string | No | - | Optional third-party click tracking URL. |
view_tracking_url | string | No | - | Optional third-party impression tracking URL. |
android_deep_link | string | No | - | Optional Android deep link URL. |
ios_deep_link | string | No | - | Optional iOS deep link URL. |
is_dynamic_cta | boolean | No | False | Let Pinterest pick the best CTA per placement and device from cta_types instead of always serving one fixed CTA. Cannot be combined with call_to_action. Default false. |
cta_types | string or array of string | No | - | CTAs Pinterest may choose between when is_dynamic_cta is true, as a JSON list or comma-separated string. At least two, from: ADD_TO_CART, BUY_NOW, CONTACT_US, EXPLORE_MORE, GET_OFFER, LEARN_MORE, ORDER_NOW, SHOP_NOW, TAKE_A_PEEK, VISIT_SITE. Pinterest also requires the campaign objective’s default CTA to be in the list (VISIT_SITE for CONSIDERATION) and names the missing one in its error. Example: [“VISIT_SITE”, “SHOP_NOW”, “LEARN_MORE”]. |
return_detailed_results | boolean | No | False | Bulk mode only. If true, returns per-row results and does not raise on partial failures. |
structured_data | array (also accepts a comma-separated string) | No | - | Use only when update_type is bulk. Required columns: video_url, destination_url, pin_title or pin_description, plus ad_group_id and ad_name unless pin_only is true. Optional columns: cover_image_url, cover_image_key_frame_time, board_id, ad_only_pin, pin_only, ad_status, call_to_action, is_dynamic_cta, cta_types, click_tracking_url, view_tracking_url, android_deep_link, ios_deep_link. |
