Marketing API Version

Business Manager

Overview

Business Manager helps businesses and agencies manage their Facebook Pages, ad accounts and apps in one place. In Business Manager you can establish connections amongst your assets and other business assets for:

  • Project and permission management
  • Allowing agencies to run campaigns for another company's Page.

You can also create ad accounts and assign credit with a single click.

Prerequisites

Business requires at least one page, an admin, and a business name. You also need a valid email address.

The name is not external and used only for the business and any of other businesses they choose to share objects with. Once this business unit is established, more pages, ad-accounts, apps, offsite conversion tracking objects, basically anything that is owned by a business, can be added as an asset of that business.

Business Manager API's can automate the tasks of managing ad account assets and permissions. It can also automate the creation of ad accounts when needed by the business.

To use the Business Manager API, please ensure your app has the appropriate Marketing API Access Level. Your app also needs business_management extended permission, available as of 2.7. You cannot use ads_management or manage_pages to call Business Management API 2.7. If you have an existing app on 2.6 or earlier, with approval to use ads_management or manage_pages permissions, Facebook will migrate your app to this new permission and you do not need to redo permissions review. If you move your app to 2.7 your app should ask for the additional permission ‘business_management’ any time your app generates a new access token for new or old users. Apps using this permission for the first time need to go through review, see Permissions.

View this help site for more information.

Create a business manager

The API below will allow you to create a new business manager for your business. Typically this is not necessary; once you have a business manager created you can easily add more people, pages, ad accounts within that business manger. Only create a new business manager if you are setting up a new business manager for your clients. If you simply need another ad account or to get access to another page, you should use your existing manager and take advantage of asset permissions.

To create a Business you need the following things:

  • an access token
  • a Page ID
  • a vertical
  • an app scoped user ID

The Page ID given will be the Primary Page of your Business. The Primary Page of your business is the public representation of your business on Facebook. Whomever who creates the Business will need to be a Manager of this page. If you don't have a Page to represent your business on Facebook please create one.

To create a new business manager make a POST request as shown the in the below example:

curl \
-F "name=Pomni Media" \
-F "vertical=ADVERTISING" \
-F "primary_page=<PAGE_ID>" \
-F "timezone_id=1" \
-F "access_token=<ACCESS_TOKEN>" \
"https://graph.facebook.com/<API_VERSION>/<USER_ID>/businesses"

The vertical is a constant string of one of the following types: ADVERTISING , AUTOMOTIVE , CONSUMER_PACKAGED_GOODS , ECOMMERCE , EDUCATION , ENERGY_AND_UTILITIES , ENTERTAINMENT_AND_MEDIA , FINANCIAL_SERVICES , GAMING , GOVERNMENT_AND_POLITICS ,MARKETING , ORGANIZATIONS_AND_ASSOCIATIONS , PROFESSIONAL_SERVICES , RETAIL , TECHNOLOGY , TELECOM , TRAVEL , OTHER

Read a business manager

To view the properties of a single business, you just need its ID:

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

You can also see a list of the business managers that you are on:

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

Response fields

NameDescriptionType

name

The Name of the Business

string

timezone_id

ID for the timezone

int

primary_page

The object of the primary page associated with this business manager.

{
  "category": "App page", 
  "name": "Sample Primary Page", 
  "id": "123456789"
}

JSON object

id

The ID of the business manager

long

update_time

The last time this business manager was updated

string

updated_by

The last user (name and id) who have updated this business manager

JSON object

creation_time

The time this brand was created

string

created_by

The user (name and id) who has created this business manager

JSON object

Update a business manager

You can update any of the below fields of the business manager using the following endpoint:

https://graph.facebook.com/<API_VERSION>/<BUSINESS_ID>
NameDescription

name

Required; The Name of the Business

primary_page

The ID of the primary page associated with this business manager

Examples

You can update the business name by making the following POST request:

curl \
-F "name=My Actual Business Name" \
-F "access_token=<ACCESS_TOKEN>" \
"https://graph.facebook.com/<API_VERSION>/<BUSINESS_ID>/"

You can update the business vertical by making the following POST request:

curl \
-F "vertical=RETAIL" \
-F "access_token=<ACCESS_TOKEN>" \
"https://graph.facebook.com/<API_VERSION>/<BUSINESS_ID>/"

You can update the primary page by making the following POST request. The primary page has to be owned by business manager.

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

You can also update all of the above in one POST request:

curl \
-F "name=My Actual Business Name" \
-F "vertical=RETAIL" \
-F "primary_page=<PAGE_ID>" \
-F "access_token=<ACCESS_TOKEN>" \
"https://graph.facebook.com/<API_VERSION>/<BUSINESS_ID>/"

Delete a business manager

Deleting a business manager is not allowed.

People on business manager

There are two types of roles a person may have on a business manager:

NameAPI ConstantDescription

Admin

ADMIN

  • Can control all aspects of the business including modifying or deleting the account and adding or removing people from the employee list.
  • Has READ and WRITE access to all assets that the Buisness Manager is connected with.

Employee

