Ad Account

Marketing API Version

Represents a business, person or other entity who creates and manage ads on Facebook. Multiple people can manage an account, and each person can have one or more levels of access to an account, by specifying roles, see Ad User. For example, query 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])

APINodeList<AdSet> adSets = new AdAccount(act_<AD_ACCOUNT_ID>, context).getAdSets()
  .requestNameField()
  .requestConfiguredStatusField()
  .requestEffectiveStatusField()
  .execute();

curl -G \
-d "fields=name" \
-d "access_token=<ACCESS_TOKEN>" \                                                     
"https://graph.facebook.com/act_<AD_ACCOUNT_ID>/adsets"

Limits

Limits on number of ad accounts per user do not apply to Business Manager API, <AD_ACCOUNT_ID>/userpermissions. See Business Manager. })

Limit	Value
Maximum number of ad accounts per person	25
Maximum number of people with access, 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	100k 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	100k 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	100k archived ad campaigns
Maximum number of images per ad account	Unlimited

Reading

An ad account is an account used for managing ads on Facebook.

Permissions

Developers usually request these permissions for this endpoint:

Marketing Apps

ads_management
ads_read

Page management Apps

No data

Other Apps

No data

Finding people with access to this 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])

APINodeList<AdAccountUser> adAccountUsers = new AdAccount(act_<AD_ACCOUNT_ID>, context).getUsers()
  .execute();

curl -G \                                                                          
-d "access_token=<ACCESS_TOKEN>" \                                                     
"https://graph.facebook.com/act_<AD_ACCOUNT_ID>/users"

Get list of accepted Terms of Service, where id is the Facebook terms of service content id:

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)

AdAccount adAccount = new AdAccount(act_<AD_ACCOUNT_ID>, context).get()
  .requestTosAcceptedField()
  .execute();

curl -G \
-d "fields=tos_accepted" \
"https://graph.facebook.com/act_<AD_ACCOUNT_ID>"

Sample Response:
{
  "tos_accepted": {
    "206760949512025": 1, 
    "215449065224656": 1
  }, 
}

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

