Business-to-Business Functions
As of June 8, 2021, access to these endpoints is limited. Apps without access will receive an error.
Request Access to Assets
A Business Manager may request access to an ad account or Page owned by another Business Manager. They must specify the tasks that they want to assign in the request.
Assigning a business to a Page requires a page token; for example:
curl -F "business=<BUSINESS_ID>" -F "permitted_tasks=['MODERATE', 'ADVERTISE', 'ANALYZE']" "https://graph.facebook.com/<API_VERSION>/<PAGE_ID>/agencies?access_token=<ACCESS_TOKEN>"
To request AGENCY access, you must provide permitted_tasks in your request. You can only send request to assets to Business Manager that you intend to approve and that they must already know your business.
For example, a business that needs access to adaccount_id and needs to be able to assign its employees as ['ADVERTISE', 'ANALYZE'] would make this POST call:
curl \ -F "adaccount_id=act_<AD_ACCOUNT_ID>" \ -F "permitted_tasks=['ADVERTISE','ANALYZE']" \ "https://graph.facebook.com/<API_VERSION>/<BUSINESS_ID>/client_ad_accounts?access_token=<ACCESS_TOKEN>"
Similarly for a Page, if you want to assign ['ADVERTISE', 'ANALYZE'] tasks for a Page someone does not own:
curl \ -F "page_id=<PAGE_ID>" \ -F "permitted_tasks=['ADVERTISE','ANALYZE']" \ "https://graph.facebook.com/<API_VERSION>/<BUSINESS_ID>/client_pages?access_token=<ACCESS_TOKEN>"
These calls send out a notification to the respective admins of the ad account or Page, which asks to accept the access request. The respective admins will see the notification in Ads Manager or Pages Manager. They can also accept the request in the user interface. If you want to see outstanding requests via the API, make a GET request and check PENDING for the access_status field.
curl "https://graph.facebook.com/<API_VERSION>/<BUSINESS_ID>/clients?access_token=<ACCESS_TOKEN>"
The response:
"data": [
{
"name": "Random Page",
"page_permissions": [
{
"id": "1900952844321",
"permitted_tasks": [
'MANAGE',
'CREATE_CONTENT',
'MODERATE',
'ADVERTISE',
'ANALYZE',
],
"access_status": "CLIENT_RESPONSE_PENDING",
"access_requested_time": "2014-01-07T23:26:09+0000",
"access_updated_time": "2014-01-07T23:26:09+0000"
}
],
"id": "190137931178903"
},Grant Access to Assets for Another Business Manager
This is also known as adding an Agency to your object.
To accept an access request of an object you own from another business manager, or to give access of one of the objects you own to another business manager, you must specify the business and the list of tasks they should have access to.
If the access token used to make the API call belongs to a user or system user who has access to the requested asset via a business, the access to the asset can only be granted if this business is the OWNER of the asset. You cannot grant access to assets of which you are just an AGENCY.
For example, to give someone access to an ad account using the [ADVERTISE,ANALYZE] tasks, use this POST request:
curl \ -F "business=<BUSINESS_ID>" \ -F "permitted_tasks=['ADVERTISE', 'ANALYZE']" \ "https://graph.facebook.com/<API_VERSION>/act_<AD_ACCOUNT_ID>/agencies?access_token=<ACCESS_TOKEN>"
To give a business access to your page with [ADVERTISE], [MODERATE] and [ANALYZE]:
curl \ -F "business=<BUSINESS_ID>" \ -F "permitted_tasks=['MODERATE', 'ADVERTISE', 'ANALYZE']" \ "https://graph.facebook.com/<API_VERSION>/<PAGE_ID>/agencies?access_token=<ACCESS_TOKEN>"
In the case of granting access to an ad account, a review from another business admin is sometimes required as a security measure. This review can be approved by navigating to https://business.facebook.com/settings/requests/admin_reviews. In this case, the response will have an additional field indicating review is required.
{
"success": true,
"requires_admin_approval": true
}Page admins can also accept a agency access requests in the Manage Admin Roles tabs in Page Settings on facebook.com.
Remove Access to Assets
This is also known as removing an agency from your business. To remove a business managers's access from your ad account:
curl \ -X DELETE \ -F "business=<BUSINESS_ID>" \ "https://graph.facebook.com/<API_VERSION>/act_<AD_ACCOUNT_ID>/agencies?access_token=<ACCESS_TOKEN>"
Similarly, to remove a Business's access from your Page:
curl \ -X DELETE \ -F "business=<BUSINESS_ID>" \ "https://graph.facebook.com/<API_VERSION>/<PAGE_ID>/agencies?access_token=<ACCESS_TOKEN>"
View Agency Access
To see all the businesses that have access to your ad account with a GET call:
curl "https://graph.facebook.com/<API_VERSION>/act_<AD_ACCOUNT_ID>/agencies?access_token=<ACCESS_TOKEN>"
To see all the businesses that have access to your page:
curl "https://graph.facebook.com/<API_VERSION>/<PAGE_ID>/agencies?access_token=<ACCESS_TOKEN>"
To see all the businesses that have access to your business assets:
curl "https://graph.facebook.com/<API_VERSION>/<BUSINESS_ID>/agencies?access_token=<ACCESS_TOKEN>"
View Client Access
To see all the businesses that have given you access to one or more of their ad accounts or pages, use this GET call:
curl "https://graph.facebook.com/<API_VERSION>/<BUSINESS_ID>/clients?access_token=<ACCESS_TOKEN>"
Managing Your Relationship as an Ad Agency Acting on Behalf of Another Business
These APIs allow you to manage the relationship between your Ad Accounts and the businesses for which you are acting on behalf of (OBO). Creating these relationships allows you to access custom audiences for the business and use of the audience overlap tool.
View OBO Request Details
To view the details of an OBO request, make this GET request:
curl -G \ -F "access_token=<ACCESS_TOKEN>" \ "https://graph.facebook.com/<API_VERSION>/<OBO_REQUEST_ID>?fields=id,receiving_business,requesting_business,status,business_owned_object"
The response contains the details of the OBO request and looks like this:
{
"id": "1111111111",
"receiving_business": {
"id": "2222222222",
"name": "Example Business Name"
},
"requesting_business": {
"id": "3333333333",
"name": "Example Business Name"
},
"status": "IN_PROGRESS",
"business_owned_object": "1111111111"
}Delete OBO Request
To cancel a pending request to act OBO another business, make this DELETE request:
curl \ -X DELETE \ -F "access_token=<ACCESS_TOKEN>" \ "https://graph.facebook.com/<API_VERSION>/<OBO_REQUEST_ID>"
The response, indicating success or failure, looks like this:
{
"success": "true"
}View the Status of OBO Requests for an Ad Account
To view the status of requests to act OBO another business for an Ad account, make this GET request:
curl -G \
-F "access_token=<ACCESS_TOKEN>" \
"https://graph.facebook.com/<API_VERSION>/act_<AD_ACCOUNT_ID>/onbehalf_requests?
fields=id,status,receiving_business,requesting_business&status=<STATUS>"The status parameter in the request must be APPROVE, DECLINE, or IN_PROGRESS.
The response contains an array with the OBO request objects for an Ad account matching the requested status.
Example response:
{
"data": [
{
"id": "1111111111",
"status": "IN_PROGRESS",
"receiving_business": {
"id": "2222222222",
"name": "Example Business Name"
},
"requesting_business": {
"id": "3333333333",
"name": "Example Business Name"
}
}
]
}View OBO Requests Received From Other Businesses
To view requests of IN_PROGRESS OBO requests sent to your business, make this GET request:
curl -G \ -F "access_token=<ACCESS_TOKEN>" \ "https://graph.facebook.com/<API_VERSION>/<BUSINESS_ID>/received_inprogress_onbehalf_requests"
The response contains the IN_PROGRESS OBO request IDs and looks like this:
{
"data": [
{
"id": "1111111111"
},
{
"id": "2222222222"
},
{
"id": "3333333333"
}
]
}View Pending OBO Requests Sent by Your Business
To view OBO requests that were sent by your business that are still in the IN_PROGRESS state, make this GET request:
curl -G \ -F "access_token=<ACCESS_TOKEN>" \ "https://graph.facebook.com/<API_VERSION>/<BUSINESS_ID>/sent_inprogress_onbehalf_requests"
The response contains the IN_PROGRESS OBO request IDs and looks like this:
{
"data": [
{
"id": "1111111111"
},
{
"id": "2222222222"
},
{
"id": "3333333333"
}
]
}