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:
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);
Note that you can only grant read access to the users who have some role on the page.
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');
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
/<LEAD_ID> 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.
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);