Create Lead Forms and Ads

This page describes how you can create and manage Lead Forms and how to create Lead Ads through the API. You must use a Page access token for this API.

You can also add Facebook's Lead Form creation UI to your website using the JavaScript SDK. Learn more about the Leadgen Dialog below.

Before You Start

You will need:

the pages_read_permissions permission
the ads_management permission
a Page access token from a User who can perform the ADVERTISE task on the Page

Create a Lead Form

Create a Lead Form with questions you can display in Lead Ads; see Lead Form, Reference. You can use this API to also create a form by directly passing the parameters for Legal Content and Context Card.

use FacebookAds\Object\Fields\LeadgenFormFields;
use FacebookAds\Object\Fields\LeadgenQuestionFields;
use FacebookAds\Object\LeadgenForm;
use FacebookAds\Object\LeadGenQuestion;

$form = new LeadgenForm(null, <PAGE_ID>);
$form->setData(array(
  LeadgenFormFields::NAME => 'LeadAds Form Name',
  LeadgenFormFields::FOLLOW_UP_ACTION_URL => '<URL>',
  LeadgenFormFields::QUESTIONS => array(
    (new LeadGenQuestion())->setData(array(
      LeadgenQuestionFields::TYPE => 'EMAIL',
    )),
  ),
  'context_card_id' => <CONTEXT_CARD_ID>,
  'legal_content_id' => <LEGAL_CONTENT_ID>,
));

$form->create();

curl \
  -F 'name=LeadAds Form Name' \
  -F 'follow_up_action_url=<URL>' \
  -F 'questions=[{"type":"EMAIL"}]' \
  -F 'context_card_id=<CONTEXT_CARD_ID>' \
  -F 'legal_content_id=<LEGAL_CONTENT_ID>' \
  -F 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v2.11/<PAGE_ID>/leadgen_forms

You can include a lead form in canvas ad campaigns that you run with BRAND_AWARENESS, REACH and traffic objectives. For background see, Ads Help Center, Collect leads using a Facebook Canvas instant form and Canvas and Lead Ads.

When you create your lead form, you should also provide legal_content and you may include context_card.

As an option, you can also specify a thank_you_page. Many of the sub-fields are optional in API, except you must provide a website URL and a default value if you want to include a Thank You page:

Options include:

body - Body of the thank you page
business_phone_number - Phone number with full international number
button_text - Text shown on the call-to-action (CTA) button of static footer
button_type - This must be of type VIEW_WEBSITE, DOWNLOAD or CALL_BUSINESS.
country_code - Two-letter ISO country code that represents a specified country
title - Title of the thank you page
website_url - URL of website where Facebook redirects someone when they click the CTA button

Provide Tracking Parameters

You can use optional tracking_parameters for Lead Ads forms. These parameters do not appear in your ad, however we report these key-value pairs when you request metadata about the leads generated from the form. This enables you to better track the source of leads generated in your ads. For example:

curl \
-F context_card='{"title":"","style":"PARAGRAPH_STYLE","content":{}}' \
-F name="Demo Form" \
-F questions='[{"key":null,"type":"EMAIL"},{"key":null,"type":"FULL_NAME"}]' \
-F status=DRAFT \
-F tracking_parameters='{"param_name":"param_value"}' 'https://graph.facebook.com/<VERSION>/<PAGE_ID>/leadgen_draft_forms?access_token=<ACCESS_TOKEN>

Optimize for Intent

When you create a lead ad, by default, Facebook optimize for number of leads. However, you can provide a lead form option optimizes for higher intent. Your lead ad includes an extra review step where people can confirm their information, resulting in more intentional leads. For background see Ads Help Center, Choose the right lead form.

To use this optional, provide the boolean is_optimized_for_quality set to true. Facebook then generates a Higher Intent form with the additional review step.

If you set this to false we deliver the default form optimized for number of leads. This displays a Lead ad form that is quick to fill out and submit on a mobile device.

Filter Organic Leads

Relevant Resources

If you don't want to receive organic leads, you need to make sure you've set block_display_for_non_targeted_viewer to true in your lead form. If you don't restrict organic leads, they appear when you download or request your leads via the API.

use FacebookAds\Object\Fields\LeadgenFormFields;
use FacebookAds\Object\Fields\LeadgenQuestionFields;
use FacebookAds\Object\LeadgenForm;
use FacebookAds\Object\LeadGenQuestion;

