Marketing API Version

Ad Account Group

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.

Reading

An ad account group allows managing user access to multiple Facebook ad accounts as a single unit.

If you want to learn how to use the Graph API, read our Using Graph API guide.

Parameters

This endpoint doesn't have any parameters.

Fields

FieldDescription

id

id

ID of this ad account group, it's the same as account_group_id

account_group_id

id

ID of this ad account group

accounts

list<AdAccountGroupAdAccounts>

The accounts in an account group in which the users have access

name

string

Name for the account group.

status

unsigned int32

Determines whether the account has a status of active (1) or deleted (2)

users

The users who own the ad account group

Edges

EdgeDescription

adaccounts

The ad accounts in the ad account group

Validation Rules

ErrorDescription
100Invalid parameter

Creating

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

Parameters

NameDescription
accounts
dictionary

The ad accounts in the ad account group to which the users have access

name
string

Name for the ad account group

Required
redownload
boolean

Allows you to specify that you would like to retrieve all fields of the set in your response. Default value: false.

users
dictionary

The users who own the ad account group

Return Type

Struct {
id: numeric string,
data: Struct {
account_group_id: id,
name: string,
status: unsigned int32,
users: List [
Struct {
uid: id,
role: unsigned int32,
}
],
accounts: List [
Struct {
uid: id,
role: unsigned int32,
}
],
},
}

Validation Rules

ErrorDescription
100Invalid parameter

Updating

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.

use FacebookAds\Object\AdAccountGroup;
use FacebookAds\Object\Fields\AdAccountGroupFields;

$adaccountgroup = new AdAccountGroup(<AD_ACCOUNT_GROUP_ID>);
$adaccountgroup->{AdAccountGroupFields::NAME} = 'New AdAccountGroup Name';
$adaccountgroup->update();

echo $adaccountgroup->{AdAccountGroupFields::NAME}.PHP_EOL;
from facebookads.adobjects.adaccountgroup import AdAccountGroup

adaccountgroup = AdAccountGroup(<AD_ACCOUNT_GROUP_ID>)
adaccountgroup[AdAccountGroup.Field.name] = 'New AdAccountGroup Name'
adaccountgroup.remote_update()
new AdAccountGroup(<AD_ACCOUNT_GROUP_ID>, context).update()
  .setName("New AdAccountGroup Name")
  .execute();
curl \
  -F 'name=New AdAccountGroup Name' \
  -F 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v2.7/<AD_ACCOUNT_GROUP_ID>
You can update an AdAccountGroup by making a POST request to /{ad_account_group_id}.

Parameters

NameDescription
accounts
dictionary

The accounts in an account group in which the users have access

name
Base64 UTF-8 encoded string

Name for the account group

redownload
boolean

Allows you to specify that you would like to retrieve all fields of the set in your response. Default value: false.

status
unsigned int32

Determines whether the account has a status of active (1) or deleted (2)

users
dictionary

Users and roles in an account group

Return Type

Struct {
result: bool,
data: Struct {},
} Or Struct {
success: bool,
}
You can update an AdAccountGroup by making a POST request to /{ad_account_group_id}/users.

Parameters

NameDescription
account_group_roles
list<dictionary>

List of user and their roles to be added, for example [{"uid": 12345, "role": 1001}, {"uid": 54321, "role": 1001}].

Required
uid
int

ID of users

Required
role
unsigned int32

Role of the users. The roles are:
1001: Administrator access
1002: General-user access
1003: Reports-only access

Required
redownload
boolean

Allows you to specify that you would like to retrieve all fields of the set in your response. Default value: false.

Return Type

Struct {
success: bool,
} Or Struct {
success: bool,
account_group: Struct {
account_group_id: id,
name: string,
status: unsigned int32,
users: List [
Struct {
uid: id,
permissions: List [
unsigned int32
],
role: integer,
}
],
accounts: List [
Struct {
account_id: string,
account_group_id: id,
status: unsigned int32,
name: string,
}
],
},
}
You can update an AdAccountGroup by making a POST request to /{ad_account_group_id}/adaccounts.

Parameters

NameDescription
account_ids
list<numeric string>

List of ad account IDs

Required
redownload
boolean

Allows you to specify that you would like to retrieve all fields of the set in your response. Default value: false.

Return Type

Struct {
success: bool,
} Or Struct {
success: bool,
account_group: Struct {
account_group_id: id,
name: string,
status: unsigned int32,
users: List [
Struct {
uid: id,
permissions: List [
unsigned int32
],
role: integer,
}
],
accounts: List [
Struct {
account_id: string,
account_group_id: id,
status: unsigned int32,
name: string,
}
],
},
}

Validation Rules

ErrorDescription
100Invalid parameter

Deleting

You can delete an AdAccountGroup by making a DELETE request to /{ad_account_group_id}.

Parameters

This endpoint doesn't have any parameters.

Return Type

Struct {
success: bool,
}
You may perform a DELETE request to the following edges from this node: