Graph API Version

Business

Reading

Represents a business on Facebook. Includes any specified properties and assets belonging to the business.

Example

Graph API Explorer
GET /v7.0/{business-id} HTTP/1.1
Host: graph.facebook.com
/* PHP SDK v5.0.0 */
/* make the API call */
try {
  // Returns a `Facebook\FacebookResponse` object
  $response = $fb->get(
    '/{business-id}',
    '{access-token}'
  );
} catch(Facebook\Exceptions\FacebookResponseException $e) {
  echo 'Graph returned an error: ' . $e->getMessage();
  exit;
} catch(Facebook\Exceptions\FacebookSDKException $e) {
  echo 'Facebook SDK returned an error: ' . $e->getMessage();
  exit;
}
$graphNode = $response->getGraphNode();
/* handle the result */
/* make the API call */
FB.api(
    "/{business-id}",
    function (response) {
      if (response && !response.error) {
        /* handle the result */
      }
    }
);
/* make the API call */
new GraphRequest(
    AccessToken.getCurrentAccessToken(),
    "/{business-id}",
    null,
    HttpMethod.GET,
    new GraphRequest.Callback() {
        public void onCompleted(GraphResponse response) {
            /* handle the result */
        }
    }
).executeAsync();
// For more complex open graph stories, use `FBSDKShareAPI`
// with `FBSDKShareOpenGraphContent`
/* make the API call */
FBSDKGraphRequest *request = [[FBSDKGraphRequest alloc]
                               initWithGraphPath:@"/{business-id}"
                                      parameters:params
                                      HTTPMethod:@"GET"];
[request startWithCompletionHandler:^(FBSDKGraphRequestConnection *connection,
                                      id result,
                                      NSError *error) {
    // Handle the result
}];
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
numeric string

The business ID.

block_offline_analytics
bool

Specifies whether offline analytics for business is blocked.

created_by
BusinessUser|SystemUser

Creator of this business.

created_time
datetime

Creation time of this business.

extended_updated_time
datetime

Extended credits update time.

is_hidden
bool

Whether the business is hidden.

is_instagram_enabled_in_fb_analytics
bool

Whether Instagram is enabled as event source in Facebook Analytics.

link
string

URI for business profile page.

name
string

The business's name.

payment_account_id
numeric string

ID for the payment account for this business.

primary_page

The primary Facebook Page for this business.

profile_picture_uri
string

The profile picture URI of the business.

timezone_id
unsigned int32

This business's timezone.

two_factor_type
enum

Two factor type authentication used for this business

updated_by
BusinessUser|SystemUser

Last time this business was updated.

updated_time
datetime

Last time this business was updated.

verification_status
enum

Verification status for this business.

vertical
string

This business belongs to this vertical industry.

vertical_id
unsigned int32

ID for vertical industry.

Edges

EdgeDescription

The studies this business has access to, such as any advertising lift studies or split testing studies.

Audience Network query for this publisher entity.

Obtain the results of an asynchronous Audience Network query for this publisher entity.

The business has access to these pixels.

Agencies associated with this business.

Placements used by this Audience Network business.

This is the object to represent business creative folder sharing agreements that have this business as receiving business.

Business asset groups owned by this business. The business can grant permissions to assets in this group.

This business has access to these business units.

Business users associated with this business. Includes employees and admins at the business.

This business has access to these client ad accounts.

This business has access to these client apps.

This business has access to these client pages.

This business has access to these client pixels.

This business has access to these client product catalogs.

Clients of this business.

Commerce Merchant Settings belonging to this business.

creative_asset_tags

The business owns these event source groups. Includes various signals sources such as pixels.

The audience sharing requests initiated by this business.

initiated_sharing_agreements

This business has access to these Instagram accounts.

The measurement reports that the business owns.

The business has access to these offline conversion datasets.

This business owns these ad accounts.

This business owns these apps.

This business aggregates and manages these client businesses.

This business owns these Instagram accounts.

This business owns these pages.

This business owns these pixels.

This business owns these product catalogs.

This business requested access to these client ad accounts and is pending approval.