$form = new LeadgenForm(null, <PAGE_ID>);
$form->setData(array(
  LeadgenFormFields::NAME => 'LeadAds Form Name',
  LeadgenFormFields::FOLLOW_UP_ACTION_URL => '<URL>',
  LeadgenFormFields::QUESTIONS => array(
    (new LeadGenQuestion())->setData(array(
      LeadgenQuestionFields::TYPE => 'EMAIL',
    )),
  ),
  'block_display_for_non_targeted_viewer' => true,
  'context_card_id' => <CONTEXT_CARD_ID>,
  'legal_content_id' => <LEGAL_CONTENT_ID>,
));

$form->create();

curl \
  -F 'name=LeadAds Form Name' \
  -F 'follow_up_action_url=<URL>' \
  -F 'questions=[{"type":"EMAIL"}]' \
  -F 'block_display_for_non_targeted_viewer=1' \
  -F 'context_card_id=<CONTEXT_CARD_ID>' \
  -F 'legal_content_id=<LEGAL_CONTENT_ID>' \
  -F 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v2.11/<PAGE_ID>/leadgen_forms

Add Questions

A lead form contains a section that contains headline and list of questions. General features of form questions:

You can use question_page_custom_headline to provide a custom headline for the question section of your Lead Form.

You can tokenize questions by specifying key; for example, [{type: 'EMAIL', key: 'question1'}]. If keys aren't provided, default to the value formed by concatenating every word in the question by underscore. For example, what_do_you_like.
All available question types are listed in the reference docs under questions type.

Create a Standard Question

To create a standard question, you only need to pass the PII type; for example, {type: 'EMAIL'}.

curl \
  -F 'name=LeadAds Form Name' \
  -F 'follow_up_action_url=<URL>' \
  -F 'questions=[{"type":"EMAIL"}]' \
  -F 'access_token=ACCESS_TOKEN' \
  https://graph.facebook.com/VERSION/PAGE_ID/leadgen_forms

Create a Custom Text-Input Question

To create a custom text-input question, specify label and type as follows: {label: 'This is a custom text-input question', type: 'CUSTOM'}

curl \
  -F 'name=LeadAds Form Name' \
  -F 'follow_up_action_url=<URL>' \
  -F 'questions=[{"type":"CUSTOM", "label": "This is a custom text-input question"}]' \
  -F 'access_token=ACCESS_TOKEN' \
  https://graph.facebook.com/VERSION/PAGE_ID/leadgen_forms

Create a Drop-Down Question

To create a custom drop-down question, specify label, type, and option as follows:

{label: 'This is a custom dropdown question', type: 'CUSTOM', options: [{value: 'option1', key: 'key1'}]}

curl \
  -F 'name=LeadAds Form Name' \
  -F 'follow_up_action_url=<URL>' \
  -F 'questions=[{"type":"CUSTOM", "label": "This is a custom dropdown question", "options": [{value: "option1", key: "key1"}]}]' \
  -F 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/VERSION/<PAGE_ID>/leadgen_forms

Add Conditional Questions

To add conditional questions to Lead Forms, you need to upload a CSV file representing all valid options; see the CSV example file for how this file can look like if you use conditional questions to select Country, State, and City.

First create and upload the CSV file. This returns a conditional_questions_group_id.

use FacebookAds\Api;
use FacebookAds\Http\FileParameter;
use FacebookAds\Http\RequestInterface;

$request = $this->getApi()->prepareRequest(
  '/'.<PAGE_ID>.'/leadgen_conditional_questions_group',
  RequestInterface::METHOD_POST);

$request->getFileParams()->offsetSet(
  'conditional_questions_group_csv',
  (new FileParameter('<FILENAME>'))->setMimeType("text/csv"));

$data = $this->getApi()->executeRequest($request)->getContent();

curl \
  -F 'conditional_questions_group_csv=@<FILENAME>;type=text/csv' \
  -F 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v2.11/<PAGE_ID>/leadgen_conditional_questions_group

When creating the Lead Form, create a custom questions with a label representing the first column in the CSV file, provide the conditional_questions_group_id and list dependent_conditional_questions in the order you want them selected.

use FacebookAds\Object\Fields\LeadgenFormFields;
use FacebookAds\Object\Fields\LeadgenQuestionFields;
use FacebookAds\Object\LeadgenForm;
use FacebookAds\Object\LeadGenQuestion;