EMPLOYEE

  • Can see all of the information in the business settings and be assigned roles by business admins, but can't make any changes, except to add Pages or ad accounts which this user is an admin of to the business.
  • Has READ access to all assets that the Buisness Manager is connected with.

Initially the creator of the Business is the only user on the Business and is an Admin.

Inviting people to business manager

To add your coworkers to your business you must invite them. To invite someone all you need is a valid email address that they have access to.

To invite someone as an Admin, send a POST request:

curl \
-F "email=some@email.com" \
-F "role=ADMIN" \
-F "access_token=<ACCESS_TOKEN>" \
"https://graph.facebook.com/<API_VERSION>/<BUSINESS_ID>/userpermissions"

To invite someone as an Employee, send a POST request:

curl \
-F "email=some@email.com" \
-F "role=EMPLOYEE" \
-F "access_token=<ACCESS_TOKEN>" \
"https://graph.facebook.com/<API_VERSION>/<BUSINESS_ID>/userpermissions"

After making this call an email invitation will be sent to the work email address you've specified. The invitee must have to check the email and go through the flow to on the business manager. Once accepted, you'll be able to see them in your list of Users.

Sending requests to add employees to a business manager is limited. When you hit this limit you will get error code 17, you should resume 24 hours later.

Getting list of people on business manager

To get the list of all people within the business manager, make the following GET request:

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

This will include INVITED and ACTIVE users on your Business. ACTIVE users will have both a user field and a business_persona field. Here is the example of a response.

{
  "data": [
    {
      "business_persona": {
        "name": "Jason White", 
        "id": "12345678"
      }, 
      "role": "ADMIN", 
      "status": "ACTIVE", 
      "email": "jw@email.com", 
      "user": {
        "name": "Jason White", 
        "id": "10015004084976543"
      }
    }, 
    {
      "role": "EMPLOYEE", 
      "status": "INVITED", 
      "email": "jesscias3@fb.com", 
    }, 
  ]
}
NameDescriptionType

user

The Facebook user information, including id and name. This field is null for non-ACTIVE people. Do not use the name in this field for your UI. Use that in business_persona instead.

JSON object

business_persona

The persona of this user with this business. If you ever wish to display the name of your users in any UI, you must use the name from the business_persona when available and not the name from the user. This helps communicate the separation of business contexts from personal contexts. Customers may use a different name in their business context.

JSON object

role

The role this person has with this business. Could be EMPLOYEE or ADMIN.

string

status

Whether this user has accepted the invitation to be a people of this business. Could be INVITED, ACTIVE, or SUSPENDED.

string

email

The email address used to invite people for this business.

string

created_by

The ADMIN user who created this user.

string

updated_by

The ADMIN user who last updated this user.

string

created_time

When this user was created.

DateTime string

updated_time

When this user was updated

DateTime string

page_permissions

An array of Page permissions, one element for each Page this user has access or is invited to have access. In each element, there is an id for Page, a role for the Page, and a STATUS which can be ACTIVE or INVITED.

JSON object

adaccount_permissions

An array of ad account permissions, one element for each ad account this user has access or is invited to have access. In each element, there is an id for ad account, a role for the ad account, and a STATUS which can be ACTIVE or INVITED.

JSON object

Changing the role on people

To change a user's role on your Business you simply need the User ID of the user whose role you are trying to change.

For example you can upgrade an Employee to the Admin role, make the following POST request:

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

or downgrade an Admin to the Employee role using this POST request:

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

You can even change the role assigned to an invited email address with this POST request:

curl \
-F "email=some@email.com" \
-F "role=EMPLOYEE" \
-F "access_token=<ACCESS_TOKEN>" \
"https://graph.facebook.com/<API_VERSION>/<BUSINESS_ID>/userpermissions"

Removing people from your business

Removing a user from your business is convenient if that person should no longer have access to any of your business manager assets. Removing will cause them to lose any permissions granted because of membership in your business managers. They'll lose access to ad accounts, pages as well. If the user has access to ad accounts or pages outside of your business manager (they have added directly or they have access through another business manager) those permissions are not affected.

To remove a user from your business make a DELETE call like this:

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

Or if you want to cancel an email invitation with a DELETE request:

curl \
-X DELETE \
-F "email=some@email.com" \
-F "access_token=<ACCESS_TOKEN>" \
"https://graph.facebook.com/<API_VERSION>/<BUSINESS_ID>/userpermissions"

These calls will remove the user from your Business as well as remove them from all your Business's assets.

Getting Connection Objects

You can retrieve all Facebook objects (e.g. pages, apps, etc) where an Ad User is an administrator (or developer/advertiser) for a specific business:

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

See sample response and read more about connection objects here.

Persona

Business manager is all about creating a place for business interactions. Each business manager creates a separate working context separate from their personal identities, and from their other business manager contexts. Each person has name, email and title specific to that particular business manager. Although access to BM is authenticated using personal facebook identity within each business context, FB usernames, friend lists, etc are not used or shown.

Fields

NameDescriptionType

id

Business persona ID, default field

long

name

