Share Custom Audiences between Business Managers

The Business Manager API establishes 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.

Since 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: true,
    sharing_data : [
     {         
       "ad_acct_id": "<AD_ACCOUNT_ID>"
       "audience_share_status" : "in progress"
       "errors" : []
     },
     ...
    ]
}

Options and parameters for this request include:

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

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>"
       "audience_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>"
       "audience_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>"
       "audience_share_status" : "shared"
       "errors" : []
    }
    {         
       "ad_acct_id": "<AD_ACCOUNT_ID>"
       "audience_share_status" : "in progress"
       "errors" : []
    }
    {         
       "ad_acct_id": "<AD_ACCOUNT_ID>"
       "audience_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?fields=custom_audiences,initiator,recipient,relationship_type,request_status,request_type

The response looks like this:

{
    "data": [   
        {         
           "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>"
                }
            ]     
         }
         ...
    ],
    "paging": {
        "cursors": {
            "before": "<CURSOR>",
            "after": "<CURSOR>"
        }
    }
}

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

GET <BUSINESS_ID>/initiated_audience_sharing_requests?fields=custom_audiences,initiator,recipient,relationship_type,request_status,request_type

The response looks like this:

{
    "data": [
        {         
            "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>"
                }
            ]    
        }
        ...
    ],
    "paging": {
        "cursors": {
            "before": "<CURSOR>",
            "after": "<CURSOR>"
        }
    }
}