$form = new LeadgenForm(null, $page_id);
$form->setData(array(
  LeadgenFormFields::NAME => 'LeadAds Form Name',
  LeadgenFormFields::FOLLOW_UP_ACTION_URL => '<URL>',
  LeadgenFormFields::QUESTIONS => array(
    (new LeadGenQuestion())->setData(array(
      LeadgenQuestionFields::TYPE => 'EMAIL',
    )),
    (new LeadGenQuestion())->setData(array(
      LeadgenQuestionFields::TYPE => 'CUSTOM',
      LeadgenQuestionFields::LABEL => 'Country',
      'conditional_questions_group_id' => <CONDITIONAL_QUESTIONS_GROUP_ID>,
      'dependent_conditional_questions' => array(
        array('name' => 'State'),
        array('name' => 'City'),
      )
    )),
  ),
  'context_card_id' => <CONTEXT_CARD_ID>,
  'legal_content_id' => <LEGAL_CONTENT_ID>,
));

$form->create();

curl \
  -F 'name=LeadAds Form Name' \
  -F 'follow_up_action_url=<URL>' \
  -F 'questions=[ 
    {"type":"EMAIL"}, 
    { 
      "type": "CUSTOM", 
      "label": "Country", 
      "conditional_questions_group_id": "<CONDITIONAL_QUESTIONS_GROUP_ID>", 
      "dependent_conditional_questions": [{"name":"State"},{"name":"City"}] 
    } 
  ]' \
  -F 'context_card_id=<CONTEXT_CARD_ID>' \
  -F 'legal_content_id=<LEGAL_CONTENT_ID>' \
  -F 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v2.11/105/leadgen_forms

Create an Appointment Scheduling Question

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

To create an appointment scheduling question, specify a label and type. Optionally, you can also add confirmation message in inline_context that will be rendered directly below the question field.

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

curl \
  -F 'name=LeadAds Form Name' \
  -F 'follow_up_action_url=<URL>' \
  -F 'questions=[{"type":"DATE_TIME", "label": "Appointment time", "inline_context": "We will verify and call you to confirm your appointment."}]' \
  -F 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/VERSION/<PAGE_ID>/leadgen_forms

Create a Store Locator Question

Reference Docs

Setting up locations

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

To create a store locator question, specify a label, type and context_provider_type as follows:

{label: 'Which dealer do you want to visit?', type: 'STORE_LOOKUP', context_provider_type: 'LOCATION_MANAGER'}

Note: To enable this feature, you must set up the appropriate location structure and map these locations against zip or postal codes.

IPv4 example:

curl \
  -F 'name=LeadAds Form Name' \
  -F 'follow_up_action_url=<URL>' \
  -F 'questions=[{"type":"STORE_LOOKUP", "label": "Which dealer do you want to visit?", "context_provider_type": "LOCATION_MANAGER"}]' \
  -F 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/VERSION/<PAGE_ID>/leadgen_forms

Create a National ID Question

You may ask people to submit their government-issued ID. Note: Validation checks for a valid format; it does not verify that the ID actually belongs to a real person.

National ID questions are added as a standard question by using the corresponding PII type; for example, {type: 'ID_AR_DNI'}. The list of available IDs is:

Type	National ID	Country
`ID_AR_DNI`	DNI	Argentina
`ID_CPF`	CPF	Brazil
`ID_CL_RUT`	RUT	Chile
`ID_CO_CC`	CC	Colombia
`ID_EC_CI`	CI	Ecuador
`ID_PE_DNI`	DNI	Peru

Note: 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.

For example, to ask for CC from Colombia, you should create a form like this:

curl \
  -F 'name=LeadAds Form Name' \
  -F 'follow_up_action_url=<URL>' \
  -F 'legal_content_id=<LEGAL_CONTENT_ID>' \
  -F 'questions=[{"type:"ID_CO_CC"}]' \
  -F 'access_token=ACCESS_TOKEN' \
  https://graph.facebook.com/VERSION/PAGE_ID/leadgen_forms

Read Lead Form

Read all forms available on a page. See reference doc for available fields; for example, questions.

use FacebookAds\Object\Page;

$page = new Page(<PAGE_ID>);
$leadgen_forms = $page->getLeadgenForms();

from facebookads.adobjects.page import Page

page = Page(<PAGE_ID>)
leadgen_forms = page.get_leadgen_forms()

curl -G \
  -d 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v2.11/<PAGE_ID>/leadgen_forms

Read All Questions

The following API call returns all available questions on a form:

All pre-fill questions
All custom created questions

curl \
-F "access_token=<ACCESS_TOKEN>" \
"https://graph.facebook.com/<API_VERSION>/<FORM_ID>?fields=questions"

The category field in the response can be personal, advertiser_customized, or related to a vertical such as automotive.

Archive a Lead Form

You can archive a lead form that's currently used in an ad. An archived form can be activated by setting its status back to ACTIVE. Once a form is archived:

The form won't appear (by default) in 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 in CF or PE.

use FacebookAds\Object\LeadgenForm;
use FacebookAds\Object\Fields\LeadgenFormFields;

$form = new LeadgenForm(<FORM_ID>);
$form->update(array(
  LeadgenFormFields::STATUS => 'ARCHIVED',
));

curl \
  -F 'status=ARCHIVED' \
  -F 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v2.11/<FORM_ID>

Delete a Lead Form

To delete a Lead Form, all ads associated with this form must be deleted or archived.

use FacebookAds\Object\LeadgenForm;

$form = new LeadgenForm(<FORM_ID>);
$form->deleteSelf();

from facebookads.adobjects.leadgenform import LeadgenForm

form = LeadgenForm(<LEADGEN_FORM_ID>)
form.remote_delete()

curl -X DELETE \
  -d 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v2.11/<FORM_ID>/

JavaScript Lead Form Builder

This is an optional form-creation dialog to use only if you don't want to use the API. You need the Facebook JavaScript SDK to define a callback that provides necessary data for the Ad Creative. Facebook stores the form at the Page level. You should have ad account permission to open form builder. See Handling the Form Builder, Blog

/**
 * Executing this will immediately load a popup, be sure to
 * associate this with an appropriate event.
 */
FB.ui({
  method: 'lead_gen',
  page_id: <PAGE_ID>,
  ad_account_id: <AD_ACCOUNT_ID>, // Note: This does NOT contain 'act_'
}, function(response) {
  // Handle response.
});

Executing this launches a pop-up:

This create dialog is not supported in mobile devices.

The response:

{
  follow_up_action_text: "<FOLLOW_UP_ACTION_TEXT>",
  follow_up_action_url: "<FOLLOW_UP_ACTION_URL>",
  formID: <FORM_ID>,
  form_url: "<FORM_URL>",
  is_tcpa_compliant: false,
  name: "My+Form",
  pageID: <PAGE_ID>,
  privacy_policy_url: "<PRIVACY_POLICY_URL>",
  status: "success"
}

You only need to provide formID for the object_story_spec for the ad creative. The following are response properties:

Property Name	Description	Type
`custom_disclaimer_responses`	The responses to custom disclaimer checkboxes	`string`
`follow_up_action_text`	The caption of the follow up action text on the final screen of the form	`string`
`follow_up_action_url`	The destination of the follow-up action text on the final screen of the form	`string`
`formID`	The ID of the form	`string`
`form_url`	The URL to the form	`string`
`is_tcpa_compliant`	[DEPRECATED] Whether this form needs TCPA compliance	`boolean`
`name`	The name of the form	`string`
`pageID`	The ID of the page to which this form belongs	`string`
`privacy_policy_url`	The supplied privacy policy URL	`string`
`status`	Returns `success` when the form has been created	`string`

If you cancel the create, you see the following:

{
  error_code: 4201,
  error_message: "User canceled the Dialog flow"
}

Create Lead Ads

Guidelines on how to set up a campaign and ad set:

Campaigns must have objective set to LEAD_GENERATION.
Campaign should have buying_type set to AUCTION.
Ad sets must have promoted_object set to the corresponding <PAGE_ID>.
Ad sets' optimization_goal must be LEAD_GENERATION or LINK_CLICKS. Note that LINK_CLICKS is a sub-optimal optimization strategy and may be deprecated in the future.
Ad sets' billing_event should be based on optimization_goal:
Billing event IMPRESSIONS for LEAD_GENERATION optimization.
Billing event of LINK_CLICKS for LINK_CLICKS optimization.
Ad set targeting either mobilefeed or desktopfeed

Ad Creative

The lead ads form builder response contains <FORM_DATA_ID>, which is used to create an ad creative object using an object_story_spec. Note: While creating the link_data, the value associated with the link field can only be https//fb.me/.

While creating the leadgen form using Ads Manager or PE, you don't get the shortened URL, which needs to be supplied under link_data. If this is the case, use the default https://fb.me/ while making the API call.

Ensure that the link_url you specify in the object_story_spec of the creative doesn't belong to a Facebook page; in which case, this API call fails.

