Graph API Version

Business

Represent a specific business on Facebook. Make the API call to the business ID.

To find the ID of a business, go to Business Manager > Business Settings > Business Info. There, you will see information about the business, including the ID.

Reading

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

Starting September 14, 2021, the following fields will throw an error for version 12.0+ calls made by apps that lack the endpoint's required permissions. This change will apply to all versions on December 13, 2021.

  • collaborative_ads_managed_partner_business_info

Example

Graph API Explorer
GET /v12.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();
/* 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.

collaborative_ads_managed_partner_business_info
ManagedPartnerBusiness

collaborative_ads_managed_partner_business_info

collaborative_ads_managed_partner_eligibility
BusinessManagedPartnerEligibility

collaborative_ads_managed_partner_eligibility

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.

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

Audience Network query for this publisher entity.

Agencies associated with this business.

Placements used by this Audience Network business.

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

The extended credit invoices of this business.

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.

The business has access to these client offsite signal container business objects

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.

WhatsApp business accounts that were shared to this business.

Clients of this business.

All Collaborative Ads. collaboration requests initiated by the business.

Collaborative Ads suggested partners for a business.

Commerce Merchant Settings belonging to this business.

Extended Credit Applications for this business.

Extended credits for this business.

The audience sharing requests initiated by this business.

initiated_sharing_agreements

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.

owned_offsite_signal_container_business_objects

This business owns these pages.

This business owns these pixels.

This business owns these product catalogs.

This business owns these WhatsApp Business Accounts.

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.

This business received sharing requests for these offsite signal container business objects and is pending for 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.

Error Codes

ErrorDescription
200Permissions error
100Invalid parameter
190Invalid OAuth 2.0 Access Token
368The action attempted has been deemed abusive or is otherwise disallowed
294Managing advertisements requires an access token with the extended permission for ads_management
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.
210User not visible

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

Error Codes

ErrorDescription
200Permissions error
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
child_business_external_id
string

child_business_external_id

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

Error Codes

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.
3912There was a technical issue and the changes you made to your Business Manager weren't saved. Please try again.
3913It doesn't look like you have permission to create a new 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.
368The action attempted has been deemed abusive or is otherwise disallowed
3998You must be an admin of the primary Page to create a business using that page.
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, MESSAGING, ADVERTISE, ANALYZE, MODERATE_COMMUNITY, MANAGE_JOBS, PAGES_MESSAGING, PAGES_MESSAGING_SUBSCRIPTIONS, READ_PAGE_MAILBOXES, VIEW_MONETIZATION_INSIGHTS, MANAGE_LEADS, PROFILE_PLUS_FULL_CONTROL, PROFILE_PLUS_MANAGE, PROFILE_PLUS_FACEBOOK_ACCESS, PROFILE_PLUS_CREATE_CONTENT, PROFILE_PLUS_MODERATE, PROFILE_PLUS_MESSAGING, PROFILE_PLUS_ADVERTISE, PROFILE_PLUS_ANALYZE, PROFILE_PLUS_REVENUE, 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,
}

Error Codes

ErrorDescription
3913It doesn't look like you have permission to create a new Business Manager.
100Invalid parameter
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.

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

Error Codes

ErrorDescription
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.
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.
3912There was a technical issue and the changes you made to your Business Manager weren't saved. Please try again.
100Invalid parameter
3973The name you chose for this Business Manager is not valid. Please choose another.
200Permissions error
3911You need permission to set up a new Business Manager.
You can update a Business by making a POST request to /{business_id}/managed_businesses.

Parameters

ParameterDescription
child_business_external_id
string

child_business_external_id

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

Error Codes

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

Error Codes

ErrorDescription
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,
}

Error Codes

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

Error Codes

ErrorDescription
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.
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.
100Invalid parameter
200Permissions error
You can dissociate a Business from a Business by making a DELETE request to /{business_id}/ad_accounts.

Parameters

ParameterDescription
adaccount_id
string

Ad account ID.

Required

Return Type

Struct {
success: bool,
}

Error Codes

ErrorDescription
100Invalid parameter
368The action attempted has been deemed abusive or is otherwise disallowed
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}/owned_businesses.

Parameters

ParameterDescription
client_id
business ID

client_id

Required

Return Type

Struct {
success: bool,
}

Error Codes

ErrorDescription
3912There was a technical issue and the changes you made to your Business Manager weren't saved. Please try again.
100Invalid parameter
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,
}

Error Codes

ErrorDescription
100Invalid parameter