Field	Description
`id` string	The string `act_{ad_account_id}` Default
`account_id` numeric string	The ID of the ad account Default
`account_status` unsigned int32	Status of the account `1 = ACTIVE` `2 = DISABLED` `3 = UNSETTLED` `7 = PENDING_RISK_REVIEW` `9 = IN_GRACE_PERIOD` `100 = PENDING_CLOSURE` `101 = CLOSED` `102 = PENDING_SETTLEMENT` `201 = ANY_ACTIVE` `202 = ANY_CLOSED`
`age` float	Amount of time the ad account has been open, in days
`agency_client_declaration` AgencyClientDeclaration	Details of the agency advertising on behalf of this client account, if applicable
`amount_spent` numeric string	Current total amount spent by the account. This can be reset.
`attribution_spec` list<AttributionSpec>	The attribution specification of ad account, including click through window length, view through window length, etc.
`balance` numeric string	Bill amount due
`business` Business	The Business Manager, if this ad account is owned by one.
`business_city` string	City for business address
`business_country_code` string	Country code for the business address
`business_name` string	The business name for the account
`business_state` string	State abbreviation for business address
`business_street` string	First line of the business street address for the account
`business_street2` string	Second line of the business street address for the account
`business_zip` string	Zip code for business address
`can_create_brand_lift_study` bool	If we can create a new automated brand lift study under the ad account.
`capabilities` list<string>	See capabilities
`created_time` datetime	The time the account was created in ISO 8601 format.
`currency` string	The currency used for the account, based on the corresponding value in the account settings. See supported currencies
`disable_reason` unsigned int32	The reason why the account was disabled. Possible reasons are: `0 = NONE` `1 = ADS_INTEGRITY_POLICY` `2 = ADS_IP_REVIEW` `3 = RISK_PAYMENT` `4 = GRAY_ACCOUNT_SHUT_DOWN` `5 = ADS_AFC_REVIEW` `6 = BUSINESS_INTEGRITY_RAR` `7 = PERMANENT_CLOSE` `8 = UNUSED_RESELLER_ACCOUNT`
`end_advertiser` numeric string	The ID of a Facebook Page or Facebook App
`end_advertiser_name` string	The name of a Facebook Page or Facebook App
`failed_delivery_checks` list<DeliveryCheck>	Failed delivery checks
`funding_source` numeric string	ID of the payment method. If the account does not have a payment method it will still be possible to create ads but these ads will get no delivery.
`funding_source_details` FundingSourceDetails	`ID` = ID of the payment method `COUPON` = Details of the Facebook Ads Coupon from the payment method `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 payment method is shown `TYPE` = Type of the funding source
`has_migrated_permissions` bool	Whether this account has migrated permissions
`io_number` numeric string	The IO number
`is_attribution_spec_system_default` bool	If the attribution specification of ad account is generated from system default values
`is_notifications_enabled` bool	Get the notifications status of the user for this ad account. This will return true or false depending if notifications are enabled or not.
`is_personal` unsigned int32	Indicates that this ad account is being used for private, non-business purposes which affects how value added tax (VAT) is assessed.
`is_prepay_account` bool	If this ad account is a prepay or postpay account
`is_tax_id_required` bool	If tax id for this ad account is required or not
`line_numbers` list<integer>	The line numbers
`media_agency` numeric string	The ID of a Facebook Page or Facebook Application
`min_campaign_group_spend_cap` numeric string	The minimum required spend cap of campaign group
`min_daily_budget` unsigned int32	The minimum daily budget for this ad account
`name` string	Name of the account. If the account name is not set, the name of the first admin visible to the user will be returned
`offsite_pixels_tos_accepted` bool	Indicates whether the offsite pixel Terms Of Service contract was signed. This feature can be accessible before v2.9.
`owner` numeric string	The ID of the account owner
`partner` numeric string	The ID of a Facebook Page or Facebook App
`rf_spec` ReachFrequencySpec	Reach and Frequency limits configuration. See Reach and Frequency
`salesforce_invoice_group_id` string	Get invoice group id if ad account in the invoice group which existed in salesforce
`show_checkout_experience` bool	Whether or not to show the pre-paid checkout experience to anadvertiser. If true, it's either because the advertiser is a NUXadvertiser that is eligible for checkout or they're PUX and alreadylocked in to checkout and haven't graduated to postpay.
`spend_cap` numeric string	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. cents for USD.
`tax_id` string	Tax ID
`tax_id_status` unsigned int32	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
`tax_id_type` string	Type of Tax ID
`timezone_id` unsigned int32	The timezone ID of this ad account.
`timezone_name` string	Name for the time zone
`timezone_offset_hours_utc` float	Time Zone difference from UTC
`tos_accepted` map<string, int32>	IDs of Terms of Service contracts signed
`user_role` numeric string	Role ID of the user

Edges

Edge	Description
`activities`	The activities of this ad account
`ad_place_page_sets`	The associated ad place page sets for this ad account
`adasset_feeds`	Ad Asset Feeds associated with this ad account
`adcreatives`	The ad creatives of this ad account
`adcreativesbylabels`	Search creatives associated with given labels within this ad account
`adimages`	The images associated with this account
`adlabels`	The labels associated with this ad account
`adlanguage_assets`	Language assets associated with this ad account
`adreportruns`	All bookmarked async runs of this ad account
`adreportschedules`	All scheduled reports of this ad account
`ads`	The ads of this ad account
`adsbylabels`	Search ads associated with given labels within this ad account
`adsets`	The adsets of this ad account
`adsetsbylabels`	Search ad sets associated with given labels within this ad account
`adspixels`	The associated tracking pixels for this ad account
`adtoplinedetails`	All IO topline details for this account
`adtoplines`	All IO lines for this account
`advertisable_applications`	All advertisable apps associated with this account
`advideos`	The videos associated with this account
`an_roas`	The audience network return on ad spend
`applications`	Applications connected to the ad accounts
`asyncadrequestsets`	The async ad request sets associated with this account
`broadtargetingcategories`	Broad targeting categories (BCTs) can be used for targeting
`business_activities`	The business activities related to this adaccount
`campaigns`	The ad campaigns of this ad account
`campaignsbylabels`	Search campaigns associated with given labels within this ad account
`customaudiences`	The custom audiences owned by/shared with this ad account
`customaudiencestos`	The custom audiences term of services available to the ad account
`delivery_estimate`	The delivery estimate for a given ad set configuration for this ad account.
`generatepreviews`	Generate previews for a creative specification
`insights`	Insights on advertising performance of this ad account
`instagram_accounts`	Instagram accounts connected to the ad accounts
`minimum_budgets`	Returns minimum daily budget values by currency.
`offline_conversion_data_sets`	List of Offline Conversion Data Sets available for this Ad Account
`partnercategories`	Partner categories can be used for targeting
`partners`	The ad partners of this ad account
`publisher_block_lists`	Publisher block lists owned by this account. These list are used to block publishers on Audience Network
`ratecard`	Rate card of an ad account
`reachestimate`	The reach estimate of a given targeting spec for this ad account
`reachfrequencypredictions`	The reach and frequency predictions of this ad account
`roas`	The return on ad spend
`targetingsentencelines`	The targeting description sentence for a given target spec
`tracking`	List of tracking specs for this Ad Account
`transactions`	The transactions of this ad account
`users`	Container for the user ID, permissions, and role

Validation Rules

Error	Description
100	Invalid parameter
200	Permissions error
274	The 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
273	This Ads API call requires the user to be admin of the ad account
278	Reading advertisements requires an access token with the extended permission ads_read
272	This Ads API call requires the user to be admin of the application
294	Managing advertisements requires an access token with the extended permission for ads_management
1150	An unknown error occurred.
2608	The account is not a corporate account.

Creating

To create a new ad account for your business you must specify name, currency, timezone_id, end_advertiser, media_agency, and partner. Provide end_advertiser, media_agency, and partner:

They must be Facebook Page Aliases, Facebook Page ID or an Facebook app ID. For example, to provide your company as an end advertiser you specify my company or 20531316728.
If your ad account has no End Advertiser, Media Agency, or Partner, specify NONE.
If your ad account has an End Advertiser, Media Agency, or Partner, that are not represented on Facebook by Page or app, specify UNFOUND.

Once you set end_advertiser to a value other than NONE or UNFOUND you cannot change it.

Create an ad account:

curl \
-F "name=MyAdAccount" \
-F "currency=USD" \
-F "timezone_id=1" \
-F "end_advertiser=<END_ADVERTISER_ID>" \
-F "media_agency=<MEDIA_AGENCY_ID>" \
-F "partner=NONE" \
-F "access_token=<ACCESS_TOKEN>" \
"https://graph.facebook.com/<API_VERSION>/<BUSINESS_ID>/adaccount"

If you have an extended credity line with Facebook, you can set invoice to true and we associate your new ad account to this credit line.

The response:

{
  "id": "act_<ADACCOUNT_ID>",
  "account_id": "<ADACCOUNT_ID>",
  "business_id": "<BUSINESS_ID>",
  "end_advertiser_id": "<END_ADVERTISER_ID>",
  "media_agency_id": "<MEDIA_AGENCY_ID>",
  "partner_id": "NONE"
}

You can make a POST request to adaccounts edge from the following paths:

/{offsite_pixel_id}/adaccounts

When posting to this edge, an AdAccount will be created.

Parameters

Name	Description
`adaccounts` list<string>	List of ad account IDs to add Required

Return Type

This endpoint supports read-after-write and will read the node to which you POSTed.

Struct {

success: bool,

}

You can make a POST request to adaccount edge from the following paths:

/{business_id}/adaccount

When posting to this edge, an AdAccount will be created.

Parameters

Name	Description
`billing_address_id` numeric string or integer	The ID of the billing address that will be used for this account if on invoicing
`currency` ISO 4217 Currency Code	The currency used for the account Required
`end_advertiser`	The entity the ads will target. Must be a Facebook Page Alias, Facebook Page ID or an Facebook App ID. In absence of one, you can use `NONE` or `UNFOUND`. Note that once a value other than `NONE` or `UNFOUND` is set, it cannot be modified any more. Required
`funding_id` numeric string or integer	ID of the payment method. If the account does not have a payment method it will still be possible to create ads but these ads will get no delivery.
`invoice` boolean	If business manager has Business Manager Owned Normal Credit Line on file on the FB CRM, it will attach the ad account to that credit line.
`io` boolean	If corporate channel is direct sales.
`media_agency` string	The agency, this could be your own business. Must be a Facebook Page Alias, Facebook Page ID or an Facebook App ID. In absence of one, you can use `NONE` or `UNFOUND` Required
`name` string	The name of the ad account Required
`partner` string	This could be FBMP or FBX parthner if there is one. Must be a Facebook Page Alias, Facebook Page ID or an Facebook App ID. In absence of one, you can use `NONE` or `UNFOUND` Required
`po_number` string	Purchase order number
`timezone_id` unsigned int32	ID for the timezone. See here. Required

Return Type

This endpoint supports read-after-write and will read the node represented by id in the return type.

Struct {

id: token with structure: AdAccount ID,

account_id: numeric string,

business_id: numeric string,

end_advertiser_id: string,

media_agency_id: string,

partner_id: string,

}

You can make a POST request to adaccounts edge from the following paths:

/{custom_audience_id}/adaccounts

When posting to this edge, an AdAccount will be created.

Parameters

Name	Description
`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,

}

