account | DynamicAccount | Yes | - | Select the Meta Ads account, ask the user for it if not provided |
update_type | string or SelectableOption | Yes | - | Choose whether to create a single ad or multiple ads at once. Available options: ‘single’ (Single Ad), ‘bulk’ (Multiple Ads) |
page | string or SelectItem | Yes | - | Select the Facebook page that owns the post (or whose linked Instagram account owns the media). Ask the user 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 status for the new ad. Available options: ‘ACTIVE’, ‘PAUSED’ |
post_id | string | No | - | ID of the Facebook page post to advertise. Provide just the numeric post id; Markifact combines it with the selected page id automatically. Required for Facebook posts. If you want to advertise an Instagram media instead, set instagram_media_id and leave this empty. |
instagram_media_id | string | No | - | Meta Marketing API source Instagram media V2 ID for the existing Instagram post to advertise. Provide this instead of post_id only when advertising an existing Instagram post from the selected Instagram account. This must be the numeric media ID returned by Meta for that Instagram account (the value Meta accepts as source_instagram_media_id), not an Instagram permalink, shortcode, reel code, media URL, scraped media PK, post caption ID, or ad/creative ID. Uses the page-linked Instagram account by default, or the override set via instagram_user_id. |
url_parameters | string | No | - | Add UTM or other tracking parameters to the post’s link (e.g., utm_source=facebook&utm_medium=cpc) |
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 pointing at a different post, then attach it using meta_ads_replace_ad_creative. When true, adset_id is not required since you’re not creating a new ad. 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’. Mainly the output of a Google Sheets read operation. Each row should include: ‘ad_name’, ‘adset_id’ (when not creative_only), and either ‘post_id’ (Facebook post) or ‘instagram_media_id’ (Instagram media). Optional per-row fields: ‘ad_status’ (ACTIVE/PAUSED, default PAUSED), ‘url_parameters’. |
