Business-to-Business Functions

Request Access to Assets

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 manger, 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//act_/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>"

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>"

Share Custom Audiences between Business Managers

These APIs establish clear roles and responsibilities when accessing an audience belonging to another business. When a Custom Audience is shared between parties, a partnership relationship must first be established between the Business Managers. This is in the Partners section of Business Settings in Business Manager. The party sharing the audience must also affirm their compliance with our Custom Audience terms of service provided in Business Manager, see Facebook, Custom Audience Terms.

Once established, a sharing relationship enables a business to share audiences with another Business Manager. However, audiences can only be shared in one direction. This means the audience is shared from Business #1 to Business #2. Business #2 will not be able to share audiences back to Business #1 unless a separate sharing relationship from Business #2 to #1 is established.

Starting from July 2, 2018 in order to share a Custom Audience between Business Managers, such businesses should establish an audience sharing relationship as follows. You need Business Manager admin permission to request a relationship to share an audience. If two Business Managers have already established the relationship, then an advertiser can directly share the audience with the other business. See also Reference, Custom Audience and Reference, Custom Audience Shared Account Info

To create a relationship, make this call, to a specific custom_audience_id:

POST {custom_audience_id}/adaccounts?adaccounts=[<ad_account_id>]&relationship_type=[<relationship_type>] 

We handle a request based on the relationship status with the other business:

  • For ad accounts which have an existing approved relationship, we share the audience directly with them.
  • For ad accounts which have an existing in progress relationship, we add the audience ID to the request so that when the recipient business approves this request, we then share the audience.
  • For ad accounts which do not have any relationship, we create a sharing agreement with the audience ID attached to it so that when the recipient business approves this request, we can then share of the audience.

Facebook returns a sharing_data object for each ad account passed into the request. For example:

{  
    success: bool,
    sharing_data : [
     {         
       "ad_acct_id": id
       "business_id": id
       "audience_share_status" : string
       "errors" : list<string>
     },
     ...
    ]
}

Options and parameters for this request include:

Level Description

adaccounts

type: list:numericstring

The IDs for ad accounts that you want to share the audience with.

relationship_type

type: list:string

Required.

Denotes the relationship between the business owning the audience and the recipient business with which the audience is shared. An array of all values which apply.


Possible Values: Audience Info Provider, Information Manager, Ad Optimizer, Agency

Examples

If you do not have admin permissions for Business Manager and you try to share an audience, you get an error similar to this:

[   
    {         
       "ad_acct_id": "<AD_ACCOUNT_ID>"
       "share_status" : "NOT_SHARED"
       "errors" : [
        "You don't have permission to initiate a sharing relationship for this ad account/business"
       ]
    }
...
]

After you make a request, the business that owns the recipient ad account may receive a pending shared audience relationship request, if they do not have a relationship with you. They can see this status on their Business Manager. At the point the business can approve or decline the relationship request:

POST <SHARING_RELATIONSHIP_ID>?request_response="approve"

On success, the business gets this response:

{  
    success: bool
}

Options include:

Name Description

request_response

type: string

Whether the business receiving a relationship requests approves or rejects the request.


Possible values: approve, decline

After the business that received a relationship request approves it, you can share audience with them. When you make a request, sharing_data looks like this:

[   
    {         
       "ad_acct_id": "<AD_ACCOUNT_ID>"
       "share_status" : "SHARED"
       "errors" : []
    }
...
]

If you are a Business Manager admin and share an audience with a pending relationship request, Facebook appends the audience ID with the existing relationship:

[   
    {         
       "ad_acct_id": "<AD_ACCOUNT_ID>"
       "share_status" : "IN_PROGRESS"
       "errors" : []
    }
...
]

Since you can specify multiple ad accounts in your request to share an audience, results for each account appear in the response:

[   
    {         
       "ad_acct_id": "<AD_ACCOUNT_ID>"
       "share_status" : "SHARED"
       "errors" : []
    }
    {         
       "ad_acct_id": "<AD_ACCOUNT_ID>"
       "share_status" : "IN_PROGRESS"
       "errors" : []
    }
    {         
       "ad_acct_id": "<AD_ACCOUNT_ID>"
       "share_status" : "NOT_SHARED"
       "errors" : [
        "You don't have permission to initiate a sharing relationship for this ad account/business"
       ]
    }
...
]

To view requests to share an audience received by your business:

GET <BUSINESS_ID>/received_audience_sharing_requests

The response looks like this:

[   
    {         
       "initiator": {            
           "id": "<BUSINESS_ID>",            
           "name": "business_name1"         
        }, 
        "recipient": {            
           "id": "<BUSINESS_ID>",            
           "name": "business_name2"         
        },         
        "request_status": "IN_PROGRESS",
        "relationship_type": "[<relationship_type>]",
        "id": "<SHARING_RELATIONSHIP_ID>",
        "custom_audiences": [
            {
                "id": "<CUSTOM_AUDIENCE_ID>",
                "name": "<CUSTOM_AUDIENCE_NAME>",
                "share_account_name": "<ACCOUNT_NAME>",
                "share_account_id": "<ACCOUNT_ID>",
            }
        ]     
     }
...
]

To view requests sent by your business to share an audience with others:

GET <BUSINESS_ID>/initiated_audience_sharing_requests

The response looks like this:

[   
    {         
       "initiator": {            
           "id": "<BUSINESS_ID>",            
           "name": "business_name1"         
        }, 
        "recipient": {            
           "id": "<BUSINESS_ID>",            
           "name": "business_name2"         
        },         
        "request_status": "IN_PROGRESS",
        "relationship_type": "[<relationship_type>]",         
        "id": "<SHARING_RELATIONSHIP_ID>",
        "custom_audiences": [
            {
                "id": "<CUSTOM_AUDIENCE_ID>",
                "name": "<CUSTOM_AUDIENCE_NAME>",
                "share_account_name": "<ACCOUNT_NAME>",
                "share_account_id": "<ACCOUNT_ID>",
            }
        ]    
     }
...
]

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.

Request Permission to Act OBO Another Business

To request permission to act OBO another business, make this POST call:

curl \
  -F "receiving_business=<CLIENT_BUSINESS_ID>" \
  -F "business_owned_object=act_<AD_ACCOUNT_ID>" \
  -F "access_token=<ACCESS_TOKEN>" \
  "https://graph.facebook.com/<BUSINESS_ID>/sent_inprogress_onbehalf_requests"

Call parameters:

  • receiving_business - The business ID of the client you are acting OBO
  • business_owned_object - Ad account ID, in act_123 form

The response contains the OBO request ID and looks like this:

{
  "id": "1234567890" 
}

The new request has an IN_PROGRESS state.

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/<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/<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/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/<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/<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"
    }
  ]
}