Lead Forms for Ads

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

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

1. Create an ad campaign
2. Create an ad set that links your ads to your ad campaign
3. Create a lead form
4. Create an ad creative with the lead form
5. Associate your campaign and creative to create an ad
6. Publish your ad

Before You Start

You will need the following:

• The ads_management permission
• The pages_manage_ads permission
• The pages_read_engagement permission
• The pages_show_list permission
• A Page access token from a person who can perform the ADVERTISE task on the Page

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 catergory
• status set to PAUSED

Example Request

curl -X POST "https://graph.facebook.com/v21.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 amout your 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 with the pixel_id.

Example Request

curl -X POST "https://graph.facebook.com/v21.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

curl -X POST "https://graph.facebook.com/v21.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

curl -X POST "https://graph.facebook.com/v21.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 speciaized 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 this 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:

• Form Performance Tracking to track the source of your leads
• Higher Intent Forms to add a review and confirm step in the form flow
• Organic Leads Filtering to filter out organic leads

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

...
           "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

...
           "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

...
           "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",
}

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

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" 
         }'
  

With a Carousel

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.

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/v21.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 included:

• 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

curl -X POST "https://graph.facebook.com/v21.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

curl -X GET "https://graph.facebook.com/v21.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

curl -X GET "https://graph.facebook.com/v21.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

curl -X GET "https://graph.facebook.com/v21.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

curl -X GET "https://graph.facebook.com/v21.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

• Lead Generation UI Dialog SDK components
• Page Reference, Leadgen Forms
• Tracking and Conversion Specs, Custom Tracking Specs

Meta Business Help Center

• Organic Leads Help Center article
• Share Button Help Center article
• Lead Form Types Help Center article
• Lead Forms in Canvas Ads Help Center article