account | DynamicAccount | Yes | - | Select the Meta Ads account, ask the user for it if not provided |
update_type | string or SelectableOption | Yes | - | Choose how to create ads. Available options: ‘single’ (one ad with one video, one headline, one primary text), ‘bulk’ (one or many ads from structured_data). Bulk unlocks features the single form does not have: multiple headlines, titles, and primary texts (headline_1-5, title_1-5, primary_text_1-5), a placement-specific story video with its own thumbnail, lead forms (form_id), pixel_id, ad scheduling (ad_start_time/ad_end_time), and sitelinks. Use bulk when an ad needs any of these. |
page | string or SelectItem | Yes | - | Select Facebook page, ask the user for it if not provided |
instagram_user_id | string or SelectItem | No | - | Optional Instagram account override. Leave empty in nearly all cases — the Instagram account linked to the selected Page is used automatically. Only set this when the user wants to advertise with a different Instagram account they have access to. Value is the numeric IG user/business account id. |
adset_id | string or SelectItem | No | - | Select the ad set for this ad, ask the user for it if not provided |
ad_name | string | No | - | Name of the ad |
ad_status | string or SelectableOption | No | - | Select the new status for the ad. Available options: ‘ACTIVE’, ‘PAUSED’ |
video_url | string | No | - | Video to use for the ad. Accepts a direct video URL or a Google Drive share link. If a Drive link is provided, Markifact automatically converts it to a direct video URL. The only requirement is that the file sharing is set to ‘Anyone with the link’. For a placement-specific story video, use bulk mode. |
thumbnail_url | string | No | - | Leave empty to use auto-generated thumbnail |
primary_text | string | No | - | The main body text of the ad. For multiple text variations, use bulk mode (primary_text_1-5 columns). |
headline | string | No | - | The headline of the ad. For multiple headline variations, use bulk mode (headline_1-5 columns). |
title | string | No | - | The title of your video ad |
description | string | No | - | Additional text that appears below the headline |
website_url | string | No | - | The URL where people will go when they click your ad (e.g., https://example.com) |
call_to_action | string or SelectableOption | No | - | Select a call to action button for the ad: Some Options: ‘LEARN_MORE’, ‘SHOP_NOW’, ‘BOOK_TRAVEL’, ‘DOWNLOAD’, ‘GET_QUOTE’, ‘CONTACT_US’, ‘APPLY_NOW’, ‘SIGN_UP’ |
url_parameters | string | No | - | Add UTM or other tracking parameters to your URL (e.g., utm_source=facebook&utm_medium=cpc) |
disable_creative_enhancements | boolean | No | - | Set to True to disable Meta’s automatic creative enhancements (video auto-crop, image templates, text optimizations, dynamic media etc.) |
disable_multi_advertiser_ads | boolean | No | - | Set to True to opt out of Meta’s multi-advertiser ads feature, which shows your ad alongside other ads. By default, Meta enables this feature. |
display_url | string | No | - | A custom display URL shown on the ad instead of the actual website URL (e.g., ‘example.com’). This is cosmetic only and does not affect the landing page. |
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 creative with the updated video, thumbnail, text, URL, or CTA, 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. |
return_detailed_results | boolean | No | False | Bulk mode only. If true, returns per-row results (success_count, failed_count, total_count, results[]) and does NOT raise an error on partial failures so the workflow can continue. If false (default), returns a simple summary and raises an error if any row fails. |
structured_data | array (also accepts a comma-separated string) | No | - | Use only when update_type is ‘bulk’. This will mainly be the output of a Google Sheets read operation. Supports multiple videos with clear naming: ‘video_url’ or ‘default_video_url’ (all placements), ‘story_video_url’ (story placements). Optional custom thumbnails: ‘thumbnail_url’ or ‘default_thumbnail_url’ (for default video), ‘story_thumbnail_url’ (for story video). Also supports multiple text variations (headline_1-5, title_1-5, primary_text_1-5) and single ‘description’ field. For lead form ads, include ‘form_id’ field. Optional: ‘disable_creative_enhancements’ (set to True to disable Meta’s automatic creative optimizations), ‘disable_multi_advertiser_ads’ (set to True to opt out of showing your ad alongside other ads), ‘pixel_id’ (optional, leave empty to inherit from adset and account), ‘display_url’ (optional, a custom display URL shown on the ad instead of the actual website URL, e.g. ‘example.com’), ‘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). Optional sitelinks (bulk only): leave all ‘sitelink_*’ columns blank to skip the feature. To use sitelinks, Meta requires between 4 and 20 per ad. For each one, fill in ‘sitelink_N_title’ and ‘sitelink_N_url’ (N = 1..20); ‘sitelink_N_image_url’ is optional and accepts a direct URL or Google Drive share link. If ‘sitelink_1_title’ starts with the word ‘Optional’ (i.e. the template’s instruction text was not cleared), all sitelinks are skipped for that row. Suggest this template for user: https://docs.google.com/spreadsheets/d/1yAE2JDqxLFGCyHjjIQsvxn240B-ekg0B3eqcsssMQOQ/edit?gid=1444761059#gid=1444761059 |