This business requested access to these client apps and is pending approval.

This business requested access to these client pages and is pending approval.

This business requested ownership of these ad accounts and is pending approval.

This business requested ownership of these pages and is pending approval.

Admin for this business invited this user to the business. Pending user approval.

The audience sharing requests received by this business.

received_sharing_agreements

Reseller verification requests for a China reseller business.

The business's system users.

Validation Rules

ErrorDescription
200Permissions error
100Invalid parameter
278Reading advertisements requires an access token with the extended permission ads_read
80004There have been too many calls to this ad-account. Wait a bit and try again. For more info, please refer to https://developers.facebook.com/docs/graph-api/overview/rate-limiting.
294Managing advertisements requires an access token with the extended permission for ads_management

Creating

To create other Business Managers, your business needs to obtain BUSINESS_MANAGEMENT during the app review process. If your app is in development mode, you can surpass this requirement, but to create only two child businesses.

You can make a POST request to businesses edge from the following paths:
When posting to this edge, a Business will be created.

Parameters

ParameterDescription
email
string

The business email of the business admin

name
string

Username

Required
primary_page
page ID

Primary Page ID

sales_rep_email
string

Sales Rep email address

survey_business_type
enum {AGENCY, ADVERTISER, APP_DEVELOPER, PUBLISHER}

Business Type

survey_num_assets
int64

Number of Assets in the business

survey_num_people
int64

Number of People that will work on the business

timezone_id
int64

Timezone ID

vertical
enum {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, NON_PROFIT, RESTAURANT, HEALTH, LUXURY, OTHER}

Vertical ID

Required

Return Type

This endpoint supports read-after-write and will read the node represented by id in the return type.
Struct {
id: numeric string,
}

Validation Rules

ErrorDescription
100Invalid parameter
3947You are trying to create a Business Manager with the same name as one you are already a part of. Please pick a different name.
3992Your payment account is disabled.
42000This Page can't be added because it's already linked to an Instagram business profile. To add this Page to Business Manager, go to Instagram and convert to a personal account or change the Page linked to your business profile.
3974The name you chose for this Business Manager is not valid. Try a different name.
3913It doesn't look like you have permission to create a new Business Manager.
3929It looks like you're trying to create a new Business Manager using shared login details (a gray account). To confirm your identity, you need to log in with the username and password you use for your personal Facebook account. Nothing from your personal account will be shared with the Business Manager.
3918The Facebook Page you've tried to add is already owned by another Business Manager. You can still request access to this Page, but your request will need to be approved by the Business Manager that owns it.
3973The name you chose for this Business Manager is not valid. Please choose another.
368The action attempted has been deemed abusive or is otherwise disallowed
You can make a POST request to agencies edge from the following paths:
When posting to this edge, a Business will be created.

Parameters

ParameterDescription
business
numeric string or integer

SELF_EXPLANATORY

Required
other_relationship
string

SELF_EXPLANATORY

permitted_roles
list<enum {ADMIN, UPLOADER, ADVERTISER}>

Permitted roles the agency can assign to users

relationship_type
array<enum {AD_MANAGER, AUDIENCE_MANAGER, AGENCY, AGGREGATOR, OTHER}>

Relationship type for sharing

Return Type

This endpoint supports read-after-write and will read the node to which you POSTed.
Struct {
success: bool,
share_status: enum,
}

Validation Rules

ErrorDescription
100Invalid parameter
You can make a POST request to owned_businesses edge from the following paths:
When posting to this edge, a Business will be created.

Parameters

ParameterDescription
name
string

name

Required
page_permitted_tasks
array<enum {MANAGE, CREATE_CONTENT, MODERATE, ADVERTISE, ANALYZE, MODERATE_COMMUNITY, MANAGE_JOBS, PAGES_MESSAGING, PAGES_MESSAGING_SUBSCRIPTIONS, READ_PAGE_MAILBOXES, VIEW_MONETIZATION_INSIGHTS, MANAGE_LEADS, PROFILE_PLUS_MANAGE, PROFILE_PLUS_CREATE_CONTENT, PROFILE_PLUS_ADVERTISE, PROFILE_PLUS_ANALYZE, PROFILE_PLUS_MESSAGING, PROFILE_PLUS_MODERATE, CASHIER_ROLE}>

