Marketing API Version

Ad Account

An ad account is an account used to manage ads on Facebook. Each ad account can be managed by multiple people, and each person can have one or more different levels of access to an account, configured by specifying roles for each user.

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

Reading

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

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

string

The string act_{ad_account_id}

account_groups

Container for the ID, name, and status of the ad account groups which contain this account

account_id

numeric string

The ID of the ad account

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.

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

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

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_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. More details on offsite-pixels can be found here

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

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

EdgeDescription

activities

The activities of this ad account

ad_place_page_sets

The associated ad place page sets for 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

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

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

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

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.

offsitepixels

Offsite pixels 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

transactions

The transactions of this ad account

users

Container for the user ID, permissions, and role

Validation Rules

ErrorDescription
100Invalid parameter
278Reading advertisements requires an access token with the extended permission ads_read

Creating

To create a new ad account for your business you must specify a name , currency , timezone_id, end_advertiser , media_agency , and partner . The latter 3 must be a Facebook Page Alias, Facebook Page ID or an Facebook app ID (for instance if you were going to mark your company as an end advertiser you would either specify my company or 20531316728 ). If your ad account doesn't have an End Advertiser, Media Agency, or Partner, please specify NONE . If your ad account has an End Advertiser, Media Agency, or Partner, but they are not represented on Facebook by either a Page or an app please specify UNFOUND . Note that for End Advertiser field, once a value other than NONE or UNFOUND is set it cannot be modified any more.

Examples

Sample call to 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"

Optionally, you may set the invoice to true. If you do your new ad account will be associated with your extended credit line. You must have already set up an extended credit line with Facebook to use this feature.

The response of this create call will be like this:

{
  "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:
When posting to this edge, an AdAccount will be created.

Parameters

NameDescription
adaccounts
list<string>

List of ad account IDs to add

Required

Return Type

Struct {
success: bool,
}
You can make a POST request to adaccount edge from the following paths:
When posting to this edge, an AdAccount will be created.

Parameters

NameDescription
currency
ISO 4217 Currency Code

The currency used for the account

Required
end_advertiser
The type of this param is undocumented. If you are the owner of this param, please specify a developer-friendly type for it

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

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:
When posting to this edge, an AdAccount will be created.

Parameters

NameDescription
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

Struct {
success: bool,
}
You can make a POST request to adaccounts edge from the following paths:
When posting to this edge, an AdAccount will be created.

Parameters

NameDescription
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

Struct {
access_status: string,
}
You may perform a POST request to the following edges from this node:

Validation Rules

ErrorDescription
100Invalid parameter
274The 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
272This Ads API call requires the user to be admin of the application

Updating

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

Parameters

NameDescription
agency_client_declaration
dictionary

Details of the agency advertising on behalf of this client account

business_info
dictionary

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 lowest denomination of the currency, e.g. cents for USD.

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

Struct {
success: bool,
}

Validation Rules

ErrorDescription
100Invalid parameter
274The 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
272This Ads API call requires the user to be admin of the application

Deleting

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

Parameters

NameDescription
account_id
numeric string

ID of the ad 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

NameDescription
adaccounts
list<numeric string>

Array of ad account IDs to revoke access to the custom audience

Return Type

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

Validation Rules

ErrorDescription
100Invalid parameter