An ad account is an used for managing ads of Facebook. Each ad account can be managed by multiple users, and users can have one or more different levels of access to an account, configured by specifying roles for each user.
To read information about an ad account:
use FacebookAds\Object\AdAccount;
use FacebookAds\Object\Fields\AdAccountFields;
$account = new AdAccount('act_<AD_ACCOUNT_ID>');
$fields = array(
AdAccountFields::NAME,
AdAccountFields::BALANCE,
);
$account->read($fields);
echo $account->{AdAccountFields::NAME}.PHP_EOL;
echo $account->{AdAccountFields::BALANCE}.PHP_EOL;
from facebookads.adobjects.adaccount import AdAccount
account = AdAccount('act_<AD_ACCOUNT_ID>')
account.remote_read(fields=[
AdAccount.Field.name,
AdAccount.Field.balance,
])
print(account[AdAccount.Field.name])
print(account[AdAccount.Field.balance])
curl -X GET -G \
-d 'access_token=<ACCESS_TOKEN>' \
https://graph.facebook.com/v10.0/act_<AD_ACCOUNT_ID>
You must specify which fields of the account you want returned using the fields
parameter - only id
is returned by default.
Name | Description | Type |
---|---|---|
account_groups | Container for the ID, name, and status of the ad account groups which contain this account | array of objects with three fields: |
account_id | The ID of the ad account | long |
account_status | Status of the account. | integer |
age | Amount of time the ad account has been open, in days | float |
agency_client_declaration | Details of the agency advertising on behalf of this client account, if applicable. See table below for more detail | object |
amount_spent | Current total amount spent by the account. This can be reset. | numeric string |
balance | Bill amount due | numeric string |
business | The Business Manager, if this ad account is owned by one. | object |
business_city | City for business address | string |
business_country_code | Country code for the business address | string |
business_name | The business name for the account | string |
business_state | State abbreviation for business address | string |
business_street | First line of the business street address for the account | string |
business_street2 | Second line of the business street address for the account | string |
business_zip | Zip code for business address | string |
capabilities | See capabilities | array |
created_time | The time the account was created in ISO 8601 format. | datetime |
currency | The currency used for the account, based on the corresponding value in the account settings. The list of supported currencies can be found here | string |
end_advertiser | The ID of a Facebook Page or Facebook App | long |
funding_source | ID of the funding source. If the account does not have a funding source it will still be possible to create ads but these ads will get no delivery. | numeric string ID |
funding_source_details |
| array |
id | The string | string |
is_personal | If this is a personal or business account | integer |
media_agency | The ID of a Facebook Page or Facebook App | long |
name | Name of the account; note that many accounts are unnamed, so this field may be empty | string |
offsite_pixels_tos_accepted | Indicates whether the offsite pixel Terms Of Service contract was signed. There are the following ToS at this moment: | boolean |
partner | The ID of a Facebook Page or Facebook App | long |
rf_spec | Reach and Frequency limits configuration. See Reach and Frequency | object |
spend_cap | The maximum that can be spent by this account after which campaigns will be paused. A value of 0 signifies no spending-cap and setting a new spend cap only applies to spend AFTER the time at which you set it. Value specified in basic unit of the currency, e.g. dollars for USD | numeric string |
tax_id_status | Vat status code for the account. | integer |
timezone_id | ID for the timezone. See here | integer |
timezone_name | Name for the time zone | string |
timezone_offset_hours_utc | Time Zone difference from UTC | integer |
tos_accepted | Terms of Service contracts signed as keys. Value is | object |
users | Container for the user ID, permissions, and role | array of objects with three fields: |
Description of the fields in array agency_client_declaration
:
Name | Description | Type |
---|---|---|
agency_representing_client | Whether this account is for an agency representing a client | integer |
client_based_in_france | Whether the client is based in France | integer |
client_city | Client's city | string |
client_country_code | Client's country code | string |
client_email_address | Client's email address | string |
client_name | Name of the client | string |
client_postal_code | Client's postal code | string |
client_province | Client's province | string |
client_street | First line of client's street address | string |
client_street2 | Second line of client's street address | string |
has_written_mandate_from_advertiser | Whether the agency has a written mandate to advertise on behalf of this client | integer |
is_client_paying_invoices | Whether the client is paying via invoice | integer |
To update the below fields of an ad account, make an HTTP POST call to
https://graph.facebook.com/act_<AD_ACCOUNT_ID>
use FacebookAds\Object\AdAccount;
use FacebookAds\Object\Fields\AdAccountFields;
$account = new AdAccount('act_<AD_ACCOUNT_ID>');
$account->{AdAccountFields::NAME} = "New Name";
$account->update();
from facebookads.adobjects.adaccount import AdAccount
account = AdAccount('act_<AD_ACCOUNT_ID>')
account[AdAccount.Field.name] = 'New Name'
account.remote_update()
curl -X GET -G \
-d 'access_token=<ACCESS_TOKEN>' \
https://graph.facebook.com/v10.0/act_<AD_ACCOUNT_ID>
with the following mutable fields:
You can only update one field at a time.
Name | Description | Type |
---|---|---|
agency_client_declaration | Details of the agency advertising on behalf of this client account | object |
media_agency | The ID of a Facebook Page or Facebook App | long |
name | The name of the ad account | string |
partner | The ID of a Facebook Page or Facebook App | long |
spend_cap | The total amount that this account can spend, after which all campaigns will be paused, based on | integer |
spend_cap_action | Setting this parameter to | string |
The response will be true
.
An Ad Account object has connections to other information. To query an account's connections:
use FacebookAds\Object\AdAccount;
use FacebookAds\Object\Fields\CampaignFields;
$account = new AdAccount('act_<AD_ACCOUNT_ID>');
$campaigns = $account->getCampaigns(array(
CampaignFields::NAME,
));
foreach ($campaigns as $campaign) {
echo $campaign->{CampaignFields::NAME}.PHP_EOL;
}
from facebookads.adobjects.adaccount import AdAccount
from facebookads.adobjects.campaign import Campaign
account = AdAccount('act_<AD_ACCOUNT_ID>')
campaigns = account.get_campaigns(fields=[
Campaign.Field.name,
])
for campaign in campaigns:
print(campaign[Campaign.Field.name])
curl -G \
-d "fields=<LIST_OF_FIELDS>" \
-d "access_token=<ACCESS_TOKEN>" \
"https://graph.facebook.com/act_<AD_ACCOUNT_ID>/<CONNECTION_NAME>"
The list below details which connections (and their methods) are available:
Connection Name / SDK Method | Description | Type |
---|---|---|
activities | Information on any activity that has occured on this account | Dependent on input, see activity log documentation |
adcampaign_groups | The ad campaigns in the account | array of ad campaign objects |
adcampaignconversions | Conversion data for all Ad sets under an Ad account. | Conversion stat object |
adcampaigns | The ad sets in the account | array of ad set objects |
adcampaignstats | The statistics for the account by ad campaign | array of adstatistics objects |
adcreatives | The creatives in the account's creative library | array of adcreative objects |
adgroupconversions | Conversion data for all Ad groups under an Ad account. | Conversion stat object |
adgroups | The ads of the account | array of adgroup objects |
adgroupstats | The statistics for the account by ad group | array of adstatistics objects |
adimages | The ad images of the account | array of adimage objects |
adpreviewscss | The Ad Preview CSS for the account | Ad Preview CSS snippet |
advideos | The ad videos of the account | array of advideo objects |
broadtargetingcategories | Array of broad category targeting (BCT) that you can specify for ads | array of broadcategorytargeting objects |
connectionobjects | The Connection Objects of the ad account user | array of connectionobjects objects |
conversions | Conversion data aggregated from all adgroups, including deleted. | Conversion stat object |
customaudiences | Custom audiences accessible by this account | array of custom audiences |
partnercategories | Partner categories accessible by this account | array of partner categories |
ratecard | The Rate Cards for Homepage Ads for this account | array of objects containing the country, currency and price for each rate |
reachestimate | Used to estimate the reach of intended targeting | array of reachestimate objects |
reportstats | The statistics for the account using the new Ad Report Stats API | Dependent on input, see report stats documentation |
stats | The statistics for the account in aggregate | array of adstatistics objects |
transactions | The payment order for the account | Payment Order object |
users | The users of the ad account | array of aduser objects |
List of capabilities an ad account can have. Make an HTTP GET call to act_<AD_ACCOUNT_ID>?fields=capabilities
endpoint in order to get all capabilities.
Capability | Description |
---|---|
BULK_ACCOUNT | Bulk accounts can create up to 10000 campaigns, 10000 adsets and 50000 adgroups while regular accounts can go up to 5000 for all objects |
CAN_CREATE_LOOKALIKES_WITH_CUSTOM_RATIO | Ability to set custom lookalike ratio. See lookalike audiences |
CAN_USE_CONVERSION_LOOKALIKES | Ability to use conversion lookalikes. See conversion lookalikes |
CAN_USE_MOBILE_EXTERNAL_PAGE_TYPE | Ad account can use mobile external page type for Mobile App Ads |
CAN_USE_MOBILE_EXTERNAL_PAGE_TYPE_FOR_LPP | Ad account can use mobile external page type for Link Page Post |
CAN_USE_REACH_AND_FREQUENCY | Ability to buy Reach and Frequency ads |
CUSTOM_CLUSTER_SHARING | Ability to share Custom Audiences |
DIRECT_SALES | Direct sales are accounts run entirely by Facebook Employees on behalf of advertisers who have purchased an Insertion Order |
HAS_AVAILABLE_PAYMENT_METHODS | This account has a available payment method for this ad account |
HOLDOUT_VIEW_TAGS | Ability to use third-party view tags for managing target restrictions over an audience |
PREMIUM | Ad account can buy ads on a fixed CPM. See Premium via API |
VIEW_TAGS | Ability to track impressions using third-party view tags |
The following are the limits on ad account.
This limit for number of ad accounts per user does not apply in context of the Business Manager when using the <AD_ACCOUNT_ID>/userpermissions
API. More information available here.
Limit | Value |
---|---|
Maximum number of ad accounts per user | 25 |
Maximum number of users per ad account | 25 |
Maximum number of ads per regular ad account | 5000 non-archived non-deleted ads |
Maximum number of ads per bulk ad account | 50000 non-archived non-deleted ads |
Maximum number of archived ads per ad account | 50k archived ads |
Maximum number of ad sets per regular ad account | 5000 non-archived non-deleted ad sets |
Maximum number of ad sets per bulk ad account | 10000 non-archived non-deleted ad sets |
Maximum number of archived ad sets per ad account | 50k archived ad sets |
Maximum number of ad campaigns per regular ad account | 5000 non-archived non-deleted ad campaigns |
Maximum number of ad campaigns per bulk ad account | 10000 non-archived non-deleted ad campaigns |
Maximum number of archived ad campaigns per ad account | 50k archived ad campaigns |
Maximum number of images per ad account | Unlimited |
Updating the spend cap of an ad account
use FacebookAds\Object\AdAccount;
use FacebookAds\Object\Fields\AdAccountFields;
$account = new AdAccount('act_<AD_ACCOUNT_ID>');
$account->{AdAccountFields::SPEND_CAP} = 1000;
$account->update();
from facebookads.adobjects.adaccount import AdAccount
account = AdAccount('act_<AD_ACCOUNT_ID>')
account[AdAccount.Field.spend_cap] = 10000
account.remote_update()
curl \
-F "spend_cap=1000" \
-F "access_token=<ACCESS_TOKEN>" \
"https://graph.facebook.com/act_<AD_ACCOUNT_ID>"
Querying for all ad sets in this ad account
use FacebookAds\Object\AdAccount;
use FacebookAds\Object\Fields\AdSetFields;
$account = new AdAccount('act_<AD_ACCOUNT_ID>');
$adsets = $account->getAdSets(array(
AdSetFields::NAME,
AdSetFields::CONFIGURED_STATUS,
AdSetFields::EFFECTIVE_STATUS,
));
foreach ($adsets as $adset) {
echo $adset->{AdSetFields::NAME}.PHP_EOL;
}
from facebookads.adobjects.adaccount import AdAccount
from facebookads.adobjects.adset import AdSet
account = AdAccount('act_<AD_ACCOUNT_ID>')
adsets = account.get_ad_sets(fields=[AdSet.Field.name])
for adset in adsets:
print(adset[AdSet.Field.name])
curl -G \
-d "fields=name" \
-d "access_token=<ACCESS_TOKEN>" \
"https://graph.facebook.com/act_<AD_ACCOUNT_ID>/adcampaigns"
Querying for the objects that this ad account's user is connected to
use FacebookAds\Object\AdAccount;
use FacebookAds\Object\Fields\ConnectionObjectFields;
$account = new AdAccount('act_<AD_ACCOUNT_ID>');
$objects = $account->getConnectionObjects();
foreach ($objects as $object) {
echo $object->{ConnectionObjectFields::NAME}.PHP_EOL;
}
from facebookads.objects import AdAccount
account = AdAccount('act_<AD_ACCOUNT_ID>')
objects = account.get_connection_objects()
for obj in objects:
print(obj[AdAccount.Field.name])
curl -G \
-d "access_token=<ACCESS_TOKEN>" \
"https://graph.facebook.com/act_<AD_ACCOUNT_ID>/connectionobjects"
Finding the list of users who have access to this ad account
use FacebookAds\Object\AdAccount;
use FacebookAds\Object\Fields\UserFields;
$account = new AdAccount('act_<AD_ACCOUNT_ID>');
$users = $account->getUsers();
foreach ($users as $user) {
echo $user->{UserFields::ID}.PHP_EOL;
}
from facebookads.adobjects.adaccount import AdAccount
from facebookads.adobjects.adaccountuser import AdAccountUser
account = AdAccount('act_<AD_ACCOUNT_ID>')
users = account.get_users()
for user in users:
print(user[AdAccountUser.Field.id])
curl -G \
-d "access_token=<ACCESS_TOKEN>" \
"https://graph.facebook.com/act_<AD_ACCOUNT_ID>/users"
Getting the list of tos accepted for this adaccount, where id is the Facebook object id of the terms of service content.
use FacebookAds\Object\AdAccount;
use FacebookAds\Object\Fields\AdAccountFields;
$account = new AdAccount('act_<AD_ACCOUNT_ID>');
$account->read(array(
AdAccountFields::TOS_ACCEPTED,
));
// Dump TOS Accepted info.
var_dump($account->{AdAccountFields::TOS_ACCEPTED});
from facebookads.adobjects.adaccount import AdAccount
account = AdAccount('act_<AD_ACCOUNT_ID>')
account.remote_read(fields=[AdAccount.Field.tos_accepted])
for tos in account[AdAccount.Field.tos_accepted]:
print(tos)
curl -G \
-d "fields=tos_accepted" \
"https://graph.facebook.com/act_<AD_ACCOUNT_ID>"
Sample Response:
{
"tos_accepted": {
"web_custom_audience_tos": 1,
"custom_audience_tos": 1
},
}