Graph API Version

Page Leadgen Forms

Reading

Fetch LeadGen forms associated with a page

Permissions

This operation requires a Page access token.

Example

Graph API Explorer
GET /v19.0/{page-id}/leadgen_forms HTTP/1.1
Host: graph.facebook.com
/* PHP SDK v5.0.0 */
/* make the API call */
try {
  // Returns a `Facebook\FacebookResponse` object
  $response = $fb->get(
    '/{page-id}/leadgen_forms',
    '{access-token}'
  );
} catch(Facebook\Exceptions\FacebookResponseException $e) {
  echo 'Graph returned an error: ' . $e->getMessage();
  exit;
} catch(Facebook\Exceptions\FacebookSDKException $e) {
  echo 'Facebook SDK returned an error: ' . $e->getMessage();
  exit;
}
$graphNode = $response->getGraphNode();
/* handle the result */
/* make the API call */
FB.api(
    "/{page-id}/leadgen_forms",
    function (response) {
      if (response && !response.error) {
        /* handle the result */
      }
    }
);
/* make the API call */
new GraphRequest(
    AccessToken.getCurrentAccessToken(),
    "/{page-id}/leadgen_forms",
    null,
    HttpMethod.GET,
    new GraphRequest.Callback() {
        public void onCompleted(GraphResponse response) {
            /* handle the result */
        }
    }
).executeAsync();
/* make the API call */
FBSDKGraphRequest *request = [[FBSDKGraphRequest alloc]
                               initWithGraphPath:@"/{page-id}/leadgen_forms"
                                      parameters:params
                                      HTTPMethod:@"GET"];
[request startWithCompletionHandler:^(FBSDKGraphRequestConnection *connection,
                                      id result,
                                      NSError *error) {
    // Handle the result
}];
If you want to learn how to use the Graph API, read our Using Graph API guide.

Parameters

This endpoint doesn't have any parameters.

Fields

Reading from this edge will return a JSON formatted result:

{ "data": [], "paging": {} }

data

A list of LeadGenData nodes.

paging

For more details about pagination, see the Graph API guide.

Error Codes

ErrorDescription
200Permissions error
80005There have been too many leadgen api calls to this Page account. Wait a bit and try again. For more info, please refer to https://developers.facebook.com/docs/graph-api/overview/rate-limiting.
100Invalid parameter
80001There have been too many calls to this Page account. Wait a bit and try again. For more info, please refer to https://developers.facebook.com/docs/graph-api/overview/rate-limiting.
190Invalid OAuth 2.0 Access Token

Creating

You can make a POST request to leadgen_forms edge from the following paths:
When posting to this edge, a Page will be created.

Additional Errors

In addition to the errors listed below, you may receive unknown errors for privacy_policy if the URL is invalid or the link_text exceeds 70 characters.

Permissions

If you upload an image by specifying cover_photo parameter, the access_token accompanying the request must include the pages_manage_posts permission.

Parameters

ParameterDescription
allow_organic_lead_retrieval
boolean
Default value: true

Previously, this flag controlled whether any leads submitted in a non-Ad context were retrievable. Now this flag will not be considered and it will be deprecated entirely. To control visibility of Lead Forms in a non-Ad context you should use 'block_display_for_non_targeted_viewer'

block_display_for_non_targeted_viewer
boolean

Whether to make the organic post invisible to viewers in non-Ad context

context_card
Object

Optional context card shown as the intro page

Supports Emoji
title
string

style
enum {LIST_STYLE, PARAGRAPH_STYLE}

content
array<string>

button_text
string

cover_photo_id
photo ID

cover_photo
file

Custom cover photo for context card

custom_disclaimer
Object

Customized disclaimer including title, body content with inline links, and consent checkboxes

title
string

body
Object

text
string

Required
url_entities
list<JSON object>

checkboxes
list<Object>

is_required
boolean
Default value: true

is_checked_by_default
boolean
Default value: false

text
string

Required
key
string

follow_up_action_url
URI

The final destination URL that user will go to when clicking view website button

is_for_canvas
boolean
Default value: false

Flag to indicate that the form is going to be used under a canvas

is_optimized_for_quality
boolean
Default value: false

Flag to indicate whether the form will be optimized for quality

locale
enum {AR_AR, CS_CZ, DA_DK, DE_DE, EL_GR, EN_GB, EN_US, ES_ES, ES_LA, FI_FI, FR_FR, HE_IL, HI_IN, HU_HU, ID_ID, IT_IT, JA_JP, KO_KR, NB_NO, NL_NL, PL_PL, PT_BR, PT_PT, RO_RO, RU_RU, SV_SE, TH_TH, TR_TR, VI_VN, ZH_CN, ZH_HK, ZH_TW}

The locale of the form. Pre-defined questions renders in this locale

name
string

The name that will help identity the form

Required
privacy_policy
Object

The url and link_text of the privacy policy of advertiser. link_text is limited to a maximum of 70 characters.

url
string

link_text
string

question_page_custom_headline
string

The custom headline for the question page within the form

questions
list<Object>

An array of questions of the form

Required
key
string

label
string

type
enum {CUSTOM, CITY, COMPANY_NAME, COUNTRY, DOB, EMAIL, GENDER, FIRST_NAME, FULL_NAME, JOB_TITLE, LAST_NAME, MARITIAL_STATUS, PHONE, PHONE_OTP, POST_CODE, PROVINCE, RELATIONSHIP_STATUS, STATE, STREET_ADDRESS, ZIP, WORK_EMAIL, MILITARY_STATUS, WORK_PHONE_NUMBER, SLIDER, STORE_LOOKUP, STORE_LOOKUP_WITH_TYPEAHEAD, DATE_TIME, ID_CPF, ID_AR_DNI, ID_CL_RUT, ID_CO_CC, ID_EC_CI, ID_PE_DNI, ID_MX_RFC, JOIN_CODE, USER_PROVIDED_PHONE_NUMBER, FACEBOOK_LEAD_ID, EMAIL_ALIAS, MESSENGER}

Required
inline_context
string

options
list<JSON object>

dependent_conditional_questions
list<JSON object>

conditional_questions_group_id
LeadGen Conditional Questions Group ID

thank_you_page
Object

Optional customized thank you page displayed post submission

title
string

Required
body
string

Required
short_message
string

button_text
string

button_description
string

business_phone_number
phone number string

enable_messenger
boolean
Default value: false

website_url
string

button_type
enum {VIEW_WEBSITE, CALL_BUSINESS, MESSAGE_BUSINESS, DOWNLOAD, SCHEDULE_APPOINTMENT, VIEW_ON_FACEBOOK, NONE}

Required
country_code
string

tracking_parameters
JSON object {string : string}

Map for additional tracking parameters to include with the form's field data

Return Type

This endpoint supports read-after-write and will read the node represented by id in the return type.
Struct {
id: numeric string,
}

Error Codes

ErrorDescription
100Invalid parameter
192Invalid phone number
200Permissions error
368The action attempted has been deemed abusive or is otherwise disallowed

Updating

You can't perform this operation on this endpoint.

Deleting

You can't perform this operation on this endpoint.