Retrieving Leads

If you chose "lead form" as communication channel, you can access leads generated on Marketplace in different ways.

Manual download

It's possible to view and download leads received from Marketplace into the Publishing Tools of your page. This is accessible from the top header bar of your page. Note you must be a Page admin to see it:

From the Publishing Tools page, click on "Forms Library" under the section "Lead Ads Form", on the left hand side. In the Forms Library table, you will find a form called Marketplace Autos Lead Gen Form:

by clicking "Download", you will be able to choose to download all available leads or leads within a specific time range, either in csv or xls format.

Lead APIs / webhook - Requirements

It's possible to retrieve leads by setting up a webhook: visit our Marketing API documentation for more details and to stay up to date.

Before starting the setup, make sure to meet the following requirements:

1. Have Admin access to Dealer pages

Make sure to have Admin access with Manage Page role to your Dealer pages.

2. Register an app and submit for app review

Register an app to retrieve test leads in dev mode. After the setup is complete, you have to request an app review and switch the app to live mode in order to receive production leads.

Permissions required:

  • manage_pages
  • leads_retrieval
  • business_management

The app review process could take up to 1-2 weeks including the business verification process: prepare the required documents in advance.

3. Host on Public HTTP server

To receive webhook events from the Facebook Platform, your code must be hosted on a public HTTP server that meets has the following:

  • HTTPS support
  • A valid SSL certificate
  • An open port that accepts GET and POST requests

4. Use Graph API v3.2 or upper versions

Facebook Platform supports versioning and each version is guaranteed to operate for at least two years. A version will no longer be usable two years after the date that the subsequent version is released. So make sure to use the most recent API version.

Lead APIs / webhook - Setup Steps

Lead generation is language agnostic

The examples in this guide are in PHP, but you can write your webhook in whatever server-side language you like best.

Once you have meet all of the requirements listed above, you can start setting up your leads API webhook:

1
Create a new php file
You need to set up an endpoint that reads two variables (hub.challenge and hub.verify_token). If the verify code is fine, you should reply with the challenge. You can put any string as $token value, this will be used just to verify your endpoint:
<?php
  $token = "<YOUR_VERIFY_TOKEN>";
  $challenge = $_REQUEST['hub.challenge'];
  $verify_token = $_REQUEST['hub.verify_token'];

  if ($verify_token === $token) {
    echo $challenge;
  }
