Marketing API Version

Business Asset Management

A business may have access to multiple assets: either the business own them directly, or the business can accesse them as an agency. We have the following APIs to add/remove/query the relationship between a business and its assets.

Ad Account Groups

An ad account group cannot be claimed by a business manager. Users with access to certain ad account groups will still have access to them after those users are added to a business manager.

Ad Accounts

A business manager can claim ad accounts that belong to them. This allows Admin's to easily assign people to the ad accounts they should have access too. This also allows you to assigned Shared Funding Sources to your ad accounts.

Claiming ad accounts

If you previously had ad accounts you were using outside of business manager where you have the "Admin" role, you may claim them into your business. Ad account claiming is a one time procedure. Once claimed ad accounts in business manager must be managed within business manager exclusively.

To claim an ad account for your business you must have the id of the ad account (usually seen in the form of "act_###"). Then you can send a POST request:

curl \
-F "adaccount_id=act_<AD_ACCOUNT_ID>" \
-F "access_type=OWNER" \
-F "access_token=<ACCESS_TOKEN>" \
"https://graph.facebook.com/<API_VERSION>/<BUSINESS_ID>/adaccounts"

The access_type denotes which type of relationship your business manager should have with the ad account and is required. The two options are OWNER and AGENCY . AGENCY should be used when you only need access to another business's ad account, and don't technically "own" it. (This will be discussed further in it's own section)

If the user who made the call is an Admin of the ad account, the claim request is immediately approved. An access_status field will be returned in the response and set to CONFIRMED .

If the user who made the claim call does not have the proper permissions on the ad account, an ownership request will be made to the Admins of the ad account. The response, if the request is sent, will contain the access_status field set to PENDING.

To accept an ownership request, an Admin of the ad account must log in and accept the request in Ads Manager.

Requesting access to ad accounts

Most business managers of markteting companies will not need to claim ad accounts from their clients. Please see the business to business functions section for instructions on requesting access to assets owned by other business managers.

Creating ad accounts

Only admins of the business can create new ad accounts. Shared logins (aka gray users) cannot be admins of the business and therefore cannot make the call to create new ad account.

In order to use this API you must have a valid business and page setup. If you have any adaccounts that are unsettled, or pages unpublished by Facebook, this API will fail.

The fields used to create ad account make this API call are:

NameDescriptionType

name

The name of the ad account

string

timezone_id

ID of the timezone

int

currency

The currency abrevation used to for this ad account

string

partner

This could be FBMP or FBX partner if there is one. Must be a Facebook Page Alias, Facebook Page ID or an Facebook App ID.In absense of one, you can use NONE or UNFOUND

long or string

end_advertiser

The entity the ads will target. Must be a Facebook Page Alias, Facebook Page ID or an Facebook App ID. In absense of one, you can use NONE or UNFOUND

long or string

media_agency

The agency, this could be your own business. Must be a Facebook Page Alias, Facebook Page ID or an Facebook App ID. In absense of one, you can use NONE or UNFOUND

long or string

invoice

If business manager has Business Manager Owned Normal Credit Line on file on the FB CRM, it will attach the ad account to that creadit line.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.If business manager has Business Manager Owned Normal Credit Line on file on the FB CRM, it will attach the ad account to that creadit line.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.If business manager has Business Manager Owned Normal Credit Line on file on the FB CRM, it will attach the ad account to that creadit line.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.If business manager has Business Manager Owned Normal Credit Line on file on the FB CRM, it will attach the ad account to that creadit line.

boolean

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 .

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

Viewing business manager owned ad accounts

To see all the ad accounts your business has access to with a GET call:

curl -G \
-d "access_token=<ACCESS_TOKEN>" \
"https://graph.facebook.com/<API_VERSION>/<BUSINESS_ID>/adaccounts"

This will return a list of Ad Accounts associated with a Business Manager. There are a couple of fields that will be returned from this call that are specific to the Business and Ad Account relationship. Look for the access_status field to see the whether your access is CONFIRMED or PENDING. The permitted_roles field will be an array of the roles you may assign for that particular ad account. The access_type field will tell you if your business is acting as an OWNER or an AGENCY of the ad account. If AGENCY is used, permitted_roles is a required field.

Removing ad accounts from business manager

You may not remove ad accounts from your Business that you are the OWNER of and that are CONFIRMED .

For every other case, (a PENDING access request or an ad account that you have AGENCY access to) you can make this DELETE call:

curl \
-X DELETE \
-F "adaccount_id=act_<AD_ACCOUNT_ID>" \
-F "access_token=<ACCESS_TOKEN>" \
"https://graph.facebook.com/<API_VERSION>/<BUSINESS_ID>/adaccounts"

Viewing ad accounts that a user has access to

To see what ad accounts that user has permission on, make this GET call:

curl -G \
-d "user=<USER_ID>" \
-d "fields=adaccount_permissions" \
-d "access_token=<ACCESS_TOKEN>" \
"https://graph.facebook.com/<API_VERSION>/<BUSINESS_ID>/userpermissions"

To see who has what permissions on an ad account, make this GET call:

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

Adding people to ad accounts

After your business manager has an ad account you can now assign your fellow business users roles on it. The roles are as follows:

NameAPI ConstantDescription

Reports Only

REPORTS_ONLY

Can see ad performance

General User

GENERAL_USER

Can see and edit ads and set up ads using the funding source associated with the ad account, but can't set account level

Admin

ADMIN

Can manage all aspects of campaigns, reporting, billing and account permissions

This call requires:

  • adaccount_id : the ad account id (in "act_123" form)
  • business_id : the business id that you are acting on behalf of
  • user_id : the id of the user to add
  • the role to assign

The POST call to add a new user to the ad account as an Admin would be:

curl \
-F "business=<business_id>" \
-F "user=<USER_ID>" \
-F "role=ADMIN" \
-F "access_token=<ACCESS_TOKEN>" \
"https://graph.facebook.com/<API_VERSION>/act_<AD_ACCOUNT_ID>/userpermissions"

Changing permission on ad accounts

You can use the same POST call to change an existing user's role as you do to add a new user:

curl \
-F "business=<BUSINESS_ID>" \
-F "user=<USER_ID>" \
-F "role=REPORTS_ONLY" \
-F "access_token=<ACCESS_TOKEN>" \
"https://graph.facebook.com/<API_VERSION>/act_<AD_ACCOUNT_ID>/userpermissions"

Removing people from ad accounts

To remove a user from an ad account you own, you need:

  • adaccount_id : the ad account id (in "act_123" form)
  • business_id : the business id that you are acting on behalf of
  • user_id : the id of the user to remove

The DELETE call is:

curl \
-X DELETE \
-F "business=<BUSINESS_ID>" \
-F "user=<USER_ID>" \
-F "access_token=<ACCESS_TOKEN>" \
"https://graph.facebook.com/<API_VERSION>/act_<AD_ACCOUNT_ID>/userpermissions"

Pages

Business Manager can claim pages that belong to them. This allows admins to easily assign people to the pages they should have access too.

Claiming pages

To claim an page for your business manager you must have the id of the page. Then send this POST request:

curl \
-F "page_id=<PAGE_ID>" \
-F "access_type=OWNER" \
-F "access_token=<ACCESS_TOKEN>" \
"https://graph.facebook.com/<API_VERSION>/<BUSINESS_ID>/pages"

The access_type denotes which type of relationship your business manager should have with the Page and is required. The two options are OWNER and AGENCY. AGENCY should be used when you only need access to another business's Page, and don't technically "own" it. (This will be discussed further in it's own section) If AGENCY is used, permitted_roles is a required field.

This API request needs to use the access token of an Admin or system user of your business. If the user who makes the call is a Page Admin (MANAGER) of the page, the business immediately owns the Page. A access_status field will be returned in the response and set to CONFIRMED .

If the user who makes an OWNER claim call does not have the proper permissions on the Page, the call will fail. Unlike claiming an ad account, no request will be sent to the Page admins to be approved.

If the user who makes an AGENCY claim call does not have the proper permissions on the Page, the response will be PENDING. The Admin for that Page may login and grant the access, deny it, or even report the claim as a spam. If a Business Manager has too many Page access requests reported as spams, this Business Manager would be locked.

Viewing business manager owned pages

To see all the pages your business has access to use this GET request:

curl -G \
-d "access_token=<ACCESS_TOKEN>" \
"https://graph.facebook.com/<API_VERSION>/<BUSINESS_ID>/pages"

This will return a list of pages associated with a Business Manager. There are a couple of fields that will be returned from this call that are specific to the Business and Page relationship. The permitted_roles field will be an array of the roles you may assign for that particular ad account. The access_type field will tell you if your business is acting as an OWNER or an AGENCY of the Page.

Removing pages from business manager

You may not remove the primary page from your Business that you are the OWNER of and that are CONFIRMED .

For every other case, (a PENDING access request or an ad account that you have AGENCY access to) you can make this DELETE call:

curl \
-X DELETE \
-F "page_id=<PAGE_ID>" \
-F "access_token=<ACCESS_TOKEN>" \
"https://graph.facebook.com/<API_VERSION>/<BUSINESS_ID>/pages"

Adding people to pages

After your business has a page you can now assign your fellow business users roles on it. The roles are as follows:

API ConstantDescription

MANAGER

Can manage admin roles, send messages and post as the Page, create ads and view insights.

CONTENT_CREATOR

Can edit the Page, send messages and post as the Page, create ads, and view insights.

ADVERTISER

Can create ads for the Page and view insights.

MODERATOR

Can respond to and delete comments on the Page, send messages as the Page, create ads, and view insights.

INSIGHTS_ANALYST

Can view insights.

This call requires:

  • page_id : the id of the page
  • business_id : the business id that you are acting on behalf of
  • user_id : the id of the user to add
  • the role to assign

The POST call to add a new user to a Page as a Manager would be:

curl \
-F "business=<BUSINESS_ID>" \
-F "user=<USER_ID>" \
-F "role=MANAGER" \
-F "access_token=<ACCESS_TOKEN>" \
"https://graph.facebook.com/<API_VERSION>/<PAGE_ID>/userpermissions"

Changing permission on pages

You use the same POST call to change an existing user's role as you do to add a new user:

curl \
-F "business=<business_id>" \
-F "user=<USER_ID>" \
-F "role=ADVERTISER" \
-F "access_token=<ACCESS_TOKEN>" \
"https://graph.facebook.com/<API_VERSION>/<PAGE_ID>/userpermissions"

Viewing page permission that a user have

To see what pages that a user has permissions to, make this GET call:

curl -G \
-d "user=<USER_ID>" \
-d "fields=page_permissions" \
-d "access_token=<ACCESS_TOKEN>" \
"https://graph.facebook.com/<API_VERSION>/<BUSINESS_ID>/userpermissions"

To see who has what permission on a Page, make this GET call:

curl -G \
-d "access_token=<ACCESS_TOKEN>" \
"https://graph.facebook.com/<API_VERSION>/<PAGE_ID>/userpermissions"

Removing people from pages

To remove a user from an Page you own, you need

  • page_id : the id of the Page
  • business_id : the business id that you are acting on behalf of
  • user_id : the id of the user to remove

The DELETE call is:

curl \
-X DELETE \
-F "business=<business_id>" \
-F "user=<USER_ID>" \
-F "access_token=<ACCESS_TOKEN>" \
"https://graph.facebook.com/<API_VERSION>/<PAGE_ID>/userpermissions"

Before removing a page from the business manager, you must also remove the admins of that page from your business.

Apps

A Business Manager can claim apps that belong to the business. This allows Business Manager to easily manage apps and developers of those apps.

The business manager owned apps does not support role management. If you have to change app roles, you should do that from the app developer dashboard.

Viewing business owned apps

To see all the applications your business has access to:

curl -G \
-d "access_token=<ACCESS_TOKEN>" \
"https://graph.facebook.com/<API_VERSION>/<BUSINESS_ID>/apps"

This will return a list of apps associated with a Business Manager. There are a couple of fields that will be returned from this call that are specific to the Business Manager and app relationship. The permitted_roles field will be an array of the roles you may assign for that particular ad account. The access_type field with value OWNER shows that your business is the owner of this app.

Removing apps from business manager

To remove an app from the business, you can make this DELETE call:

curl \
-X DELETE \
-F "page_id=<PAGE_ID>" \
-F "access_token=<ACCESS_TOKEN>" \
"https://graph.facebook.com/<API_VERSION>/<BUSINESS_ID>/apps"

Instagram Accounts

A Business Manager can claim Instagram Accounts that belong to the business. This allows Business Manager to easily manage Instagram accounts and ad accounts used for these Instagram accounts.

The business manager does not support role management to its owned Instagram accounts. Who can run ads for those Instagram accounts is controled by the access to the ad accounts linked to the Instagram accounts.

Claiming Instagram Account

To claim an Instagram account for your business manager is supported by Business Manager UI only. More details can be found at Instagram Ads Setup doc.

Instagram Accounts Management

You can use API to manage relationship between a business and an Instagram account. With the APIs documented with Instagram Ads Setup, you can:

  • Assign a business as an "agency" of an owned Instagram account;
  • Delete an agency business from an Instagram account;
  • See all Instagram accounts accessible by a given business, either owned or as agency;
  • See all agency businesses of a given Instagram account.

There are also APIs to manage the relationship between ad accounts and Instagram accounts, also documented in same document.

Product Catalog

You can manage Product Catalogs with Business Manager. Once a Product Catalog is created within a business, you can set up a Product Feed and Product Set for this catalog.

Learn more in the product catalog reference.

Product Catalog Permissions

In order to update items in a Product Catalog, a user, including a system user or a system admin user, needs permissions. The only possible role is ADMIN for a Product Catalog.

To assign the ADMIN role for a catalog to a user:

curl \
-X POST
-F "user=<user_id>" \
-F "role=ADMIN" \
-F "access_token=<ACCESS_TOKEN>" \
"https://graph.facebook.com/<API_VERSION>/<PRODUCT_CATALOG_ID>/userpermissions"

To remove permissions for a catalog from a user:

curl \
-X DELETE \
-F "user=<user_id>" \
-F "access_token=<ACCESS_TOKEN>" \
"https://graph.facebook.com/<API_VERSION>/<PRODUCT_CATALOG_ID>/userpermissions"

Permitted Roles

When a user is added to a business, one of the following two roles can be assigned.

API ConstantNameDescription

ADMIN

Business Admin

Can manage all aspects of the business settings, including modifying or deleting the account and adding or removing people.

EMPLOYEE

Business Employee

Can see all of the information in the business settings but can't make any changes, except to add Pages or ad accounts which this user is an admin of to the business.

The following roles can be assigned to any user of the business, either Admin or Employee, on ad accounts accessible by this business:

API ConstantNameDescription

ADMIN

Ad Account Admin

Can manage all aspects of campaigns, reporting, billing and account permissions, and can set ad account spending limits. Ad account admins can also associate business payment methods.

GENERAL_USER

Ad Account Advertiser

Can see and edit ads and set up ads using the payment method associated with the ad account.

REPORTS_ONLY

Ad Account Analyst

Can see ad performance.

The following roles can be assigned to any user of the business, either Admin or Employee, on Pages accessible by this business:

API ConstantNameDescription

MANAGER

Page Admin

Can manage Page roles, send messages and post as the Page, create ads, and view insights.

CONTENT_CREATOR

Page Editor

Can edit the Page, send messages and post as the Page, create ads, and view insights.

MODERATOR

Page Moderator

Can respond to and delete comments on the Page, send messages as the Page, create ads, and view insights. Page moderators can't post as the Page.

ADVERTISER

Page Advertiser

Can create ads for the Page and view insights. Page advertisers can't post as the Page.

INSIGHTS_ANALYST

Page Analyst

Can view insights. Page analysts can't post as the Page.

There is no role management API for apps in Business Manager.

ADMIN is the only role can be assigned to any user of the business, either Admin or Employee, on Product Catalogs accessible by this business.

There is no role management for Instagram accounts in Business Manager. Users with access to ad accounts which are linked to Instagram accounts can run ads for those Instagram accounts.

Business to Business Functions

Requesting access to assets

Business Manager may request access to an ad account or a page owned by another business manager. They must specify the roles that they want need to be able to assign in the request.

The access_type field must be set to AGENCY to request for access instead of ownership, and permitted_roles is a required field.

You may only send request to assets to business manager that you already expect to approve and that they must already know your business.

For example a business mangager that needs access to <adaccount_id> and needs to be able to assign its employees as GENERAL_USER and REPORTS_ONLY would make this POST call:

curl \
-F "adaccount_id=act_<AD_ACCOUNT_ID>" \
-F "access_type=AGENCY" \
-F "permitted_roles=['GENERAL_USER','REPORTS_ONLY']" 
"https://graph.facebook.com/<API_VERSION>/<BUSINESS_ID>/adaccounts?access_token=<ACCESS_TOKEN>"

Similarly for a Page, if a business manager needed the ability to assign the ADVERTISER and INSIGHTS_ANALYST on a Page they don't own:

curl \
-F "page_id=<PAGE_ID>" \
-F "access_type=AGENCY" \
-F "permitted_roles=['ADVERTISER','INSIGHTS_ANALYST']" \
"https://graph.facebook.com/<API_VERSION>/<BUSINESS_ID>/pages?access_token=<ACCESS_TOKEN>" \

These calls send out a notification to the respective admins of the ad account or Page, which asks to accept the access request. The respective admins will see the notification in Ads Manager or Pages Manager. They can also accept the request from the UI. If you want to see the outstanding requests via the api, look for PENDING for access_status field with a GET request.

curl "https://graph.facebook.com/<API_VERSION>/<BUSINESS_ID>/clients?access_token=<ACCESS_TOKEN>"

This is how the response would look like:

 "data": [
    {
      "name": "Random Page", 
      "page_permissions": [
        {
          "id": "1900952844321", 
          "permitted_roles": [
            "ADVERTISER", 
            "CONTENT_CREATOR", 
            "MODERATOR", 
            "MANAGER"
          ], 
          "access_status": "CLIENT_RESPONSE_PENDING", 
          "access_requested_time": "2014-01-07T23:26:09+0000", 
          "access_updated_time": "2014-01-07T23:26:09+0000"
        }
      ], 
      "id": "190137931178903"
    }, 

Granting access to assets for another business manager

This is also known as adding an Agency to you object.

To accept an access request of an object you own from another business manager, or to give access of one of the objects you own to another business manger, you must specify the business and the list of roles they should have access to.

If the access token used to make the API call belongs to a user or system user who has access to the requested asset via a business, the access to the asset can only be granted if this business is the OWNER of the asset. You cannot grant access to assets of which you are just an AGENCY.

For example to give a Business access to an Ad Account with access to the GENERAL_USER and REPORTS_ONLY roles, use this POST request:

curl \
-F "business=<BUSINESS_ID>" \
-F "permitted_roles=['GENERAL_USER','REPORTS_ONLY']" \
"https://graph.facebook.com/<API_VERSION>/act_<AD_ACCOUNT_ID>/agencies?access_token=<ACCESS_TOKEN>"

Similarly, to give a Business access to your Page with the ADVERTISER and MODERATOR roles:

curl \
-F "business=<BUSINESS_ID>" \
-F "permitted_roles=['ADVERTISER','MODERATOR']" \
"https://graph.facebook.com/<API_VERSION>/<PAGE_ID>/agencies?access_token=<ACCESS_TOKEN>"

A Page admin can also accept an agency access request from the Manage Admin Roles tabs in a Page's settings on facebook.com

Removing access to assets on another business manager

This is also known as removing an Agency from your object.

To remove a business managers's access from your ad account:

curl \
-X DELETE \
-F "business=<BUSINESS_ID>" \
"https://graph.facebook.com/<API_VERSION>/act_<AD_ACCOUNT_ID>/agencies?access_token=<ACCESS_TOKEN>"

Similarly, to remove a Business's access from your Page:

curl \
-X DELETE \
-F "business=<BUSINESS_ID>"
"https://graph.facebook.com/<API_VERSION>/<PAGE_ID>/agencies?access_token=<ACCESS_TOKEN>"

Viewing the agency business manager access

To see all the businesses that have access to your adaccount with a GET:

curl "https://graph.facebook.com/<API_VERSION>/act_<AD_ACCOUNT_ID>/agencies?access_token=<ACCESS_TOKEN>"

To see all the businesses that have access to your page:

curl "https://graph.facebook.com/<API_VERSION>/<PAGE_ID>/agencies?access_token=<ACCESS_TOKEN>"

To see all the businesses that have access to something your business owns:

curl "https://graph.facebook.com/<API_VERSION>/<BUSINESS_ID>/agencies?access_token=<ACCESS_TOKEN>"

Viewing client business manager access

To see all the businesses that have given you access to one or more of their Ad Accounts or Pages, use this GET:

curl "https://graph.facebook.com/<API_VERSION>/<BUSINESS_ID>/clients?access_token=<ACCESS_TOKEN>"