use FacebookAds\Object\AdCreative;
use FacebookAds\Object\Fields\AdCreativeFields;
use FacebookAds\Object\Fields\AdCreativeLinkDataFields;
use FacebookAds\Object\Fields\AdCreativeObjectStorySpecFields;
use FacebookAds\Object\AdCreativeLinkData;
use FacebookAds\Object\AdCreativeObjectStorySpec;
use FacebookAds\Object\Values\AdCreativeCallToActionTypeValues;

$link_data = new AdCreativeLinkData();
$link_data->setData(array(
  AdCreativeLinkDataFields::MESSAGE => 'Creative message',
  AdCreativeLinkDataFields::LINK => 'http://fb.me/',
  AdCreativeLinkDataFields::IMAGE_HASH => '<IMAGE_HASH>',
  AdCreativeLinkDataFields::DESCRIPTION => 'Creative description',
  AdCreativeLinkDataFields::CALL_TO_ACTION => array(
    'type' => AdCreativeCallToActionTypeValues::SIGN_UP,
    'value' => array(
      'lead_gen_form_id' => <FORM_ID>,
    ),
  ),
));

$story = new AdCreativeObjectStorySpec();
$story->setData(array(
  AdCreativeObjectStorySpecFields::PAGE_ID => <PAGE_ID>,
  AdCreativeObjectStorySpecFields::LINK_DATA => $link_data,
));

$creative = new AdCreative(null, 'act_<AD_ACCOUNT_ID>');
$creative->setData(array(
  AdCreativeFields::OBJECT_STORY_SPEC => $story,
));

$creative->create();

from facebookads.adobjects.adcreative import AdCreative
from facebookads.adobjects.adcreativelinkdata import AdCreativeLinkData
from facebookads.adobjects.adcreativeobjectstoryspec \
    import AdCreativeObjectStorySpec

link_data = AdCreativeLinkData()
link_data[AdCreativeLinkData.Field.message] = 'try it out'
link_data[AdCreativeLinkData.Field.link] = 'http://fb.me/'
link_data[AdCreativeLinkData.Field.image_hash] = '<IMAGE_HASH>'
link_data[AdCreativeLinkData.Field.description] = 'My caption'
link_data[AdCreativeLinkData.Field.call_to_action] = {
    'type': 'SIGN_UP',
    'value': {
        'lead_gen_form_id': <FORM_ID>,
    },
}

object_story_spec = AdCreativeObjectStorySpec()
object_story_spec[AdCreativeObjectStorySpec.Field.page_id] = <PAGE_ID>
object_story_spec[AdCreativeObjectStorySpec.Field.link_data] = link_data

creative = AdCreative(parent_id='act_<AD_ACCOUNT_ID>')
creative[AdCreative.Field.name] = 'AdCreative for Link Ad'
creative[AdCreative.Field.object_story_spec] = object_story_spec
creative.remote_create()

print(creative)

curl \
  -F 'object_story_spec={ 
    "link_data": { 
      "call_to_action": {"type":"SIGN_UP","value":{"lead_gen_form_id":"<FORM_ID>"}}, 
      "description": "Creative description", 
      "image_hash": "<IMAGE_HASH>", 
      "link": "http:\/\/fb.me\/", 
      "message": "Creative message" 
    }, 
    "page_id": "<PAGE_ID>" 
  }' \
  -F 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v2.9/act_<AD_ACCOUNT_ID>/adcreatives

Call to Action

The following call-to-action (CTA) types are available: APPLY_NOW, DOWNLOAD, GET_QUOTE, LEARN_MORE, SIGN_UP, SUBSCRIBE

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.

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

use FacebookAds\Object\AdCreative;
use FacebookAds\Object\Fields\AdCreativeFields;
use FacebookAds\Object\Fields\AdCreativeObjectStorySpecFields;
use FacebookAds\Object\Fields\AdCreativeLinkDataFields;
use FacebookAds\Object\Fields\AdCreativeLinkDataChildAttachmentFields;
use FacebookAds\Object\Values\AdCreativeCallToActionTypeValues;

$child_attachments = array();

for ($i = 0; $i <= 3; $i++) {
  $child_attachments[] = array(
    AdCreativeLinkDataChildAttachmentFields::LINK => $url,
    AdCreativeLinkDataChildAttachmentFields::IMAGE_HASH => '<IMAGE_HASH>',
    AdCreativeLinkDataChildAttachmentFields::CALL_TO_ACTION => array(
      'type' => AdCreativeCallToActionTypeValues::SIGN_UP,
      'value' => array(
        'lead_gen_form_id' => <FORM_ID>,
      ),
    ),
  );
}

