Meta / Facebook Developer Docs Mirror

Appearance

Mirrored from https://developers.facebook.com/documentation/ads-commerce/marketing-api/guides/lead-ads/create

Lead Forms for Ads ​

Updated: Mar 26, 2026

This document describes how to use the Marketing API to create ads for lead generation using the Graph API.

To create and publish a lead ad you will follow these steps:

  • Create an ad campaign
  • Create an ad set that links your ads to your ad campaign
  • Create a lead form
  • Create an ad creative with the lead form
  • Associate your campaign and creative to create an ad
  • Publish your ad

Before You Start ​

This guide assumes you have read the Messenger Platform Overview and implemented the needed components for sending and receiving messages and notifications.

You will need the following:

Step 1. Create a campaign ​

To create an ad campaign for your lead generation ads, send a POST request to the /act_AD_ACCOUNT_ID/campaigns endpoint with the following parameters:

  • access_token set to your Page access token
  • buying_type set to AUCTION
  • name set to the name for your campaign
  • objective set to OUTCOME_LEADS
  • special_ad_categories set to NONE or your special ad category
  • status set to PAUSED

Example Request ​

Formatted for readability. Replace bold, italics values, such as AD_ACCOUNT_ID, with your values.

curl -X POST "https://graph.facebook.com/v25.0/act_AD_ACCOUNT_ID/campaigns" \
     -H "Content-Type: application/json" \
     -d '{
           "access_token":"YOUR_PAGE_ACCESS_TOKEN",
           "buying_type":"AUCTION",
           "name":"YOUR_LEADADS_CAMPAIGN_NAME",
           "objective":"OUTCOME_LEADS",
           "special_ad_categories":["NONE"],
           "status":"PAUSED"
         }'

On success, your app will receive a JSON object with the ID for your campaign. This ID will be used when creating an ad set in the next step.

{
  "id": "YOUR_CAMPAIGN_ID"
}

Visit the Ad Campaigns reference to learn more.

Step 2. Create an ad set ​

To create an ad set, send a POST request to the act_ad_account_id/adsets endpoint where ad_account_id is the ID for your Meta ad account. Your request must include:

  • access_token set to your Page access token
  • bid_amount set to the maximum amount you want to pay
  • billing_event set to IMPRESSIONS
  • campaign_id set to the ID for your ad campaign from Step 1
  • daily_budget set to the amount you want to spend per day
  • name set to the name for your ad set
  • optimization_goal set to LEAD_GENERATION, or QUALITY_LEAD
  • destination_type set to ON_AD
  • promoted_object – set to the ID for your business' Facebook Page
  • status set to PAUSED

Note: If you have set up a CRM data source and choose QUALITY_LEAD as an optimization goal, you may add the pixel_id to the promoted_object for further optimization on quality. Note that you do not need to supply a pixel_rule alongside the pixel_id.

Example Request ​

Formatted for readability. Replace bold, italics values, such as AD_ACCOUNT_ID, with your values.

curl -X POST "https://graph.facebook.com/v25.0/act_AD_ACCOUNT_ID/adsets"
     -H "Content-Type: application/json"
     -d '{
           "access_token":"YOUR_PAGE_ACCESS_TOKEN",
           "bid_amount":"YOUR_BID_AMOUNT",
           "billing_event":"IMPRESSIONS",
           "campaign_id":"YOUR_CAMPAIGN_ID",
           "daily_budget":"YOUR_DAILY_BUDGET",
           "name:"YOUR_LEADADS_ADSET_NAME",
           "optimization_goal":"LEAD_GENERATION",
           "destination_type":"ON_AD",
           "promoted_object":"YOUR_PAGE_ID",
           "status":"PAUSED"
         }'

On success your app receives the following JSON response with the ID for the ad set.

{
  "id": "YOUR_ADSET_ID"
}

Visit the Ad Sets reference to learn more.

Step 3. Create a Lead Form ​

To create a form send a POST request to the /PAGE_ID/leadgen_forms endpoint with the following parameters:

  • access_token set to your Page access token
  • name set to the name for your form
  • questions set to an array of objects defining the type of questions and the order they will appear in the form using the key parameter
    • a custom question using the label parameter
    • a custom question using the options parameter with a dropdown menu of answers