You can make a POST request to adaccounts edge from the following paths:

/{business_id}/adaccounts

When posting to this edge, an AdAccount will be created.

Parameters

Name	Description
`access_type` enum {OWNER, AGENCY}	access type Required
`adaccount_id` string	ID of ad account Required
`permitted_roles` list<enum {ADMIN, GENERAL_USER, REPORTS_ONLY, INSTAGRAM_ADVERTISER, INSTAGRAM_MANAGER, FB_EMPLOYEE_DSO_ADVERTISER}>	permitted roles

Return Type

This endpoint supports read-after-write and will read the node to which you POSTed.

Struct {

access_status: string,

}

You may perform a POST request to the following edges from this node:

Validation Rules

Error	Description
200	Permissions error
100	Invalid parameter
274	The 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

Updating

You can update an AdAccount by making a POST request to /act_{ad_account_id}.

Permissions

Developers usually request these permissions for this endpoint:

Marketing Apps

ads_management

Page management Apps

No data

Other Apps

No data

Parameters

Name	Description
`agency_client_declaration` dictionary { string : <string> }	Details of the agency advertising on behalf of this client account
`attribution_spec` list<Object>	The account attribution specification. 1. CLICK_THROUGH element must be present 2. If VIEW_THROUGH is present, window_days of VIEW_THROUGH must be smaller than or equal to that of CLICK_THROUGH
`event_type` enum {CLICK_THROUGH, VIEW_THROUGH}	Required
`window_days` int64	Required
`business_info` dictionary { string : <string> }	Business Info
`end_advertiser` numeric string	The ID of a Facebook Page or Facebook App. Once it is set to any values other than `NONE` or `UNFOUND`, it cannot be modified any more
`is_notifications_enabled` boolean	If notifications are enabled or not for this account
`media_agency` numeric string	The ID of a Facebook Page or Facebook App
`name` string	The name of the ad account
`partner` numeric string	The ID of a Facebook Page or Facebook App
`redownload` boolean	Allows you to specify that you would like toretrieve all fields of the set in your response.False by default.
`spend_cap` float	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 standard denomination of the currency, e.g. 23.50 for USD $23.50.
`spend_cap_action` string	Setting this parameter to `reset` sets the `amount_spent` back to 0. Setting it to `delete` removes the `spend_cap` from the account.

