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 image, one headline, one primary text), ‘bulk’ (one or many ads from structured_data). Bulk unlocks features the single form does not have: multiple headlines and primary texts (headline_1-5, primary_text_1-5), placement-specific images (story, right column), 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’ |
image_url | string | No | - | Image to use for the ad. Accepts a direct image URL or a Google Drive share link. If a Drive link is provided, Markifact automatically converts it to a direct image URL. The only requirement is that the file sharing is set to ‘Anyone with the link’. For placement-specific images (story, right column), use bulk mode. |
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). |
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 (image templates, touchups, 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 text, URL, image, video, or carousel payload, 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’. Supports multiple images with clear naming: ‘image_url’ or ‘default_image_url’ (all placements), ‘story_image_url’ (story placements), ‘right_column_image_url’ (right column placements). Also supports multiple text variations (headline_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’ and ‘ad_end_time’ (schedule individual ads, format: YYYY-MM-DD HH:MM or YYYY-MM-DD, uses ad account timezone; only works for sales and app promotion campaigns). 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=0#gid=0 |