Example Request ​

Formatted for readability. Replace bold, italics values with your values.

curl -X POST "https://graph.facebook.com/v25.0/PAGE_ID/leadgen_forms" \
     -H "Content-Type: application/json" \
     -d '{
           "access_token": "YOUR_PAGE_ACCESS_TOKEN",
           "name": "YOUR_LEADADS_FORM_NAME",
           "questions": "[
               {"type":"FULL_NAME", "key": "question1"},
               {"type":"EMAIL", "key": "question2"},
               {"type":"PHONE", "key": "question3"},
               {"type":"CUSTOM", "key": "question4" "label": "Do you like rainbows?"}
               {"type":"CUSTOM", "key": "question5" "label": "What is your favorite color?",
                   "options": [
                       {value: "Red", key: "key1"},
                       {value: "Green", key: "key2"},
                       {value: "Blue", key: "key2"},
                   ]}
           ]"
         }'

Forms for Messenger Conversations ​

Forms that you want to use in an ad in a Messenger conversation must contain the following:

  • The questions.type parameter can only be set to one of the following values:

    • CUSTOM

    • EMAIL

    • FIRST_NAME

    • FULL_NAME

    • LAST_NAME

    • PHONE

    If the form has a questions.type that is set to any other value than those listed, the form will be ineligible.

  • The block_display_for_non_targeted_viewer parameter must be set to false. This marks the form as Open Sharing.

Eligible Messenger Lead Form Example Request ​

Formatted for readability. Replace bold, italics values with your values.

curl -X POST "https://graph.facebook.com/v25.0/PAGE_ID/leadgen_forms" \
     -H "Content-Type: application/json" \
     -d '{
           "access_token": "YOUR_PAGE_ACCESS_TOKEN"
           "block_display_for_non_targeted_viewer": "false"
           "name": "LeadAds Form for Messenger Conversation Name"
           "questions": "[
               {"type":"FULL_NAME", "key": "question1"},
               {"type":"EMAIL", "key": "question2"},
               {"type":"PHONE", "key": "question3"},
               {"type":"CUSTOM", "key": "question4" "label": "Do you like rainbows?"}
               {"type":"CUSTOM", "key": "question5" "label": "What is your favorite color?",
                   "options": [
                       {value: "Red", key: "key1"},
                       {value: "Green", key: "key2"},
                       {value: "Blue", key: "key2"},
                   ]}
           ]"
         }'

Additional Question Types ​