Return Type

This endpoint supports read-after-write and will read the node to which you POSTed.

Struct {

success: bool,

}

Validation Rules

Error	Description
200	Permissions error
100	Invalid parameter
274	The 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

Deleting

You can dissociate an AdAccount from an AdAccount by making a DELETE request to /act_{ad_account_id}/user_match.

Parameters

Name	Description
`bidirectional` boolean	Save both extern_id to fbuid and fbuid to extern_id mappings
`namespace` string	The namespace of the extern_id<>fbuid mapping.
`payload` Object	Contains the user's extern_id and PII data for matching. Required
`schema` list<string>
`data` list<list<string>>

Return Type

Struct {

account_id: numeric string,

num_received: numeric string,

num_valid: numeric string,

num_matched: string,

invalid_entry_samples: Map {

string: string

}

You can dissociate an AdAccount from an AdAccount by making a DELETE request to /act_{ad_account_id}/tracking.

Parameters

Name	Description
`tracking_specs` Object	Tracking specs to be removed from the account Required

Return Type

Struct {

success: bool,

}

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

Parameters

Name	Description
`adaccounts` list<numeric string>	Array of ad account IDs to revoke access to the custom audience

Return Type

Struct {

success: bool,

}

You can dissociate an AdAccount from an AdAccount by making a DELETE request to /act_{ad_account_id}/agencies.

Parameters

Name	Description
`business` numeric string or integer	business Required

Return Type

Struct {

success: bool,

}

You may perform a DELETE request to the following edges from this node:

Validation Rules

Error	Description
100	Invalid parameter