page_permitted_tasks

sales_rep_email
string

sales_rep_email

shared_page_id
page ID

shared_page_id

survey_business_type
enum {AGENCY, ADVERTISER, APP_DEVELOPER, PUBLISHER}

survey_business_type

survey_num_assets
int64

survey_num_assets

survey_num_people
int64

survey_num_people

timezone_id
int64

timezone_id

vertical
enum {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, NON_PROFIT, RESTAURANT, HEALTH, LUXURY, OTHER}

vertical

Required

Return Type

This endpoint supports read-after-write and will read the node represented by id in the return type.
Struct {
id: numeric string,
}

Validation Rules

ErrorDescription
3913It doesn't look like you have permission to create a new Business Manager.
200Permissions error
3947You are trying to create a Business Manager with the same name as one you are already a part of. Please pick a different name.
3974The name you chose for this Business Manager is not valid. Try a different name.
100Invalid parameter
3929It looks like you're trying to create a new Business Manager using shared login details (a gray account). To confirm your identity, you need to log in with the username and password you use for your personal Facebook account. Nothing from your personal account will be shared with the Business Manager.
You can make a POST request to china_business_onboarding_attributions edge from the following paths:
When posting to this edge, a Business will be created.

Parameters

This endpoint doesn't have any parameters.

Return Type

Struct {
id: numeric string,
link_with_id: string,
}

Validation Rules

ErrorDescription
200Permissions error
You can make a POST request to business_units edge from the following paths:
When posting to this edge, a Business will be created.

Parameters

ParameterDescription
business_units
list<JSON or object-like arrays>

Create this array of the business units. For example [{name:"business_unit"}].

name
string

Required
is_enabled_for_measurement
boolean

Return Type

This endpoint supports read-after-write and will read the node represented by id in the return type.
Struct {
id: numeric string,
}

Validation Rules

ErrorDescription
200Permissions error
You can make a POST request to business_users edge from the following paths:
When posting to this edge, a Business will be created.

Parameters

ParameterDescription
email
string

Email of user to be added to this business.

Required
role
enum {FINANCE_EDITOR, FINANCE_ANALYST, ADS_RIGHTS_REVIEWER, ADMIN, EMPLOYEE, DEVELOPER, PARTNER_CENTER_ADMIN, PARTNER_CENTER_ANALYST, PARTNER_CENTER_OPERATIONS, PARTNER_CENTER_MARKETING, PARTNER_CENTER_EDUCATION}

Role of user to add to this business.

Return Type

This endpoint supports read-after-write and will read the node represented by id in the return type.
Struct {
id: numeric string,
}

Validation Rules

ErrorDescription
100Invalid parameter
3992Your payment account is disabled.
190Invalid OAuth 2.0 Access Token
200Permissions error
You can make a POST request to access_token edge from the following paths:
When posting to this edge, a Business will be created.

Parameters

ParameterDescription
app_id
app ID

app_id

Required
scope
List<Permission>

scope

Required
system_user_name
string

system_user_name

Return Type

This endpoint supports read-after-write and will read the node to which you POSTed.
Struct {
access_token: string,
}

Validation Rules

ErrorDescription
3972System users can not have duplicate names. Use another name.
3960Error creating the token, make sure that system user has tos-ed the app.
3962Provided permission is not valid. Check you spelling and syntax.
100Invalid parameter
200Permissions error

Updating

You can update a Business by making a POST request to /{business_id}.

Parameters

ParameterDescription
name
string

Business's name

primary_page
numeric string or integer

Primary page of this business

timezone_id
int64

Timezone id of this business

two_factor_type
enum{none, admin_required, all_required}

Two-factor type of the business

vertical
enum {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, NON_PROFIT, RESTAURANT, HEALTH, LUXURY, OTHER}

Vertical type of the business

Return Type

This endpoint supports read-after-write and will read the node represented by id in the return type.
Struct {
id: numeric string,
}