In addition to the typical question types shown in the [Create a Lead Form section]{#create-a-lead-form}, you can add more specialized question types for the following use cases:

  • Appointment Scheduling - An appointment scheduling question renders a date and time selector with a limited hour selection and a confirmation message below the question.
  • National or Government ID – A national ID question renders a question based on a person's country and validates the format of the ID entered.
  • Store Locator - A store locator question renders a store locator selector based on a person's zip code or postal code input.

Appointment Scheduling ​

An appointment scheduling question renders a date and time selector with a limited hour selection and a confirmation message below the question.

To add an appointment scheduling question, add a question object with the type parameter set to DATE_TIME. Optionally, you can also add a confirmation message in the inline_context parameter that will be rendered directly below the question field for further context, if needed.

...
           "questions": "[
               ...
               {"type": "DATE_TIME",
                "label": "Appointment time",
                "inline_context": "We will verify and call you to confirm your appointment."
               },
...

National ID ​

A national ID question renders a question based on a person's country and validates the format of the ID entered. This question can be rendered for the following countries:

  • Argentina – {"type": "ID_AR_DNI"}
  • Brazil – ID_CPF
  • Chile – ID_CL_RUT
  • Colombia – ID_CO_CC
  • Ecuador – ID_EC_CI
  • Peru – ID_PE_DNI

To add a national ID question, add a question object with the type parameter set to the person's country type.

Limitations ​

  • You can only ask for a single National ID in any given form and are only able to target people in their corresponding country. For example, if you ask for DNI from Peru, your target audience must be limited to Peru. Only ads that match these criteria are approved.
  • Validation checks for a valid format; it does not verify that the ID actually belongs to a real person.
...
           "questions": "[
               ...
               {"type": "ID_AR_DNI"
               },
...

Store Locator ​

A store locator question renders a store locator selector based on a person's zip code or postal code input.

You will need to set up a Store Pages Structure to use this question. Learn how in Set Up a Store Pages Structure on Facebook – Meta Business Help Center⁠

To add a store locator question, add a question object with the type parameter set to STORE_LOOKUP and the context_provider_type parameter to LOCATION_MANAGER.

...
           "questions": "[
               ...
               {"type": "STORE_LOOKUP",
                "label": "Which store do you want to visit?",
                "context_provider_type": "LOCATION_MANAGER"
               },
...

Advanced Form Settings ​

Get higher quality leads by adding one or more of the following form settings:

Add Performance Tracking ​

To help you track the source of your leads, add the tracking_parameters field, set to a list of key-value pairs of parameters you want to track, to your form. These parameters do not appear in your ad but allow Meta to provide you with metadata about leads generated from a form.

Example Request ​

Formatted for readability. Replace bold, italics values with your values.

...
           "name": "YOUR_LEADADS_FORM_NAME",
           "tracking_parameters": {"your_tracking_parameter_name":"your_tracking_parameter_value"},
           "questions": "[
...

Add Higher Intent Setting ​

By default, lead ads are optimized for the volume of leads, however, you can create forms that result in higher intent leads. These types of leads can be for people who may be interested in a specific product or service, such as booking a test drive at a dealership. This form setting adds a step to the form submission flow where a person reviews and confirms their answers before the person submits the form.

To add this confirmation flow to your form, add the is_optimized_for_quality parameter set to true when creating the form.

Example Request ​

Formatted for readability. Replace bold, italics values with your values.

...
           "name": "YOUR_LEADADS_FORM_NAME",
           "is_optimized_for_quality": "true",
           "questions": "[
...

Filter Out Organic Leads ​

To filter out organic leads, add the block_display_for_non_targeted_viewer parameter to true when you create the form.

Example Request ​

Formatted for readability. Replace bold, italics values with your values.

...
           "name": "YOUR_LEADADS_FORM_NAME",
           "block_display_for_non_targeted_viewer": "true",
           "questions": "[
...

Example Response ​

On success your app will receive a JSON response containing the ID for your form to be used when creating your ad.

{
  "id": "leadgen_form_id",
}

Gated Content ​

Reward consumers with a file download after submitting their lead. This file download will appear as a call-to-action button on your thank you page.

To add this feature, you must add the upload_gated_file parameter to your form with the file that you'd like to upload.

In addition, you must create a thank you page using the thank_you_page parameter. Within the thank_you_page parameter, set button_type to VIEW_ON_FACEBOOK.

Example Request ​

Formatted for readability. Replace bold, italics values with your values.

...
  "name": "YOUR_LEADADS_FORM_NAME",
      "upload_gated_file": "YOUR_FILE",
      "thank_you_page": {
         "body": "Feel free to download our brochure here",
         "title": "Thanks, you're all set.",
         "button_type": "VIEW_ON_FACEBOOK",
         "button_text": "Download"
      }
    ...

Example Response ​

On success, your app will receive a JSON response containing the ID for your form to be used when creating your ad.

{
  "id": "leadgen_form_id",
}

Step 4. Create an Ad Creative ​

To create an ad creative with an image and your form, send a POST request to the /act_AD_ACCOUNT_ID/adcreatives endpoint with the following parameters:

  • access_token set to your Page access token
  • object_story_spec that includes a link_data object with the following parameters:
    • call_to_action set to an object containing type andvalue set to your lead form ID
    • description set to the description for your creative
    • image_hash set to the hash for an image for your ad creative
    • message set to the text for your ad creative
  • page_id set to your Facebook Page ID

Note: While creating the link_data, the value associated with the link field can only be https://fb.me/.

The link_data.call_to_action parameter must be set to one of the following values:

  • APPLY_NOW
  • DOWNLOAD
  • GET_QUOTE
  • LEARN_MORE
  • SIGN_UP
  • SUBSCRIBE

Example Request ​

Formatted for readability. Replace bold, italics values, such as AD_ACCOUNT_ID, with your values.

curl -X POST "https://graph.facebook.com/LATEST-API-VERSION/act_AD_ACCOUNT_ID/adcreatives" \
     -H "Content-Type: application/json" \
     -d '{
           "access_token":"YOUR_PAGE_ACCESS_TOKEN",
           "object_story_spec":{
             "link_data": {
               "call_to_action": {
                 "type":"SIGN_UP",
                 "value":{
                   "lead_gen_form_id":"YOUR_FORM_ID"
                 }
               },
               "description": "YOUR_AD_CREATIVE_DESCRIPTION",
               "image_hash": "YOUR_IMAGE_HASH",
               "link": "http:\/\/fb.me\/",
               "message": "YOUR_AD_CREATIVE_MESSAGE"
             },
           "page_id": "YOUR_PAGE_ID"
         }'

You can create a carousel lead ad using the same object_story_spec, but with an additional lead_gen_form_id field defined in the child_attachments parameter.

You can only specify the same <FORM_ID> for all child attachments.

curl \
  -F 'object_story_spec={
    "page_id": "<PAGE_ID>",
    "link_data": {
      "message": "My description",
      "link": "http:\/\/www.google.com",
      "caption": "WWW.EXAMPLE.COM",
      "child_attachments": [
        {
          "link": "http:\/\/www.google.com",
          "image_hash": "<IMAGE_HASH>",
          "call_to_action": {"type":"SIGN_UP","value":{"lead_gen_form_id":"<FORM_ID>"}​}
        },
        {
          "link": "http:\/\/www.google.com",
          "image_hash": "<IMAGE_HASH>",
          "call_to_action": {"type":"SIGN_UP","value":{"lead_gen_form_id":"<FORM_ID>"}​}
        },
        {
          "link": "http:\/\/www.google.com",
          "image_hash": "<IMAGE_HASH>",
          "call_to_action": {"type":"SIGN_UP","value":{"lead_gen_form_id":"<FORM_ID>"}​}
        },
        {
          "link": "http:\/\/www.google.com",
          "image_hash": "<IMAGE_HASH>",
          "call_to_action": {"type":"SIGN_UP","value":{"lead_gen_form_id":"<FORM_ID>"}​}
        }
      ],
      "multi_share_optimized": true,
      "call_to_action": {"type":"SIGN_UP","value":{"lead_gen_form_id":"<FORM_ID>"}​}
    }
  }' \
  -F 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/LATEST-API-VERSION/act_<AD_ACCOUNT_ID>/adcreatives