?>
Save the file and make it reachable from a path URL of your convenience, e.g. https://yourdomain.com/facebook/webhook_verify.php. Find more details in this guide.
2
Add the webhook to your Facebook app
From the Facebook app dashboard, select your app and add the webhook itme from Products:
Select Page from the dropdown menu, then click on Subscribe to this object.
Enter the information required:
  • Callback URL: the path URL you created to reach your webhook
  • Verify Token: a token you can set to verify the request that Facebook will send to the webhook (see above)
  • You should now see a list of possible fields to subscribe. Scroll down, and click on the Subscribe button next to leadgen field.
    You can test your webhooks using the test button next to leadgen. Check on your server if you received the request, for example by:
  • checking access logs
  • reading the raw content of the request body:
    $request_body = file_get_contents('php://input')
  • 3
    Get Business System User Access Token

    Create a system user. Go to your Business Manager > Business Settings > Users > System Users and create a new system user.

    Install app and generate a new Token. You will need to select your app and these permissions:

    • manage_pages
    • leads_retrieval
    • business_management

    Copy and save this token as it won't be stored at Facebook. You will use this token to access pages of dealers under your business.

    4
    Assign dealers pages to the system user you created

    In Business Manager > Users > System Users, select your system admin. Click Assign Assets button and then select Page.

    Select dealers pages with Page Admin access. Make sure you got assigned pages when you integrate new dealers!

    Or you can use API similar with this guide. Make sure you include MANAGE role in tasks.

            curl \
            -F "user=<BUSINESS_SCOPED_USER_ID>" \
            -F "tasks=['CREATE_CONTENT', 'MODERATE', 'ADVERTISE', 'ANALYZE', 'MANAGE']" \
            -F "access_token=<ACCESS_TOKEN>" \
    "https://graph.facebook.com/v3.2/<PAGE_ID>/assigned_users"
    5
    Get Page Access Tokens

    You will get all page access tokens assigned to the system admin.

    Use the Business Manager System User Token you saved before as access_token, and your regular user id (or "me") as user-id.

    curl -X GET \ -d 'access_token=<ACCESS_TOKEN>' \ https://graph.facebook.com/v4.0/{user-id}/accounts
    'use strict'; const bizSdk = require('facebook-nodejs-business-sdk'); const User = bizSdk.User; const Page = bizSdk.Page; const access_token = '<ACCESS_TOKEN>'; const app_secret = '<APP_SECRET>'; const app_id = '<APP_ID>'; const id = '<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 = { }; const accountss = (new User(id)).getAccounts( fields, params ); logApiCallResult('accountss api call complete.', accountss);
    require __DIR__ . '/vendor/autoload.php'; use FacebookAds\Object\User; use FacebookAds\Object\Page; use FacebookAds\Api; use FacebookAds\Logger\CurlLogger; $access_token = '<ACCESS_TOKEN>'; $app_secret = '<APP_SECRET>'; $app_id = '<APP_ID>'; $id = '<ID>'; $api = Api::init($app_id, $app_secret, $access_token); $api->setLogger(new CurlLogger()); $fields = array( ); $params = array( ); echo json_encode((new User($id))->getAccounts( $fields, $params )->getResponse()->getContent(), JSON_PRETTY_PRINT);
    from facebook_business.adobjects.user import User from facebook_business.adobjects.page import Page from facebook_business.api import FacebookAdsApi access_token = '<ACCESS_TOKEN>' app_secret = '<APP_SECRET>' app_id = '<APP_ID>' id = '<ID>' FacebookAdsApi.init(access_token=access_token) fields = [ ] params = { } print User(id).get_accounts( 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 = \"<ID>\"; APIContext context = new APIContext(access_token).enableDebug(true); new User(id, context).getAccounts() .execute(); } }
    require 'facebook_ads' access_token = '<ACCESS_TOKEN>' app_secret = '<APP_SECRET>' app_id = '<APP_ID>' id = '<ID>' FacebookAds.configure do |config| config.access_token = access_token config.app_secret = app_secret end user = FacebookAds::User.get(id) accountss = user.accounts({ fields: { }, })

    The response example:

    {
      "data": [
        {
            "access_token": "...",
            "category": "Automotive Dealership",
            "category_list": [
                {
                    "id": "123688294262123",
                    "name": "Automotive Dealership"
                }
            ],
            "name": "Test dealer page",
            "id": "132337234248833",
            "tasks": [
                "ANALYZE",
                "ADVERTISE",
                "MODERATE",
                "CREATE_CONTENT",
                "MANAGE"
            ]
        },
      ]
    }

    This access tokens in the response are long-lived page tokens which has no expiration date and you can hard-code it in simple RTU integrations to get leads data.

    6
    Subscribe pages to the app

    Using the page access tokens, your app need to subscribe pages so Facebook can send webhooks to your webserver.

    curl -X POST \ -F 'subscribed_fields="leadgen"' \ -F 'access_token=<ACCESS_TOKEN>' \ https://graph.facebook.com/v4.0/{page-id}/subscribed_apps
    'use strict'; const bizSdk = require('facebook-nodejs-business-sdk'); const Page = bizSdk.Page; const access_token = '<ACCESS_TOKEN>'; const app_secret = '<APP_SECRET>'; const app_id = '<APP_ID>'; const id = '<PAGE_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 = { 'subscribed_fields' : 'leadgen', }; const subscribed_apps = (new Page(id)).createSubscribedApp( fields, params ); logApiCallResult('subscribed_apps api call complete.', subscribed_apps);
    require __DIR__ . '/vendor/autoload.php'; use FacebookAds\Object\Page; use FacebookAds\Api; use FacebookAds\Logger\CurlLogger; $access_token = '<ACCESS_TOKEN>'; $app_secret = '<APP_SECRET>'; $app_id = '<APP_ID>'; $id = '<PAGE_ID>'; $api = Api::init($app_id, $app_secret, $access_token); $api->setLogger(new CurlLogger()); $fields = array( ); $params = array( 'subscribed_fields' => 'leadgen', ); echo json_encode((new Page($id))->createSubscribedApp( $fields, $params )->exportAllData(), JSON_PRETTY_PRINT);
    from facebook_business.adobjects.page import Page from facebook_business.api import FacebookAdsApi access_token = '<ACCESS_TOKEN>' app_secret = '<APP_SECRET>' app_id = '<APP_ID>' id = '<PAGE_ID>' FacebookAdsApi.init(access_token=access_token) fields = [ ] params = { 'subscribed_fields': 'leadgen', } print Page(id).create_subscribed_app( 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 = \"<PAGE_ID>\"; APIContext context = new APIContext(access_token).enableDebug(true); new Page(id, context).createSubscribedApp() .setSubscribedFields(Arrays.asList(Page.EnumSubscribedFields.VALUE_LEADGEN)) .execute(); } }
    require 'facebook_ads' access_token = '<ACCESS_TOKEN>' app_secret = '<APP_SECRET>' app_id = '<APP_ID>' id = '<PAGE_ID>' FacebookAds.configure do |config| config.access_token = access_token config.app_secret = app_secret end page = FacebookAds::Page.get(id) subscribed_apps = page.subscribed_apps.create({ subscribed_fields: 'leadgen', })

    If you are using Graph API v3.2 or upper version, please add one additional parameter in the POST request (read more):

    subscribed_fields=leadgen

    The Facebook app associated with your token is authenticated for page updates; you do not need to specify app ID.

    On success, real time pings occur on events with a delay of up to a few minutes. See Troubleshooting Real-time Integrations.

    Lead APIs / webhook - Receive leads

    1. Test your webhook by sending leads from your Marketplace listings

    If you do not receive leads in your webhook:

    • Make sure you changed your app to the public mode
    • Delete existing leads in order to receive them again from the same listings.

    The payload sent to the webhook has the following structure:

    {
      "changes": [{
        "field": "leadgen",
        "value": {
          "created_time": 1540269154,
          "page_id": "1935718636547237",
          "form_id": "2217161425198865",
          "leadgen_id": "2219139835001024"
        }
      }],
      "id": "1935718636547237",
      "time": 1540269155
    }

    2. Use leadgen_id to retrieve data associated with the lead

    Use page access token of the page associated with the lead:

    curl -X GET \ -d 'access_token=<ACCESS_TOKEN>' \ https://graph.facebook.com/v4.0/{lead-id}/
    'use strict'; const bizSdk = require('facebook-nodejs-business-sdk'); const Lead = bizSdk.Lead; const access_token = '<ACCESS_TOKEN>'; const app_secret = '<APP_SECRET>'; const app_id = '<APP_ID>'; const id = '<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 = { }; const sample_code = (new Lead(id)).get( fields, params ); logApiCallResult('sample_code api call complete.', sample_code);
    require __DIR__ . '/vendor/autoload.php'; use FacebookAds\Object\Lead; use FacebookAds\Api; use FacebookAds\Logger\CurlLogger; $access_token = '<ACCESS_TOKEN>'; $app_secret = '<APP_SECRET>'; $app_id = '<APP_ID>'; $id = '<ID>'; $api = Api::init($app_id, $app_secret, $access_token); $api->setLogger(new CurlLogger()); $fields = array( ); $params = array( ); echo json_encode((new Lead($id))->getSelf( $fields, $params )->exportAllData(), JSON_PRETTY_PRINT);
    from facebook_business.adobjects.lead import Lead from facebook_business.api import FacebookAdsApi access_token = '<ACCESS_TOKEN>' app_secret = '<APP_SECRET>' app_id = '<APP_ID>' id = '<ID>' FacebookAdsApi.init(access_token=access_token) fields = [ ] params = { } print Lead(id).get( 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 = \"<ID>\"; APIContext context = new APIContext(access_token).enableDebug(true); new Lead(id, context).get() .execute(); } }
    require 'facebook_ads' access_token = '<ACCESS_TOKEN>' app_secret = '<APP_SECRET>' app_id = '<APP_ID>' id = '<ID>' FacebookAds.configure do |config| config.access_token = access_token config.app_secret = app_secret end lead = FacebookAds::Lead.get(id ,'')

    to get the following response:

    {
      "created_time": "2018-10-23T04:32:34+0000",
      "id": "2219139835001024",
      "field_data": [{
          "name": "email",
          "values": [
            "joe@fbtest.com"
          ]
        },
        {
          "name": "phone_number",
          "values": [
            "12345678"
          ]
        },
        {
          "name": "full_name",
          "values": [
            "Joe"
          ]
        }
      ],
      "retailer_item_id": "Vehicle_id_4"
    }

    3.a Additional option: retrieve more Vehicle information

    You can add vehicle parameter in the request. Read the supported fields list:

    curl -X GET \
      -d "access_token=<ACCESS_TOKEN>" \
      "https://graph.facebook.com/v3.3/<lead-id>?fields=id,field_data,vehicle{id,vin,vehicle_registration_plate,title,price,address,mileage}"

    to get the following response:

    {
      "id": "2219139835001024",
      "field_data": [{
          "name": "email",
          "values": [
            "joe@fbtest.com"
          ]
        },
        {
          "name": "phone_number",
          "values": [
            "12345678"
          ]
        },
        {
          "name": "full_name",
          "values": [
            "Joe"
          ]
        }
      ],
      "vehicle": {
        "id": "2561003667307302",
        "vin": "TEST1234453254321",
        "title": "Title1",
        "price": "$1,500.00",
        "mileage": {
          "value": 1000,
          "unit": "MILES"
        },
        "address": {
          "city": "Menlo Park",
          "country": "US",
          "latitude": 37.4435997,
          "longitude": -122.1615219,
          "postal_code": "94025",
          "region": "Menlo Park, CA",
          "street_address": "1234 Example St"
        }
      }
    }

    3.b Additional option: retrieve all Leads

    You can also retrieve all leads you received by using {form-id} - this can be found using this API:

    curl -i -X GET \
     "https://graph.facebook.com/v3.2/{form-id}/leads?access_token={access-token}"

    3.c Additional option: delete Leads

    You can also delete a lead. See this API reference for more details:

    curl -i -X DELETE \
     "https://graph.facebook.com/v3.2/{lead-id}?access_token=<access_token>"

    Need help?

    You can contact Facebook's Support team any time you have questions.

    Contact us