$object_story_spec = array(
  AdCreativeObjectStorySpecFields::PAGE_ID => <PAGE_ID>,
  AdCreativeObjectStorySpecFields::LINK_DATA => array(
    AdCreativeLinkDataFields::MESSAGE => 'My description',
    AdCreativeLinkDataFields::LINK => $url,
    AdCreativeLinkDataFields::CAPTION => 'WWW.EXAMPLE.COM',
    AdCreativeLinkDataFields::CHILD_ATTACHMENTS => $child_attachments,
    AdCreativeLinkDataFields::MULTI_SHARE_OPTIMIZED => true,
    AdCreativeLinkDataFields::CALL_TO_ACTION => array(
      'type' => AdCreativeCallToActionTypeValues::SIGN_UP,
      'value' => array(
        'lead_gen_form_id' => <FORM_ID>,
      ),
    ),
  ),
);

$creative = new AdCreative(null, 'act_<AD_ACCOUNT_ID>');
$creative->setData(array(
  AdCreativeFields::OBJECT_STORY_SPEC => $object_story_spec,
));

$creative->create();

from facebookads.adobjects.adcreative import AdCreative
from facebookads.adobjects.adcreativelinkdata import AdCreativeLinkData
from facebookads.adobjects.adcreativeobjectstoryspec \
    import AdCreativeObjectStorySpec
from facebookads.adobjects.adcreativelinkdatachildattachment \
    import AdCreativeLinkDataChildAttachment

child_attachments = list()
for i in range(3):
    child_attachment = AdCreativeLinkDataChildAttachment()
    child_attachment[AdCreativeLinkDataChildAttachment.Field.link] = 'http://fb.me/'
    child_attachment[AdCreativeLinkDataChildAttachment.Field.image_hash] = '<IMAGE_HASH>'
    child_attachment[AdCreativeLinkDataChildAttachment.Field.image_hash] = '<IMAGE_HASH>'
    child_attachment[AdCreativeLinkDataChildAttachment.Field.call_to_action] = {
        'type': 'SIGN_UP',
        'value': {
            'lead_gen_form_id': <FORM_ID>,
        },
    }
    child_attachments.append(child_attachment)

link_data = AdCreativeLinkData()
link_data[AdCreativeLinkData.Field.message] = 'My description'
link_data[AdCreativeLinkData.Field.link] = 'http://fb.me/'
link_data[AdCreativeLinkData.Field.caption] = 'WWW.EXAMPLE.COM'
link_data[AdCreativeLinkData.Field.child_attachments] = child_attachments
link_data[AdCreativeLinkData.Field.multi_share_optimized] = True
link_data[AdCreativeLinkData.Field.call_to_action] = {
    'type': 'SIGN_UP',
    'value': {
        'lead_gen_form_id': <FORM_ID>,
    },
}

story = AdCreativeObjectStorySpec()
story[story.Field.page_id] = <PAGE_ID>
story[story.Field.link_data] = link_data

creative = AdCreative(parent_id='act_<AD_ACCOUNT_ID>')
creative[AdCreative.Field.object_story_spec] = story

creative.remote_create()

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/v2.9/act_<AD_ACCOUNT_ID>/adcreatives

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, and then use it in the object_story_spec:


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/v10.0/act_<AD_ACCOUNT_ID>/adcreatives


'use strict';
const bizSdk = require('facebook-nodejs-business-sdk');
const AdAccount = bizSdk.AdAccount;
const AdCreative = bizSdk.AdCreative;

const access_token = '<ACCESS_TOKEN>';
const app_secret = '<APP_SECRET>';
const app_id = '<APP_ID>';
const id = '<AD_ACCOUNT_ID>';
const api = bizSdk.FacebookAdsApi.init(access_token);
const showDebugingInfo = true; // Setting this to true shows more debugging info.
if (showDebugingInfo) {
  api.setDebug(true);
}

const logApiCallResult = (apiCallName, data) => {
  console.log(apiCallName);
  if (showDebugingInfo) {
    console.log('Data:' + JSON.stringify(data));
  }
};

let fields, params;
fields = [
];
params = {
  'object_story_spec' : {'page_id':'<pageID>','video_data':{'link_description':'try it out','image_url':'<imageURL>','video_id':'<videoID>','call_to_action':{'type':'SIGN_UP','value':{'link':'http:\/\/fb.me\/','lead_gen_form_id':'<formID>'}}}},
};
const adcreatives = (new AdAccount(id)).createAdCreative(
  fields,
  params
);
logApiCallResult('adcreatives api call complete.', adcreatives);