With a Video ​

You can also use a video in the lead ad creative instead of a photo. First, upload the video to your ad video library, then use it in the object_story_spec parameter:

curl -X POST \
  -F 'object_story_spec={
       "page_id": "<PAGE_ID>",
       "video_data": {
         "link_description": "try it out",
         "image_url": "<IMAGE_URL>",
         "video_id": "<VIDEO_ID>",
         "call_to_action": {
           "type": "SIGN_UP",
           "value": {
             "link": "http://fb.me/",
             "lead_gen_form_id": "<FORM_ID>"
           }
         }
       }
     }' \
  -F 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v25.0/act_<AD_ACCOUNT_ID>/adcreatives

Ad Creative Example Response ​

On success your app receives the following JSON response with the ID for the ad creative.

{
  "id": "YOUR_AD_CREATIVE_ID"
}

Step 5. Create the Ad ​

To create the ad you need to associate the ad creative and the ad set. To create the ad, send a POST request to the /act_AD_ACCOUNT_ID/ads endpoint. Your request must include:

  • access_token set to your Page access token
  • adset_id (from Step 2)
  • creative_id (from Step 4)
  • name
  • status

Ad with Creative Example Request ​

Formatted for readability. Replace bold, italics values, such as AD_ACCOUNT_ID, with your values.

