page | SelectItem | Yes | - | Select the Facebook page to create the lead form on, ask the user for it if not provided |
name | string | Yes | - | Form name, must be unique per page. Forms cannot be edited after creation, only archived. |
questions | array of object or string | Yes | - | Lead form questions, sent to Meta as-is (Meta leadgen_forms reference). Each item needs type: prefill types like EMAIL, FULL_NAME, FIRST_NAME, LAST_NAME, PHONE, WORK_EMAIL, JOB_TITLE, COMPANY_NAME, CITY, STATE, ZIP, COUNTRY, DOB, GENDER, WEBSITE, WHATSAPP_NUMBER, STREET_ADDRESS auto-fill from the user’s profile; CUSTOM is for qualifying questions and needs label, plus options ([{value, key?}]) for multiple choice or no options for free text. Advanced keys (inline_context, dependent_conditional_questions, conditional_questions_group_id) pass through unchanged. Example: [{“type”: “FULL_NAME”}, {“type”: “EMAIL”}, {“type”: “CUSTOM”, “label”: “Monthly budget?”, “options”: [{“value”: “Under 1,000"}, \{"value": "Over 1,000”}]}] |
privacy_policy | object or string | No | - | Sent to Meta as-is: {url, link_text?}. url is a public https privacy policy page, link_text max 70 characters. Meta requires it whenever the form collects personal information. Example: {“url”: “https://example.com/privacy”, “link_text”: “Privacy Policy”} |
context_card | object or string | No | - | Optional intro card shown before the questions, sent to Meta as-is: {title?, style? (LIST_STYLE or PARAGRAPH_STYLE), content? (list of strings), button_text?}. Example: {“title”: “Get a free audit”, “style”: “LIST_STYLE”, “content”: [“Free 30-min call”, “No commitment”], “button_text”: “Get Started”} |
thank_you_page | object or string | No | - | Optional completion screen, sent to Meta as-is. title and button_type are required inside it; button_type is one of VIEW_WEBSITE, CALL_BUSINESS, MESSAGE_BUSINESS, DOWNLOAD, SCHEDULE_APPOINTMENT, VIEW_ON_FACEBOOK, PROMO_CODE, NONE, WHATSAPP, P2B_MESSENGER, BOOK_ON_WEBSITE. website_url is needed for website/download buttons, business_phone_number for CALL_BUSINESS. Other keys (body, short_message, button_text, button_description, country_code, enable_messenger, gated_file) pass through unchanged. Example: {“title”: “Thanks!”, “body”: “We will reach out soon.”, “button_type”: “VIEW_WEBSITE”, “button_text”: “Visit site”, “website_url”: “https://example.com”} |
custom_disclaimer | object or string | No | - | Optional custom disclaimer with consent checkboxes, sent to Meta as-is: {title?, body? ({text, url_entities?}), checkboxes? ([{text, is_required?, is_checked_by_default?, key?}])}. Example: {“title”: “Consent”, “body”: {“text”: “By submitting you agree to be contacted.”}, “checkboxes”: [{“text”: “Send me marketing emails”, “is_required”: false}]} |
follow_up_action_url | string | No | - | Website URL opened from the default thank-you screen. Meta rejects the form (error subcode 1892085, Missing field(s): FollowUpActionURL) unless this is set or thank_you_page includes a website button with website_url. |
locale | string | No | - | Form locale code, e.g. EN_US, EN_GB, ES_ES, ES_LA, FR_FR, DE_DE, PT_BR, IT_IT, NL_NL, AR_AR. See Meta’s leadgen_forms reference for the full list. |
question_page_custom_headline | string | No | - | Custom headline shown on the questions page |
cover_photo_id | string | No | - | ID of an existing photo to use as the form cover |
is_optimized_for_quality | boolean | No | - | True for the higher-intent form type (adds a review step); default is more volume |
is_phone_sms_verify_enabled | boolean | No | - | |
should_enforce_work_email | boolean | No | - | |
block_display_for_non_targeted_viewer | boolean | No | - | Prevent people outside the ad audience from opening the form organically |
tracking_parameters | object or string | No | - | Key-value tracking parameters included with each lead, e.g. {“utm_source”: “facebook”} |
is_for_canvas | boolean | No | - | |
is_lead_capture_ai_agent_enabled | boolean | No | - | |
