meta_ads_creatives_create_lead
Creates a Lead Ad creative for a Meta Instant Form. Requires an existing form, page, and HTTPS fallback URL. Returns the new creative's ID.
Instructions
Creates a Lead Ad AdCreative attached to a Meta Instant Form. Returns the new creative's id and object_story_id. Mutating — not automatically reversible; record before-state with mureo_state_action_log_append if you may need to roll back. Use under a campaign with objective=OUTCOME_LEADS and an ad set with optimization_goal=LEAD_GENERATION. Pre-requisite: the lead form must exist (create via meta_ads_lead_forms_create) and belong to the same Facebook Page. link_url is the fallback landing page for placements where the in-app form cannot render; it must be HTTPS and domain-verified on the ad account.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| account_id | No | Meta Ads account ID in the format 'act_XXXXXXXXXX' (e.g. 'act_1234567890'). Optional — falls back to META_ADS_ACCOUNT_ID from the configured credentials. The leading 'act_' prefix is required. | |
| name | Yes | Creative name shown in Ads Manager. Internal label — not visible to end users. | |
| page_id | Yes | Facebook Page ID that the ad will be published as. Must be a page the authenticated user has permission to post from. Required by Meta for every creative — ads cannot run without a page identity. | |
| form_id | Yes | Lead Form ID returned by meta_ads_lead_forms_create or listed via meta_ads_lead_forms_list. The form must belong to the supplied page_id. | |
| link_url | Yes | Fallback destination URL for placements where the in-app form cannot render. Must be HTTPS and domain-verified on the ad account. | |
| image_url | No | Public HTTPS image URL. Auto-uploaded to image_hash. Mutually exclusive with image_hash. | |
| image_hash | No | Pre-uploaded image hash from meta_ads_creatives_upload_image / meta_ads_images_upload_file. Mutually exclusive with image_url. In video mode (when video_id is set), used as the video thumbnail. | |
| video_id | No | Pre-uploaded video ID from meta_ads_videos_upload / meta_ads_videos_upload_file. When supplied, the creative becomes a video Lead Ad — object_story_spec.video_data is used (not link_data) and lead_gen_form_id is nested under call_to_action.value. image_url is rejected in video mode; supply image_hash directly as the thumbnail. | |
| message | No | Primary ad body text shown above the creative. Plain text, emoji allowed. ≤125 characters fits most placements without truncation. | |
| headline | No | Headline shown with the creative. ~40 characters fits most placements. Mapped to link_data.name in image mode and video_data.title in video mode. | |
| description | No | Link-caption text shown below the headline. Optional; not all placements render it. | |
| call_to_action | No | CTA button label. SIGN_UP is the canonical Lead Ad CTA and the default. Choose the one that matches the form's purpose. |