Validation Rules

ErrorDescription
3974The name you chose for this Business Manager is not valid. Try a different name.
3918The Facebook Page you've tried to add is already owned by another Business Manager. You can still request access to this Page, but your request will need to be approved by the Business Manager that owns it.
3947You are trying to create a Business Manager with the same name as one you are already a part of. Please pick a different name.
3973The name you chose for this Business Manager is not valid. Please choose another.
3912There was a technical issue and the changes you made to your Business Manager weren't saved. Please try again.
3910You need permission to edit the details of your Business Manager. Please talk to one of your Business Manager admins about changing your role or editing the Business Manager details.
3911You need permission to set up a new Business Manager.
100Invalid parameter
200Permissions error
You can update a Business by making a POST request to /{business_id}/managed_businesses.

Parameters

ParameterDescription
existing_client_business_id
business ID

Existing client business id provided by the client

name
string

Client business name that's managed by the aggregator business

sales_rep_email
string

Email of sales representative of the business that's managed by the aggregator business

survey_business_type
enum {AGENCY, ADVERTISER, APP_DEVELOPER, PUBLISHER}

Business type of surveyed business that's managed by the aggregator business

survey_num_assets
int64

Number of assets surveyed of business that's managed by the aggregator business

survey_num_people
int64

Number of people surveyed of business that's managed by the aggregator business

timezone_id
int64

Timezone id of business that's managed by the aggregator business

vertical
enum {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, NON_PROFIT, RESTAURANT, HEALTH, LUXURY, OTHER}

Business vertical of business that's managed by the aggregator business

Return Type

This endpoint supports read-after-write and will read the node represented by id in the return type.
Struct {
id: numeric string,
}

Validation Rules

ErrorDescription
42004You couldn't create the client business on behalf your client successfully
100Invalid parameter
200Permissions error

Deleting

You can dissociate a Business from a Business by making a DELETE request to /{business_id}/agencies.

Parameters

ParameterDescription
business
numeric string or integer

The agency's business.

Required

Return Type

Struct {
success: bool,
}

Validation Rules

ErrorDescription
275Cannot determine the target object for this request. Currently supported objects include ad account, business account and associated objects.
100Invalid parameter
You can dissociate a Business from a Business by making a DELETE request to /{business_id}/clients.

Parameters

ParameterDescription
business
numeric string or integer

The client's business.

Required

Return Type

Struct {
success: bool,
}

Validation Rules

ErrorDescription
294Managing advertisements requires an access token with the extended permission for ads_management
You can dissociate a Business from a Business by making a DELETE request to /{business_id}/pages.

Parameters

ParameterDescription
page_id
Page ID

Page ID.

Required

Return Type

Struct {
success: bool,
}

Validation Rules

ErrorDescription
42001This Page can't be removed because it's already linked to an Instagram business profile. To remove this Page from Business Manager, go to Instagram and convert to a personal account or change the Page linked to your business profile.
3996The page does not belong to this Business Manager.
3948Please assign someone as a manager to this Page before removing it from your Business Manager.
200Permissions error
100Invalid parameter
You can dissociate a Business from a Business by making a DELETE request to /{business_id}/instagram_accounts.

Parameters

ParameterDescription
instagram_account
numeric string or integer

Instagram account ID.

Required

Return Type

Struct {
success: bool,
}

Validation Rules

ErrorDescription
100Invalid parameter
You can dissociate a Business from a Business by making a DELETE request to /{business_id}/owned_businesses.

Parameters

ParameterDescription
client_id
business ID

client_id

Required

Return Type

Struct {
success: bool,
}

Validation Rules

ErrorDescription
100Invalid parameter
200Permissions error
3912There was a technical issue and the changes you made to your Business Manager weren't saved. Please try again.
You can dissociate a Business from an AdAccount by making a DELETE request to /act_{ad_account_id}/agencies.

Parameters

ParameterDescription
business
business ID

SELF_EXPLANATORY

Required

Return Type

Struct {
success: bool,
}

Validation Rules

ErrorDescription
100Invalid parameter