Business persona pame, default field

string

business

Business manager id

long

first_name

Business first Name

string

last_name

Business last Name

string

title

Business title

string

email

Business email

string

update_time

The last time this persona was updated

string

updated_by

The last user (name and id) who have updated this persona

JSON object

created_time

The time this persona was created

string

created_by

The user (name and id) who has created this persona

JSON object

When accepting an invitation to your business manager a user is prompted to create a persona. This is how the user wishes to be displayed with in a particular business manager. The persona consists of a name , first_name , last_name , email and an id.

To get all the personas associated with a specific business manager, make this GET call:

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

To get the persona associated with your user account, as specified by the access token, on a specific business manager, make this GET call:

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

You may modify the first_name , last_name , email of a persona with this POST request:

curl \
-F "first_name=Teddy" \
-F "last_name=Bear" \
-F "email=user@email.com" \
-F "access_token=<ACCESS_TOKEN>" \
"https://graph.facebook.com/<API_VERSION>/<BUSINESS_PERSONA_ID>"

If you update email you will not see this property immediately updated for the persona even if the response for the API call is "success". Facebook first sends an email with a verification link to the new email address. After the owner of this email account verifies the new email, Facebook updates the email address of the persona.

Projects

Fields

NameDescriptionType

id

Business Project ID, default field

long

name

Business project Name, default field

string

business

Business id

long

update_time

The last time this Business project was updated

string

updated_by

The last user (name and id) who have updated this Business project

JSON object

created_time

The time this Business Label was created

string

created_by

The user (name and id) who has created this Business project

JSON object

adaccounts

The adaccounts under this project for this given business

JSON object

pages

The Pages under this project for this given business

JSON object

apps

The apps under this project for this given business

JSON object

Business project is an effective way to organize your business assets (ad accounts, Pages, apps) into logical groups. They help you navigate your business hierarchy more easily. Projects can be used across agency and client owned assets. You can only have one label per asset.

Creating a project

To create a business project you must specify the name in a POST request.

curl \
-F "name=Test label" \
-F "access_token=<ACCESS_TOKEN>" \
"https://graph.facebook.com/<API_VERSION>/<BUSINESS_ID>/businessprojects"

Viewing your projects

You can view all the labels under the business account with a GET request:

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

Viewing a projects on the business

You can view the details of a project by making this GET call:

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

Removing a project on the business

You can delete a project by making this DELETE call:

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

Page for Project

You can add a Page to a project by making following POST call:

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

You can view all the Pages under a project by making following GET call:

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

You can remove a Page from a project by making following DELETE call:

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

Ad Account for Project

You can add an ad account to a project by making following POST call:

curl \
-F "adaccount_id=act_<ADACCOUNT_ID>" \
-F "access_token=<ACCESS_TOKEN>" \
"https://graph.facebook.com/<API_VERSION>/<PROJECT_ID>/adaccounts"

You can view all the ad accounts under a project by making following GET call:

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

You can remove an ad account from a project by making following DELETE call:

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

App for Project

You can add an app to a project by making following POST call:

curl \
-F "app_id=<PAGE_ID>" \
-F "access_token=<ACCESS_TOKEN>" \
"https://graph.facebook.com/<API_VERSION>/<PROJECT_ID>/apps"

You can view all the apps under a project by making following GET call:

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

You can remove an app from a project by making following DELETE call:

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

Business Assets

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 Business Asset Management APIs to add/remove/query the relationship between a business and its assets.

Invoicing

Business Manager Owned Normal Credit Line

For the Marketing API partners who have invoicing enabled, you can take advantage of Business Manager Owned Normal Credit Line.

Facebook Marketing Partners (FBMP) need to contact their sales rep to get your business manager setup for credit. Please make sure ask for Business Manager Owned Normal Credit Line. Once this is setup, you can start using the ad account creation API to start creating ad accounts. Charges will be against your business manager credit line.

For the ad accounts created via the below api, we will dynamically distribute credit across accounts and update credit limits and spend to avoid hitting the credit limits. You will also be able to see summarized credit available and the amount of credit on each ad account.

Today, we only support normal liability, sequential liability is not supported. The process for setting this up will remain unchanged.

Funding Source API

To retrieve the credit card associated with a business manager, send this GET request.

https://graph.facebook.com/business_id/creditcards

To retrieve the extended credit funding source associated with a business manager, send this GET request.

https://graph.facebook.com/business_id/extendedcredits

To setup a funding source for a business, go to settings section of your business on Business Manager.

Dynamic Credit Allocation

Dynamic Credit Allocation (also known as DCAF) is our credit allocation system for periodically adjusting available credit on per ad account basis. Our automated script runs approximately every 30 minutes and takes your available credit (total approved credit minus total outstanding balance) and evenly distributes it across all your active accounts enabled for DCAF. This method allows us to manage spend at your ad account level and allocate funding for each ad account.

One other update is in business manager, businesses will have the ability to “inactivate” an invoiced ad account (removing the ad account from the list that needs credit assigned). Businesses no longer need to have Facebook manage this status.