Marketing API Version

Custom Audience Adaccounts

Sharing Audiences

This endpoint allows you to share audiences to other ad accounts.

Reading

The ad account ids associated with this custom audience

Graph API Explorer
GET /v2.10/{custom-audience-id}/adaccounts HTTP/1.1
Host: graph.facebook.com
/* PHP SDK v5.0.0 */
/* make the API call */
$request = new FacebookRequest(
  $session,
  'GET',
  '/{custom-audience-id}/adaccounts'
);
$response = $request->execute();
$graphObject = $response->getGraphObject();
/* handle the result */
/* make the API call */
FB.api(
    "/{custom-audience-id}/adaccounts",
    function (response) {
      if (response && !response.error) {
        /* handle the result */
      }
    }
);
/* make the API call */
new GraphRequest(
    AccessToken.getCurrentAccessToken(),
    "/{custom-audience-id}/adaccounts",
    null,
    HttpMethod.GET,
    new GraphRequest.Callback() {
        public void onCompleted(GraphResponse response) {
            /* handle the result */
        }
    }
).executeAsync();
// For more complex open graph stories, use `FBSDKShareAPI`
// with `FBSDKShareOpenGraphContent`
/* make the API call */
FBSDKGraphRequest *request = [[FBSDKGraphRequest alloc]
                               initWithGraphPath:@"/{custom-audience-id}/adaccounts"
                                      parameters:params
                                      HTTPMethod:@"GET"];
[request startWithCompletionHandler:^(FBSDKGraphRequestConnection *connection,
                                      id result,
                                      NSError *error) {
    // Handle the result
}];

Permissions

Developers usually request these permissions for this endpoint:

Marketing Apps
  • ads_management
  • ads_read
Page management Apps
No data
Other Apps
No data

Parameters

NameDescription
permissions
string

Optional permission filter for the shared ad account IDs. Values can be targeting for getting account IDs with only targeting permissions, or targeting_and_insights to get account IDs with both targeting and insights permissions.If not set, it will return all shared ad account IDs.

Fields

Reading from this edge will return a JSON formatted result:

{ "data": [], "paging": {} }

data

A list of CustomAudienceAdAccount nodes.

paging

For more details about pagination, see the Graph API guide.

Validation Rules

ErrorDescription
275Cannot determine the target object for this request. Currently supported objects include ad account, business account and associated objects.
274The ad account is not enabled for usage in Ads API. Please add it in developers.facebook.com/apps -> select your app -> settings -> advanced -> advertising accounts -> Ads API

Creating

To share audiences with other ad accounts, a business must claim the owner ad account and recipient ad accounts.

The recipient ad account can include or exclude the shared custom audience in targeting spec. Optionally, the recipient ad account can also have the access to view the audience insights with the insights tool. If the optional permissions parameter is not set, the default is targeting_and_insights.

The destination account cannot modify the audience or use it as a seed audience to create lookalikes.

You can make a POST request to adaccounts edge from the following paths:
When posting to this edge, an AdAccount will be created.

Parameters

NameDescription
adaccounts
list<numeric string>

Array of new ad account IDs to receive access to the custom audience

permissions
string

targeting or targeting_and_insights. If targeting the recipient ad account can target the audience in ads. targeting_and_insights also allows recipient account to view the audience in Audience Insights tool

replace
boolean

true or false. If true the list of adaccounts provided in the call will replace the existing set of ad accounts this audience is shared with.

Return Type

This endpoint supports read-after-write and will read the node to which you POSTed.
Struct {
success: bool,
}

Validation Rules

ErrorDescription
100Invalid parameter
2658You cannot edit this audience
2652Failed to share with a bad ad account
2633This shared login is disabled. Go to Ads Manager for more information.

Updating

You can't perform this operation on this endpoint.

Deleting

You can also unshare an audience with an ad account by specifying an HTTP DELETE to the same endpoint with the adaccounts field set to the ad account you want to remove access. Any existing ads running from these accounts using this audience will be stopped and cannot be restarted.

You can dissociate an AdAccount from a CustomAudience by making a DELETE request to /{custom_audience_id}/adaccounts.

Parameters

NameDescription
adaccounts
list<numeric string>

Array of ad account IDs to revoke access to the custom audience

Return Type

Struct {
success: bool,
}

Validation Rules

ErrorDescription
100Invalid parameter