You can read leads with Webhooks or Bulk Read.
To read ad specific fields, such as ad_id
, campaign_id
, you will need:
ads_management
permissionpages_read_engagement
permissionpages_show_list
permissionpages_manage_metadata
permission - if using webhooks To read all lead data and ad level data, you will need:
ads_management
permissionleads_retrieval
permissionpages_show_list
permissionpages_read_engagement
permission pages_manage_ads
permissionNote: If this page admin never customized leads, nor given access permission with the Leads Access Manager, then ALL page admins will have leads access permission. If leads access permission is customized by business admins, then it depends on the business admin's configuration, whether a page basic admin has leads access permission or not.
The rate limit is 200 multiplied by 24 multiplied by the number of leads created in the past 90 days for a Facebook Page. If you make more calls than this in a 24 hour period, your request returns an error.
Send a GET
request to the /ads/lead_gen/export_csv/
endpoint where date formats are either POSIX
or UNIX
timestamps:
curl -i -X GET "https://www.facebook.com/ads/lead_gen/export_csv/ ?id=<FORM_ID> &type=form &from_date=1482698431 &to_date=1482784831"
from_date
is not set or is less than the form creation time, the form creation time is used.If to_date
is not set or is greater than the present time, current time is used.
If any entries lack Ad IDs or Adgroup IDs in the TSV, it can be due to the following reasons:
is_organic
in the TSV displays 1
; otherwise, the value is 0
.Get real-time updates for lead ads.
Visit our Webhooks Get Started guide to set up your endpoint and configure your webhook.
Generate a single, long-lived Page token to continuously fetch data without worrying about it expiring.
Visit our Webhooks for Pages guide to learn how to install your app on a Page.
On leadgen creation, your app receives the following webhook response:
array( "object" => "page", "entry" => array( "0" => array( "id" => 153125381133, "time" => 1438292065, "changes" => array( "0" => array( "field" => "leadgen", "value" => array( "leadgen_id" => 123123123123, "page_id" => 123123123, "form_id" => 12312312312, "adgroup_id" => 12312312312, "ad_id" => 12312312312, "created_time" => 1440120384 ) ), "1" => array( "field" => "leadgen", "value" => array( "leadgen_id" => 123123123124, "page_id" => 123123123, "form_id" => 12312312312, "adgroup_id" => 12312312312, "ad_id" => 12312312312, "created_time" => 1440120384 ) ) ) ) ) )
You can use leadgen_id
to retrieve data associated with the lead:
curl -X GET \
-d 'access_token=<ACCESS_TOKEN>' \
https://graph.facebook.com/v21.0/{lead-id}/
On success, your app receives the following response:
{ "created_time": "2015-02-28T08:49:14+0000", "id": "<LEAD_ID>", "ad_id": "<AD_ID>", "form_id": "<FORM_ID>", "field_data": [{ "name": "car_make", "values": [ "Honda" ] }, { "name": "full_name", "values": [ "Joe Example" ] }, { "name": "email", "values": [ "joe@example.com" ] }, { "name": "selected_dealer", "values": [ "99213450" ] }], ... }
You can see an example of this implementation in our Github repo.
Apps created after July 2, 2018 are forced to use leads_retrieval
permission to read leads.
The leads
exists on both ad group and form nodes. This returns all data associated with their respective objects. Because a form can be re-used for many ads, your form could contain far more leads than an ad using it.
To read in-bulk by ad:
curl -X GET \
-d 'access_token=<ACCESS_TOKEN>' \
https://graph.facebook.com/v21.0/{adgroup-id}/leads
To read by form:
curl -G \ -d 'access_token=<ACCESS_TOKEN>' \ -d 'fields=created_time,id,ad_id,form_id,field_data' \ https://graph.facebook.com/<API_VERSION>/<FORM_ID>/leads
The response:
{ "data": [ { "created_time": "2018-02-28T08:49:14+0000", "id": "<LEAD_ID>", "ad_id": "<AD_ID>", "form_id": "<FORM_ID>", "field_data": [ { "name": "car_make", "values": [ "Honda" ] }, { "name": "full_name", "values": [ "Joe Example" ] }, { "name": "email", "values": [ "joe@example.com" ] }, ], ... } ], "paging": { "cursors": { "before": "OTc2Nz3M8MTgyMzU1NDMy", "after": "OTcxNjcyOTg8ANTI4NzE4" } } }
Store locator question is not any different than any other question. A store locator question will also have a field ID that's going to mapped against them during the form creation. They are also going to be sent similarly as other questions. The value passed will come from the Store Number of the selected location.
For example, let's say you have a store locator question with selected_dealer
as the field ID. To fetch the leads in bulk, you can call:
curl -G \ -d 'access_token=<ACCESS_TOKEN>' \ -d 'fields=created_time,id,ad_id,form_id,field_data' \ https://graph.facebook.com/<API_VERSION>/<FORM_ID>/leads
The response:
{ "data": [ { "created_time": "2018-02-28T08:49:14+0000", "id": "<LEAD_ID>", "ad_id": "<AD_ID>", "form_id": "<FORM_ID>", "field_data": [ { "name": "car_make", "values": [ "Honda" ] }, { "name": "full_name", "values": [ "Joe Example" ] }, { "name": "email", "values": [ "joe@example.com" ] }, { "name": "selected_dealer", "values": [ "99213450" ] } ], ... } ], "paging": { "cursors": { "before": "OTc2Nz3M8MTgyMzU1NDMy", "after": "OTcxNjcyOTg8ANTI4NzE4" } } }
The field_data
does not contain the responses to optional custom disclaimer check boxes that the user would have filled out. To retrieve the responses, use the custom_disclaimer_responses
field.
curl -X GET \ "https://graph.facebook.com/<API_VERSION>/<LEADGEN_ID>? fields=custom_disclaimer_responses"
Response:
{ "custom_disclaimer_responses": [ { "checkbox_key": "optional_1", "is_checked": "1" }, { "checkbox_key": "optional_2", "is_checked": "" } ], "id": "1231231231" }
This example filters leads based on timestamps. Timestamps should be a Unix timestamp.
curl -X GET \
-d 'filtering=[
{
"field": "time_created",
"operator": "GREATER_THAN",
"value": 1731593225
}
]' \
-d 'access_token=<ACCESS_TOKEN>' \
https://graph.facebook.com/v21.0/{adgroup-id}/leads
The operator
has one of the following values.
Operator | Meaning |
---|---|
| Filters for values less than the timestamp. |
| Filters for values greater than the timestamp. |
| Filters for values greater than or equal to the timestamp. |
If the form has customized field IDs, the fields and values returned will be the specified fields and values.