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
  • ads_management (if you need to retrieve additional listing detail other than just the vehicle_id. See below in the section "Additional option: retrieve more Vehicle information")

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 v4.0 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.

    First, get the Business Scoped User ID of your System User with the following request:

    Graph API Explorer
    curl -X GET \
      -d 'access_token=<ACCESS_TOKEN>' \
      https://graph.facebook.com/{BUSINESS_ID}/system_users
    GET /{BUSINESS_ID}/system_users 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(
        '/{BUSINESS_ID}/system_users',
        '{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(
        "/{BUSINESS_ID}/system_users",
        function (response) {
          if (response && !response.error) {
            /* handle the result */
          }
        }
    );

    Then, after you obtained the BUSINESS_SCOPED_USER_ID of your System User, you can run the following code to give the System User access to the page (PAGE_ID):

    Graph API Explorer
    curl -X POST \
      -F 'user={BUSINESS_SCOPED_USER_ID}' \
      -F 'tasks=[
           "CREATE_CONTENT",
           "MODERATE",
           "ADVERTISE",
           "ANALYZE",
           "MANAGE"
         ]' \
      -F 'access_token=<ACCESS_TOKEN>' \
      https://graph.facebook.com/{PAGE_ID}/assigned_users
    POST /{PAGE_ID}/assigned_users HTTP/1.1
    Host: graph.facebook.com
    
    user=%7BBUSINESS_SCOPED_USER_ID%7D&tasks%5B0%5D=CREATE_CONTENT&tasks%5B1%5D=MODERATE&tasks%5B2%5D=ADVERTISE&tasks%5B3%5D=ANALYZE&tasks%5B4%5D=MANAGE
    /* PHP SDK v5.0.0 */
    /* make the API call */
    try {
      // Returns a `Facebook\FacebookResponse` object
      $response = $fb->post(
        '/{PAGE_ID}/assigned_users',
        array (
          'user' => '{BUSINESS_SCOPED_USER_ID}',
          'tasks' => 
          array (
          0 => 'CREATE_CONTENT',
          1 => 'MODERATE',
          2 => 'ADVERTISE',
          3 => 'ANALYZE',
          4 => 'MANAGE',
          ),
        ),
        '{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}/assigned_users",
        "POST",
        {
            "user": "{BUSINESS_SCOPED_USER_ID}",
            "tasks": [
                "CREATE_CONTENT",
                "MODERATE",
                "ADVERTISE",
                "ANALYZE",
                "MANAGE"
            ]
        },
        function (response) {
          if (response && !response.error) {
            /* handle the result */
          }
        }
    );
    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.

    Graph API Explorer
    curl -X GET \
      -d 'access_token=<ACCESS_TOKEN>' \
      https://graph.facebook.com/{USER_ID}/accounts
    GET /{USER_ID}/accounts 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(
        '/{USER_ID}/accounts',
        '{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(
        "/{USER_ID}/accounts",
        function (response) {
          if (response && !response.error) {
            /* handle the result */
          }
        }
    );

    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.

    Graph API Explorer
    curl -X POST \
      -F 'subscribed_fields="leadgen"' \
      -F 'access_token=<ACCESS_TOKEN>' \
      https://graph.facebook.com/{PAGE_ID}/subscribed_apps
    POST /{PAGE_ID}/subscribed_apps HTTP/1.1
    Host: graph.facebook.com
    
    subscribed_fields=leadgen
    /* PHP SDK v5.0.0 */
    /* make the API call */
    try {
      // Returns a `Facebook\FacebookResponse` object
      $response = $fb->post(
        '/{PAGE_ID}/subscribed_apps',
        array (
          'subscribed_fields' => 'leadgen',
        ),
        '{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}/subscribed_apps",
        "POST",
        {
            "subscribed_fields": "leadgen"
        },
        function (response) {
          if (response && !response.error) {
            /* handle the result */
          }
        }
    );

    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:

    Graph API Explorer
    curl -X GET \
      -d 'access_token=<ACCESS_TOKEN>' \
      https://graph.facebook.com/{LEAD_ID}
    GET /{LEAD_ID} 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(
        '/{LEAD_ID}',
        '{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(
        "/{LEAD_ID}",
        function (response) {
          if (response && !response.error) {
            /* handle the result */
          }
        }
    );

    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

    If you want to retrieve the vehicle information, you will need an additional permission, ads_management. In the Business Manager, make also sure that the system user that owns the access token is an admin of the catalog.

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

    Graph API Explorer
    curl -X GET \
      -d 'fields="id,field_data,vehicle{id,vin,vehicle_registration_plate,title,price,address,mileage}"' \
      -d 'access_token=<ACCESS_TOKEN>' \
      https://graph.facebook.com/{LEAD_ID}
    GET /{LEAD_ID}?fields=id%2Cfield_data%2Cvehicle%7Bid%2Cvin%2Cvehicle_registration_plate%2Ctitle%2Cprice%2Caddress%2Cmileage%7D 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(
        '/{LEAD_ID}?fields=id%2Cfield_data%2Cvehicle%7Bid%2Cvin%2Cvehicle_registration_plate%2Ctitle%2Cprice%2Caddress%2Cmileage%7D',
        '{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(
        "/{LEAD_ID}",
        {
            "fields": "id,field_data,vehicle{id,vin,vehicle_registration_plate,title,price,address,mileage}"
        },
        function (response) {
          if (response && !response.error) {
            /* handle the result */
          }
        }
    );

    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:

    Graph API Explorer
    curl -X GET \
      -d 'access_token=<ACCESS_TOKEN>' \
      https://graph.facebook.com/{FORM_ID}/leads
    GET /{FORM_ID}/leads 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(
        '/{FORM_ID}/leads',
        '{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(
        "/{FORM_ID}/leads",
        function (response) {
          if (response && !response.error) {
            /* handle the result */
          }
        }
    );

    3.c Additional option: delete Leads

    You can also delete a (test) lead. Please notice that you need to use a user token and not a page token. Please notice that you can delete only leads that you own (e.g. test). See this API reference for more details:

    Graph API Explorer
    curl -X DELETE \
      -F 'access_token=<ACCESS_TOKEN>' \
      https://graph.facebook.com/{LEAD_ID}
    DELETE /{LEAD_ID} HTTP/1.1
    Host: graph.facebook.com
    /* PHP SDK v5.0.0 */
    /* make the API call */
    try {
      // Returns a `Facebook\FacebookResponse` object
      $response = $fb->delete(
        '/{LEAD_ID}',
        array (),
        '{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(
        "/{LEAD_ID}",
        "DELETE",
        function (response) {
          if (response && !response.error) {
            /* handle the result */
          }
        }
    );

    Need help?

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

    Contact us