curl -X POST "https://graph.facebook.com/v25.0/act_AD_ACCOUNT_ID/ads"
     -H "Content-Type: application/json"
     -d '{
           "access_token"="YOUR_PAGE_ACCESS_TOKEN",
           "name":"YOUR_LEADADS_AD_NAME",
           "adset_id"="YOUR_AD_SET_ID",
           "creative"={ "creative_id": "YOUR_AD_CREATIVE_ID" },
           "status"="PAUSED"
         }'

On success your app receives the following JSON response with the ID for the ad.

{
  "id": "YOUR_AD_ID"
}

Step 6. Publish your Ad ​

Verify that your ad exists in the Ads Manager⁠. Click the Review and publish button in the upper right corner. Select your campaign, the ad set for the campaign, and the ad.

You can publish your ad from the ads manager or using the API. To publish using the API, repeat Step 4 with the status parameter set to ACTIVE.

Your ad will be reviewed by Meta and the status will be PENDING_REVIEW. Once approved, the status will be ACTIVE and your ad will be delivered.

Form Management ​

Get a list of your forms, a specific forms questions, and archive old forms.

Get a List of Forms ​

To get a list of your lead gen forms, send a GET request to the /page_id/leadgen_forms endpoint with the following parameters:

  • access_token set to your Page access token
  • fields (optional) set to a comma separated list of fields to get specific information such as name and form ID

Example Request ​

Formatted for readability. Replace bold, italics values with your values.

curl -X GET "https://graph.facebook.com/v25.0/PAGE_ID/leadgen_forms
    ?fields=name,id
    &access_token": "YOUR_PAGE_ACCESS_TOKEN"

On success your app will receive a JSON response containing a list of your forms. You can use a form ID to get the questions for that form or to archive the form.

Get a List of Eligible Forms for Messenger ​

Only forms containing specific requirements are eligible to be sent in a Messenger conversation.

To get a list of eligible lead forms send a GET request to the /page_id/leadgen_forms endpoint with the following parameters:

  • access_token set to your Page access token
  • fields set to is_eligible_for_in_thread_forms

Example Request ​

Formatted for readability. Replace bold, italics values with your values.

curl -X GET "https://graph.facebook.com/v25.0/PAGE_ID/leadgen_forms
    ?fields=is_eligible_for_in_thread_forms
    &access_token": "YOUR_PAGE_ACCESS_TOKEN"

On success your app will receive a JSON response containing a list of IDs for eligible forms.

{
  "data": [
    {
      "id": "eligible_form_1_id"
    },
    {
      "id": "eligible_form_2_id"
    }
  ],
...
}

Get a List of Questions ​

To get a list of questions for a specific lead gen form, send a GET request to the /page_id/leadgen_form_id endpoint with the following parameters:

  • access_token set to your Page access token
  • fields set to questions

Example Request ​

Formatted for readability. Replace bold, italics values with your values.

curl -X GET "https://graph.facebook.com/v25.0/page_id/leadgen_form_id?fields=questions
&access_token=page_access_token"

On success your app will receive a JSON response containing a list of questions.

Archive a Form ​

You can only archive a lead form since deleting is not supported. Once a form is archived:

  • The form won't appear (by default) in the Forms Library
  • You can't use an archived form in an ad, attempting to do so can generate an error via the API.
  • Archived forms won't be available during ad creation for CF or PE.

To archive a specific lead gen form, send a POST request to the /page_id/leadgen_form_id endpoint with the following parameters:

  • access_token set to your Page access token
  • status set to ARCHIVED

Example Request ​

Formatted for readability. Replace bold, italics values with your values.

curl -X GET "https://graph.facebook.com/v25.0/page_id/leadgen_form_id?status=ARCHIVED
&access_token=page_access_token"

On success your app will receive a JSON response containing an object with success set to true.

An archived form can be reactivated by sending a request with status set to ACTIVE.

See Also ​

Visit our other guides to learn more about the components in this document.

Marketing API Developer Documentation ​

Meta Business Help Center ​

Unofficial mirror for reference/search purposes. All content originates from developers.facebook.com — see the source link at the top of each page. Machine-readable indexes: llms.txt · llms-full.txt · About

Content © Meta Platforms, Inc. · Built by Arjun Aditya