This document refers to a feature that was removed after Marketing API v3.2.
Marketing API Version

Ad account

Overview

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.

Read

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/v11.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.

NameDescriptionType

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_group_id (numeric string ID), name, and status

account_id

The ID of the ad account

long

account_status

Status of the account.
1 = Active
2 = Disabled
3 = Unsettled
7 = Pending Review
9 = In Grace Period
101 = temporarily unavailable
100 = pending closure.

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

ID = ID of the funding source
COUPON = Details of the Facebook Ads Coupon from the funding source
AMOUNT = Amount of Facebook Ads Coupon
CURRENCY = Currency of the Facebook Ads Coupon
DISPLAY_AMOUNT = How the amount of Facebook Ads Coupon is displayed
EXPIRATION = When the coupon will expire
DISPLAY_STRING = How the funding source is shown
TYPE = Type of the funding source

array

id

The string act_{ad_account_id}

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: web_custom_audience_tos
custom_audience_tos

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.
0: Unknown
1: VAT not required- US/CA
2: VAT information required
3: VAT information submitted
4: Offline VAT validation failed
5: Account is a personal 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 1 for accepted terms

object

users

Container for the user ID, permissions, and role

array of objects with three fields: id, permissions, and role

Description of the fields in array agency_client_declaration:

NameDescriptionType

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

Update

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/v11.0/act_<AD_ACCOUNT_ID>

with the following mutable fields:

You can only update one field at a time.

NameDescriptionType

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 amount_spent. 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

integer

spend_cap_action

Setting this parameter to reset sets the amount_spent back to 0. Setting it to delete removes the spend_cap from the account.

string

The response will be true.

Connections

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 MethodDescription Type

activities
getActivities

Information on any activity that has occured on this account

Dependent on input, see activity log documentation

adcampaign_groups
getAdCampaigns

The ad campaigns in the account

array of ad campaign objects

adcampaignconversions
getAdCampaignConversions

Conversion data for all Ad sets under an Ad account.

Conversion stat object

adcampaigns
getAdSets

The ad sets in the account

array of ad set objects

adcampaignstats
getAdCampaignStats

The statistics for the account by ad campaign

array of adstatistics objects

adcreatives
getAdCreatives

The creatives in the account's creative library

array of adcreative objects

adgroupconversions
getAdGroupConversions

Conversion data for all Ad groups under an Ad account.

Conversion stat object

adgroups
getAdGroups

The ads of the account

array of adgroup objects

adgroupstats
getAdGroupStats

The statistics for the account by ad group

array of adstatistics objects

adimages
getAdImages

The ad images of the account

array of adimage objects

adpreviewscss
getAdPreviews

The Ad Preview CSS for the account

Ad Preview CSS snippet

advideos
getAdVideos

The ad videos of the account

array of advideo objects

broadtargetingcategories
getBroadTargetingCategories

Array of broad category targeting (BCT) that you can specify for ads

array of broadcategorytargeting objects

connectionobjects
getConnectionObjects

The Connection Objects of the ad account user

array of connectionobjects objects

conversions
getConversions

Conversion data aggregated from all adgroups, including deleted.

Conversion stat object

customaudiences
getCustomAudiences

Custom audiences accessible by this account

array of custom audiences

partnercategories
getPartnerCategories

Partner categories accessible by this account

array of partner categories

ratecard
getRateCard

The Rate Cards for Homepage Ads for this account

array of objects containing the country, currency and price for each rate

reachestimate
getReachEstimate

Used to estimate the reach of intended targeting

array of reachestimate objects

reportstats
getReportsStats

The statistics for the account using the new Ad Report Stats API

Dependent on input, see report stats documentation

stats
getStats

The statistics for the account in aggregate

array of adstatistics objects

transactions
getTransactions

The payment order for the account

Payment Order object

users
getUsers

The users of the ad account

array of aduser objects

Capabilities

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.

CapabilityDescription

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

Limits

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.

LimitValue

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

Examples

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
  }, 
}