News for Developers

Back to News

leadgen whitelisted users

Rituparna Mukherjee
January 20, 2016

Related News

Offer Ads API

February 09 2017

Developers Sandbox Mode

February 08 2017

Messenger v1.3

November 09 2016

Today we're excited to release the Lead Ads flexible permissioning endpoint that allows Page Admins to grant leads read access to page users. One of the challenges we have heard from developers is working through the restriction that only Page Admins could read lead information with the API. This restricted companies that owned a Page but also wanted several people to access leads generated on the page and had to grant admin access to select users just to read leads.

To address this issue we have released a new API endpoint called leadgen_whitelisted_users. Using this endpoint, page admins can can give lead read premissions to users who have some role on the page. Keep in mind to use a page access token when using this endpoint. Once you give read access to a user, they can read lead ads information with the API or by using a CSV download option.

Let's say that you are the admin of your auto company's Page. The agency your company works with recently ran a Lead Ads campaign targeting recent college graduates on car features they should look for during a new car purchase.

The campaign ran successfully and generated a large number of leads on your page. The agency needs access to the leads to perform an analysis, but only has Advertiser role on your Facebook Page.

Here are example steps to use the new API endpoint for this case and similar ones:

Step 1: Grant user lead read access

As Page Admin you can give users read access so they can read leads as follows:

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

$params = array(
'user_id' => <USER_ID>,
);

$response = Api::instance()->call(
'/me/leadgen_whitelisted_users',
RequestInterface::METHOD_POST,
$params);
from facebookads import FacebookAdsApi

params = {'user_id': <USER_ID>}
response = FacebookAdsApi.get_default_api()\
.call('POST', ('/me/leadgen_whitelisted_users',), params=params)
curl \
-F 'user_id=<USER_ID>' \
-F 'access_token=<PAGE_ACCESS_TOKEN>' \
https://graph.facebook.com/<API_VERSION>/<PAGE_ID>/leadgen_whitelisted_users

Note that you can only grant read access to the users who have some role on the page.

Step 2: Check if the user was successfully granted access

You can query this endpoint to see if you successfully gave users read access to lead data:

use FacebookAds\Api;

$users = Api::instance()->call('/me/leadgen_whitelisted_users');
from facebookads import FacebookAdsApi

users = FacebookAdsApi.get_default_api()\
.call('GET', ('/me/leadgen_whitelisted_users',))
curl -G\
-d 'access_token=<PAGE_ACCESS_TOKEN>' \
https://graph.facebook.com/<API_VERSION>/<PAGE_ID>/leadgen_whitelisted_users

Step 3: New users who have been granted access can read leads

All the users you added to the access list for your page can now read lead information with our API. Reading leads can be done through /<AD_ID>/leads, /<FORM_ID>/leads and /<LEAD_ID&gt; endpoints or by using the CSV download option. Following is an example of reading all the leads belonging to an ad:

use FacebookAds\Object\Ad;

$ad = new Ad(<AD_ID>);
$leads = $ad->getLeads();
from facebookads.adobjects.ad import Ad

ad = Ad(<AD_ID>)
leads = ad.get_leads()
APINodeList<Lead> leads = new Ad(<AD_ID>, context).getLeads()
  .execute();
curl -G \
  -d 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v2.11/<AD_ID>/leads

The response of the above call will give a list of leads, which you can then use for whatever analysis you wish to do.

Step 4: Revoke lead read acess from user

In case you wish to disallow a user from reading leads, you as a page admin can do so by revoking read access from these users as follows:

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

$params = array(
'user_id' => <USER_ID>,
);

$response = Api::instance()->call(
'/me/leadgen_whitelisted_users',
RequestInterface::METHOD_DELETE,
$params);
from facebookads import FacebookAdsApi

params = {'user_id': <USER_ID>}
response = FacebookAdsApi.get_default_api()\
.call('DELETE', ('/me/leadgen_whitelisted_users',), params=params)
curl -X DELETE\
-d 'user_id=<USER_ID>' \
-d 'access_token=<PAGE_ACCESS_TOKEN>' \
https://graph.facebook.com/<API_VERSION>/<PAGE_ID>/leadgen_whitelisted_users

To learn more about the endpoint, please visit the Lead ads flexible permissioning endpoint page. More on lead ads can be found on our Marketing API docs.


Related News

February 09 2017

February 08 2017

November 09 2016

October 05 2016

September 12 2016

August 29 2016