require __DIR__ . '/vendor/autoload.php';

use FacebookAds\Object\AdAccount;
use FacebookAds\Object\AdCreative;
use FacebookAds\Api;
use FacebookAds\Logger\CurlLogger;

$access_token = '<ACCESS_TOKEN>';
$app_secret = '<APP_SECRET>';
$app_id = '<APP_ID>';
$id = '<AD_ACCOUNT_ID>';

$api = Api::init($app_id, $app_secret, $access_token);
$api->setLogger(new CurlLogger());

$fields = array(
);
$params = array(
  'object_story_spec' => array('page_id' => '<pageID>','video_data' => array('link_description' => 'try it out','image_url' => '<imageURL>','video_id' => '<videoID>','call_to_action' => array('type' => 'SIGN_UP','value' => array('link' => 'http:\/\/fb.me\/','lead_gen_form_id' => '<formID>')))),
);
echo json_encode((new AdAccount($id))->createAdCreative(
  $fields,
  $params
)->exportAllData(), JSON_PRETTY_PRINT);


from facebook_business.adobjects.adaccount import AdAccount
from facebook_business.adobjects.adcreative import AdCreative
from facebook_business.api import FacebookAdsApi

access_token = '<ACCESS_TOKEN>'
app_secret = '<APP_SECRET>'
app_id = '<APP_ID>'
id = '<AD_ACCOUNT_ID>'
FacebookAdsApi.init(access_token=access_token)

fields = [
]
params = {
  'object_story_spec': {'page_id':'<pageID>','video_data':{'link_description':'try it out','image_url':'<imageURL>','video_id':'<videoID>','call_to_action':{'type':'SIGN_UP','value':{'link':'http:\/\/fb.me\/','lead_gen_form_id':'<formID>'}}}},
}
print AdAccount(id).create_ad_creative(
  fields=fields,
  params=params,
)


import com.facebook.ads.sdk.*;
import java.io.File;
import java.util.Arrays;

