Marketing API Version

An ad account group allows managing user access to multiple Facebook ad accounts as a single unit. Business Manager is a newer product which provides functionality similar to that provided here, in addition to many other account management features.

Permissions

  • ads_management permission is needed to update ad account groups.
  • Because these calls can work with multiple accounts at once, they cannot be made by apps with Development or Basic Ads API Access.

With a Business Manager, an ad account group cannot be assigned to System User, thus the ad account group cannot be accessed by a System User. It still can be accessed by a regular user if access is granted outside the scope of Business Manager.

GET /v2.11/<AD_ACCOUNT_GROUP_ID> HTTP/1.1
Host: graph.facebook.com
/* PHP SDK v5.0.0 */
/* make the API call */
try {
  // Returns a `Facebook\FacebookResponse` object
  $response = $fb->get(
    '/<AD_ACCOUNT_GROUP_ID>',
    '{access-token}'
  );
} catch(Facebook\Exceptions\FacebookResponseException $e) {
  echo 'Graph returned an error: ' . $e->getMessage();
  exit;
} catch(Facebook\Exceptions\FacebookSDKException $e) {
  echo 'Facebook SDK returned an error: ' . $e->getMessage();
  exit;
}
$graphNode = $response->getGraphNode();
/* handle the result */
curl https://graph.facebook.com/v2.11/<AD_ACCOUNT_GROUP_ID>

Retrieving a list

Ad account groups can be retrieved directly using their IDs, or via the adaccountgroups connection of the Ad User object. An example of reading the current user's ad account groups is:

GET /v2.11/me/adaccountgroups HTTP/1.1
Host: graph.facebook.com
/* PHP SDK v5.0.0 */
/* make the API call */
try {
  // Returns a `Facebook\FacebookResponse` object
  $response = $fb->get(
    '/me/adaccountgroups',
    '{access-token}'
  );
} catch(Facebook\Exceptions\FacebookResponseException $e) {
  echo 'Graph returned an error: ' . $e->getMessage();
  exit;
} catch(Facebook\Exceptions\FacebookSDKException $e) {
  echo 'Facebook SDK returned an error: ' . $e->getMessage();
  exit;
}
$graphNode = $response->getGraphNode();
/* handle the result */
curl https://graph.facebook.com/v2.11/me/adaccountgroups

Response

If successful, the ad account group's details will be returned:

{
   "id" : "368121234",
   "name" : "Ad account group 1",
   "status" : "1",
   "users" : [ { "uid" : 9876554, "role" : 1001 } ],
   "accounts" : [ { "account_id" : 333444555, "status" : 2 } ]
}

Otherwise you'll receive the details of the error that occured.

Account group roles

After you create an account group, you use related calls to update the account group and give users the desired access to the ad accounts in the account group.

Account groups enable you to give a user a specific level of access to an entire set of accounts.

If a user is a member of an account group, they have the given level of access to all the accounts contained in the account group. A user is given the highest level of permission she has for any account in the group. For example, if Mary has reports-only access to Account ABC, but general-user access to an account group that contains Account ABC, Mary has the higher of the two permission levels. In this example, Mary's permission for all accounts in the account group will be general-user.

POST /v2.11/<AD_ACCOUNT_GROUP_ID> HTTP/1.1
Host: graph.facebook.com

name=Updated+Name
/* PHP SDK v5.0.0 */
/* make the API call */
try {
  // Returns a `Facebook\FacebookResponse` object
  $response = $fb->post(
    '/<AD_ACCOUNT_GROUP_ID>',
    array (
      'name' => 'Updated Name',
    ),
    '{access-token}'
  );
} catch(Facebook\Exceptions\FacebookResponseException $e) {
  echo 'Graph returned an error: ' . $e->getMessage();
  exit;
} catch(Facebook\Exceptions\FacebookSDKException $e) {
  echo 'Facebook SDK returned an error: ' . $e->getMessage();
  exit;
}
$graphNode = $response->getGraphNode();
/* handle the result */
curl -X POST \
     -d "name=Updated+Name" \
        https://graph.facebook.com/v2.11/<AD_ACCOUNT_GROUP_ID>