structured_data | array (also accepts a comma-separated string) | Yes | - | Structured data containing catalog ad information. Each row represents one catalog ad. Required columns: adset_id, product_set_id, ad_name, website_url, primary_text, headline. Optional columns: primary_text_2 through primary_text_5, headline_2 through headline_5, and description_2 through description_5 (additional text variations, Meta picks the best combination per viewer; primary_text_1/headline_1/description_1 are accepted as aliases of the bare columns), description, url_parameters, ad_status (ACTIVE/PAUSED), ad_type (carousel/single_image), carousel_card_type (use value ‘slideshow’ to enable slideshow cards; any other value ignored), format_option (Meta card layout, sent as given: ‘carousel_images_multi_items’ shows several product images per card, ‘carousel_images_single_item’ one image per card and needs multi_share_end_card false, ‘carousel_slideshows’ slideshow cards; takes precedence over carousel_card_type), multi_share_end_card (only set FALSE by putting ‘false’; omitted otherwise), show_multiple_images (only set TRUE by putting ‘true’; omitted otherwise), static_card_media_url, static_card_headline, static_card_description (if static_card_media_url AND static_card_headline provided, a static card is prepended as first child attachment; supports both images and videos; description optional), call_to_action (optional, e.g. SHOP_NOW, LEARN_MORE, SIGN_UP; defaults to SHOP_NOW if omitted or invalid), disable_creative_enhancements (set to True to disable Meta’s automatic creative optimizations like enhanced CTAs, image cropping, text optimizations, dynamic media, etc.), disable_multi_advertiser_ads (set to True to opt out of showing your ad alongside other ads), is_ai_generated (set to True to mark the row’s videos as AI-generated through Meta’s is_ai_generated upload flag; Meta does not document its effect, and images have no such flag), ad_start_time (schedule ad start, format: YYYY-MM-DD HH:MM or YYYY-MM-DD, in the ad account’s timezone), ad_end_time (schedule ad end, format: YYYY-MM-DD HH:MM or YYYY-MM-DD, in the ad account’s timezone). For single image ads set ad_type to ‘single_image’ which internally sets force_single_link=true. Case-insensitive matching is applied for ad_type, carousel_card_type, and the boolean flags. Note: user can provide direct media URLs or Google Drive share links; Markifact will convert Drive links to direct URLs automatically, the only requirement is that the file sharing is set to ‘Anyone with the link’. |
creative_only | boolean | No | False | Set to true to create only the Meta ad creative without creating an ad. Useful when editing an existing ad: create a new catalog creative with the updated product set, static card, text, or template data, then attach it using replace_ad_creative. When true, adset_id is not required since you’re not creating a new ad, just an ad creative. Returns creative IDs instead of ad IDs. Default is false. |