public class SAMPLE_CODE_EXAMPLE {
  public static void main (String args[]) throws APIException {

    String access_token = \"<ACCESS_TOKEN>\";
    String app_secret = \"<APP_SECRET>\";
    String app_id = \"<APP_ID>\";
    String id = \"<AD_ACCOUNT_ID>\";
    APIContext context = new APIContext(access_token).enableDebug(true);

    new AdAccount(id, context).createAdCreative()
      .setObjectStorySpec(
          new AdCreativeObjectStorySpec()
            .setFieldPageId(\"<pageID>\")
            .setFieldVideoData(
              new AdCreativeVideoData()
                .setFieldCallToAction(
                  new AdCreativeLinkDataCallToAction()
                    .setFieldType(AdCreativeLinkDataCallToAction.EnumType.VALUE_SIGN_UP)
                    .setFieldValue(
                      new AdCreativeLinkDataCallToActionValue()
                        .setFieldLeadGenFormId(\"<formID>\")
                        .setFieldLink(\"http://fb.me/\")
                    )
                )
                .setFieldImageUrl(\"<imageURL>\")
                .setFieldLinkDescription(\"try it out\")
                .setFieldVideoId(\"<videoID>\")
            )
        )
      .execute();

  }
}


require 'facebook_ads'

access_token = '<ACCESS_TOKEN>'
app_secret = '<APP_SECRET>'
app_id = '<APP_ID>'
id = '<AD_ACCOUNT_ID>'

FacebookAds.configure do |config|
  config.access_token = access_token
  config.app_secret = app_secret
end

ad_account = FacebookAds::AdAccount.get(id)
adcreatives = ad_account.adcreatives.create({
    object_story_spec: {'page_id':'<pageID>','video_data':{'link_description':'try it out','image_url':'<imageURL>','video_id':'<videoID>','call_to_action':{'type':'SIGN_UP','value':{'link':'http:\/\/fb.me\/','lead_gen_form_id':'<formID>'}}}},
})

The resulting creative id returned by the previous call is then used to create an Ad.


curl -X POST \
  -F 'name="My Ad"' \
  -F 'adset_id="<AD_SET_ID>"' \
  -F 'creative={
       "creative_id": "<CREATIVE_ID>"
     }' \
  -F 'status="PAUSED"' \
  -F 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v10.0/act_<AD_ACCOUNT_ID>/ads


'use strict';
const bizSdk = require('facebook-nodejs-business-sdk');
const AdAccount = bizSdk.AdAccount;
const Ad = bizSdk.Ad;

const access_token = '<ACCESS_TOKEN>';
const app_secret = '<APP_SECRET>';
const app_id = '<APP_ID>';
const id = '<AD_ACCOUNT_ID>';
const api = bizSdk.FacebookAdsApi.init(access_token);
const showDebugingInfo = true; // Setting this to true shows more debugging info.
if (showDebugingInfo) {
  api.setDebug(true);
}

const logApiCallResult = (apiCallName, data) => {
  console.log(apiCallName);
  if (showDebugingInfo) {
    console.log('Data:' + JSON.stringify(data));
  }
};

let fields, params;
fields = [
];
params = {
  'name' : 'My Ad',
  'adset_id' : '<adSetID>',
  'creative' : {'creative_id':'<adCreativeID>'},
  'status' : 'PAUSED',
};
const ads = (new AdAccount(id)).createAd(
  fields,
  params
);
logApiCallResult('ads api call complete.', ads);


require __DIR__ . '/vendor/autoload.php';

use FacebookAds\Object\AdAccount;
use FacebookAds\Object\Ad;
use FacebookAds\Api;
use FacebookAds\Logger\CurlLogger;

$access_token = '<ACCESS_TOKEN>';
$app_secret = '<APP_SECRET>';
$app_id = '<APP_ID>';
$id = '<AD_ACCOUNT_ID>';

$api = Api::init($app_id, $app_secret, $access_token);
$api->setLogger(new CurlLogger());

$fields = array(
);
$params = array(
  'name' => 'My Ad',
  'adset_id' => '<adSetID>',
  'creative' => array('creative_id' => '<adCreativeID>'),
  'status' => 'PAUSED',
);
echo json_encode((new AdAccount($id))->createAd(
  $fields,
  $params
)->exportAllData(), JSON_PRETTY_PRINT);


from facebook_business.adobjects.adaccount import AdAccount
from facebook_business.adobjects.ad import Ad
from facebook_business.api import FacebookAdsApi

access_token = '<ACCESS_TOKEN>'
app_secret = '<APP_SECRET>'
app_id = '<APP_ID>'
id = '<AD_ACCOUNT_ID>'
FacebookAdsApi.init(access_token=access_token)

fields = [
]
params = {
  'name': 'My Ad',
  'adset_id': '<adSetID>',
  'creative': {'creative_id':'<adCreativeID>'},
  'status': 'PAUSED',
}
print AdAccount(id).create_ad(
  fields=fields,
  params=params,
)


import com.facebook.ads.sdk.*;
import java.io.File;
import java.util.Arrays;

public class SAMPLE_CODE_EXAMPLE {
  public static void main (String args[]) throws APIException {

    String access_token = \"<ACCESS_TOKEN>\";
    String app_secret = \"<APP_SECRET>\";
    String app_id = \"<APP_ID>\";
    String id = \"<AD_ACCOUNT_ID>\";
    APIContext context = new APIContext(access_token).enableDebug(true);

    new AdAccount(id, context).createAd()
      .setName(\"My Ad\")
      .setAdsetId(<adSetID>L)
      .setCreative(
          new AdCreative()
            .setFieldId(\"<adCreativeID>\")
        )
      .setStatus(Ad.EnumStatus.VALUE_PAUSED)
      .execute();

  }
}


require 'facebook_ads'

access_token = '<ACCESS_TOKEN>'
app_secret = '<APP_SECRET>'
app_id = '<APP_ID>'
id = '<AD_ACCOUNT_ID>'

FacebookAds.configure do |config|
  config.access_token = access_token
  config.app_secret = app_secret
end

ad_account = FacebookAds::AdAccount.get(id)
ads = ad_account.ads.create({
    name: 'My Ad',
    adset_id: '<adSetID>',
    creative: {'creative_id':'<adCreativeID>'},
    status: 'PAUSED',
})

Create Leadgen Dialog

You can use the Create Leadgen dialog to provide the Facebook Leadgen creation UI flow in your website. For details about the UI component, see Dialogs.

Set up the Facebook SDK for JavaScript, see:

Then trigger the Create Leadgen page:

FB.ui({         
  account_id: '<ACCOUNT_ID>',
  display: 'popup',
  method: 'lead_gen',
  page_id: '<PAGE_ID>',
}, function(response) {
  // callback
});

You can provide these settings for the dialog:

Name	Description
`account_id`	Your ad account ID
`display`	popup
`method`	lead_gen
`page_id`	Your page ID

The dialog provides this response on success:

Struct {
  formID: numeric string,
  status: bool,
  ...
}