meta_ads_lead_forms_create
Creates a lead form on a Facebook Page with ordered questions, privacy-policy URL, and follow-up URL, returning the new form ID for capturing ad leads.
Instructions
Creates a new lead form on a Facebook Page. Returns the new form_id. Mutating — not automatically reversible; record before-state with mureo_state_action_log_append if you may need to roll back. Questions is an ordered list of standard Meta types (FULL_NAME, EMAIL, PHONE_NUMBER, COMPANY_NAME, JOB_TITLE, CITY, STATE, ZIP_CODE, COUNTRY, DATE_OF_BIRTH) or CUSTOM (requires key, label, and options for dropdowns). Meta requires both privacy_policy_url and follow_up_action_url.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | Form name shown in Ads Manager and Page Lead Center. | |
| locale | No | Optional form locale (e.g. ``ja_JP``). Defaults to the Page's primary locale. | |
| reason | No | Why this change is being made: one or two sentences naming the evidence and the expected effect. Stored in the journal and on the action_log entry this call produces, for the operator and the next session. | |
| page_id | Yes | Facebook Page ID that will own the form. | |
| approval | No | External approval this change carries out (recorded and shown, never verified) | |
| expected | No | Expected effects [{metric, direction, target?, horizon_days?, primary?}], exactly one primary:true when several; metric cpa/cpc/cpl/cpm/conversions/cvr/ctr/roas/cost/spend/clicks/impressions; direction up/down/hold. | |
| questions | Yes | Ordered question list. Standard-type questions only need `type`; CUSTOM questions require `key`, `label`, and (for dropdowns) `options`. | |
| 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. | |
| decision_id | No | A proposed decision this change carries out. | |
| context_card | No | Optional intro / welcome screen shown before the form. Lifts conversion rate measurably when supplied. Expected keys: title, content, style (PARAGRAPH_STYLE or LIST_STYLE), cover_photo_id. cover_photo_id is a PAGE photo id picked from meta_ads_pages_photos_list and is write-only: Meta reads it back as context_card.cover_photo.id ({id, created_time}), and asking for context_card{cover_photo_id} is rejected. | |
| thank_you_page | No | Optional custom completion screen with a CTA. Richer than follow_up_action_url's plain redirect, but does not replace it — Meta still requires follow_up_action_url. Expected keys: title, body, button_type (VIEW_WEBSITE / CALL_BUSINESS / MESSAGE_BUSINESS / DOWNLOAD / DOWNLOAD_APP), website_url, button_text. | |
| is_higher_intent | No | When true, Meta renders a 3-step form (input → review → submit) which trims junk submissions at the cost of total leads volume. Default false (single-step). | |
| privacy_policy_url | Yes | HTTPS URL of the advertiser's privacy policy. Required by Meta policy — forms without one are rejected. | |
| follow_up_action_url | Yes | URL the user is sent to from the completion screen (e.g. thank-you page). Required by Meta — omitting it fails with error_subcode 1892085 'Missing field(s): FollowUpActionURL'. thank_you_page adds a richer completion screen but does not replace this field. | |
| conditional_questions_choices | No | Branching logic — given a prior question's value, choose which question to ask next. Each entry: {question: <key>, value: <choice>, next_question_key: <key>}. Meta validates the keys refer to real questions. |