The Facebook Business Extension (FBE) allows your users to easily upload creative assets across the Meta family of apps by connecting with a new or existing Business Manager. Using the Business Manager returned after completing this flow, partners can upload creative assets to Facebook on behalf of their clients:
This document outlines the main prerequisites for the FBE Creative flow along with the steps required to complete the process. Please refer to the Facebook Business Extension guide for specific details on overall integrations.
Example — Onboarding flow from partner surface (Business Login)
Register as a Facebook developer to access our developer tools and create Facebook apps.
If you haven’t yet, create a Meta app.
Your Meta app must be owned by a Business Manager that is a verified business. Learn more about how to verify your business.
Create a test app and use it to perform all new development and testing. Be sure to assign a different Business Manager to your test app.
Private Permissions/Capability:
manage_business_extension
— Access to Facebook Business Extension. Once this capability is issued to your app, you can find the FBE Developer Panel under Products.
Business_creative_asset_management
— Access to creative related asset management apis. After granted with this capability, you can have access to the following permissions:
business_creative_insights
: Access business creative asset insights.
business_creative_management
: Allows your app to create, edit and share new folders and upload assets to these within the context of your own business entity.
business_creative_insights_share
(in development): An optional permission used in the folder sharing flow. If granted by the user, your app will be able to share the creative folder to other businesses and allow them to view creative asset insights.
Generate a partner access token:
Generate an admin system user access token under your business manager by following these instructions.
Ensure that this token has business_creative_insights
, business_creative_management
and business_management
permissions selected in the 'available scopes' step.
This button is used to send an asset to the user’s Facebook Media Library from your app. During this process, your app will need to allow the user to select or create a folder to send the asset to.
We recommend two approaches to doing this:
1. (At minimum) The user only has the option to choose or create a top-level folder. Under the selected business context, query all the top-level folders the user has access to. Ask the user to either choose an existing top-level folder or create a new one. Users can either specify the folder name or use the default folder name <YourBusinessName>_<UserBusinessName>_<UserName>
. Upload assets to the selected or new top-level folder. This approach requires minimal UI work and API details can be found in Step 3 below.
2. (Optional) The user has full folder and subfolder navigation control. Under the selected business context, query all the top-level folders the user has access to and ask the user to either choose an existing top-level folder or create a new one. For a new folder, either ask the user to name the folder or use the default name <YourBusinessName>_<UserBusinessName>_<UserName>
. Under the selected top-level folder, the user has the option to navigate to an existing subfolder, create a new subfolder, or upload assets. With this option, you will need to implement folder navigation in your UI. API integration instructions can be found in Step 3 and Step 4 below.
The specific steps required to implement this flow are as follows:
When the user sends a creative asset to Facebook for the first time, you need to prompt the Facebook Business Extension to ask the user to authenticate and grant your app necessary permissions and access to assets, in the form of access tokens, to access their data on Facebook. See Facebook Business Extension: Get Started to implement Facebook Business Extension into your app. Follow the Business Apps guide to enable your app to surface on Business Apps.
To prompt the Creative flow:
business_creative_management
and business_creative_insights
permissions
business_creative_insights_share
permission
VIEW_INSIGHTS
taskUsing the user access token returned from this prompt, you can make API calls on the user’s behalf.
Field | Description |
---|---|
Type: setup | Required. Seller’s Facebook setup, such as their unique identifier ( |
Type: business_config | Required. Configuration object that the Meta Business Extension uses to configure the Meta Business Extension workflow. See |
Type: boolean | Required. Set this value to |
Use this object to define the settings for the end user's Facebook presence
Field | Description |
---|---|
| Required. |
| Required. |
| Required. |
| Required. |
| Required.
|
| Optional. |
Use this object to configure the business settings for an end user. This includes CTAs, Services card, and more. Each field includes a "type" linked to the respective tables below.
Field | Description |
---|---|
| Required. |
Use this object to configure the businesses name.
Field | Description |
---|---|
| Required. |
After the user finishes the FBE onboarding flow above, you will receive the user’s Business Manager ID and access token either from the FBE Installation API or Webhook notification.
Users can upload assets to the top-level folder or create sub-folders under the top-level folder.
First, check which top-level folders the user has permission to for the CREATE_CONTENT
task, by making a request to the <business_id>/creative_folders
endpoint (under development).
Request
curl -X GET \ -F 'access_token={user-access-token}' \ https://graph.facebook.com/<API_VERSION>/<user_business_id>/creative_folders?filtering=[{field:"permitted_tasks", operator: "EQUAL", value:"create_content"}]
Response
{ "id": "<folder_id>" }
Ask the user to choose an existing top-level folder or create a new top-level folder within the context of the user’s Business Manager. For a new top-level folder, you can either ask the user to name the folder, or use <YourBusinessName>_<UserBusinessName>_<UserName>
by default. If the user shares the folder back to you, it will be visible to both your business and the user’s business in the Facebook asset library.
Note: The user’s business name can be obtained by making a GET
request to the {business-id}
endpoint where {business-id}
is the user’s business ID.
Request
curl -X GET \ -F 'access_token={user-access-token}' \ https://graph.facebook.com/<API_VERSION>/<BUSINESS_ID>
Response
{ "id": {business-id} "name": {user-business-name} }
Request
curl -X POST \ -F "name={folder_name}" -F "description={description}" -F 'access_token={user-access-token}' \ https://graph.facebook.com/<API_VERSION>/<BUSINESS_ID>/creative_folders
Response
{ "id": {top-level-folder-id} }
If you want to support the full folder navigation flow, ask the user to choose an existing subfolder or create a new one under the top-level folder with the following requests:
business_creative_management
permissionRequest
curl -X GET \ -F 'access_token={user-access-token}' \ https://graph.facebook.com/<API_VERSION>/<parent_folder_id>/subfolders?fields=name
Response
{ "data": [ { "name": "<subfolder_name>", "id": "<subfolder_id>" } ] }
business_creative_management
permissionRequest
curl -X POST \ -F "name={folder_name}" -F "description={description}" -F "parent_folder_id={parent-folder-id}" -F 'access_token={user-access-token}' \ https://graph.facebook.com/<API_VERSION>/<BUSINESS_ID>/creative_folders
Response
{ "id": {sub-folder-id} }
The folder and subfolder can be deleted by sending a DELETE
request to the <folder_id>
or <subfolder_id>
endpoint.
Upload user’s creative assets to the subfolder.
business_creative_management
permissionRequest
curl -X POST \ -F 'bytes={image-content-in-bytes-format}' \ -F 'name={image-name}' \ -F 'access_token={user-access-token}' \ -F 'creative_folder_id={subfolder-id}' \ https://graph.facebook.com/{version}/{business-id}/images
Response
{ "images":{ "{image-name}":{ "id":"{business-creative-image-id}", "hash":"{hash}", "url":"{image-url}" } } }
Upload a video in a single request if it is less than a few megabytes, or upload it in chunks (see the next section below). Make your API call for video upload at graph-video.facebook.com
instead of graph.facebook.com
.
Example — Send a POST
to {business-id}/video
and include the name of your video, the source, and the subfolder ID.
Request
curl -X POST \ -F 'name={video-name}' \ -F 'source='@{video-path}'' \ -F 'access_token={user-access-token}' \ -F 'creative_folder_id={subfolder-id}' \ https://graph-video.facebook.com/{version}/{business-id}/videos
Response
{ "success": true, "business_video_id": "<business_video_id>" }
For larger videos, send one start request, one or multiple transfer requests, and one finish request.
To make a start request and create a video upload session, send a POST
request to /{business-id}/videos
, set upload_phase
field to start, and specify file_size
, in bytes
Request
curl -X POST \ -F 'title={video-name}' \ -F 'creative_folder_id={subfolder-id}' \ -F 'access_token={user-access-token}' \ -F 'upload_phase=start' \ -F 'file_size={video_file_size_in_bytes}' \ https://graph-video.facebook.com/<API_VERSION>/<BUSINESS_ID>/videos
Response
{ "upload_session_id": "{session-id}", "video_id": "{video-id}", "start_offset": "0", "end_offset": "52428800" }
To upload [0, 52428800] from your video, slice the file into chunks according to the start and end offsets, then send those chunks with transfer requests. We send you new offsets for each chunk -- use these new offsets to upload each chunk.
Example: Send your first chunk
Request
curl -X POST \ -F 'title={video-name}' \ -F 'access_token={user-access-token}' \ -F 'creative_folder_id={subfolder-id}' \ -F 'upload_phase=transfer' \ -F 'upload_session_id={session-id}' \ -F 'start_offset=0' \ -F 'video_file_chunk=@{binary-chunk-filename}' \ https://graph-video.facebook.com/<API_VERSION>/<BUSINESS_ID>/videos
Response
On success, we respond with the offsets for your next chunk
{ "start_offset": "52428800", //Start byte position of the next file chunk "end_offset": "104857601" //End byte position of the next file chunk }
Cut and upload the second chunk with the range [52428800, 104857601] from your file and send it:
Request
curl -X POST \ -F 'title={video-name}' \ -F 'access_token={user-access-token}' \ -F 'creative_folder_id={subfolder-id}' \ -F 'upload_phase=transfer' \ -F 'start_offset=52428801' \ -F 'upload_session_id={your-upload-sesson-id}' \ -F 'video_file_chunk={binary-chunk-filename}' \ https://graph-video.facebook.com/<API_VERSION>/<BUSINESS_ID>/videos
Response
Send all additional chunks until start_offset
equals end_offset
:
{ "start_offset": "152043520", "end_offset": "152043520" }
The above response means you uploaded the whole file. Now you need to post this video and close the upload session.
Request
curl -X POST \ -F 'title={video-name}' \ -F 'access_token={user-access-token}' \ -F 'creative_folder_id={business-creative-folder-id}' \ -F 'upload_phase=finish' \ -F 'upload_session_id={session-id}' \ https://graph-video.facebook.com/<API_VERSION>/<BUSINESS_ID>/videos
If you get errors during an upload, you can retry uploading that chunk. Typically errors are due to response issues. Retry your upload for the chunk that failed. For more information about errors, see:
Your app should inform the user that the upload has succeeded, and present a deep link to this creative behind a ‘View creative in my Facebook asset library’ call to action. The deep link of the folder or asset is:
https://business.facebook.com/asset_library/business_creatives/?object_id={asset_id or folder id}
(under development)
This link directs the user to the business selection page if the user has multiple Business Managers. To remove business ambiguity, you can provide business context in the url as follows:
https://business.facebook.com/asset_library/business_creatives/?object_id={asset_id or folder id}&business_id={client_business_id}
The deep link url can also be obtained by making a GET
request on endpoint:
curl -X GET \ /<folder_id or asset_id> ?fields=['media_library_url'] &access_token=<user_access_token>
The link allows the user to go to the folder or asset directly under Facebook asset library.
You may request the top-level folder to be shared with you if you want to manage the folder or view insights for the assets. Send a POST
request to: {business-creative-folder-id}/agencies
and assign permitted_tasks
to CREATE_CONTENT
.
Note: You can also assign the VIEW_INSIGHTS
permitted task if the user grants business_creative_insights_share
to your app (under development).
business_creative_management
permissionRequest
curl -X POST \ -F 'permitted_tasks=['CREATE_CONTENT','VIEW_INSIGHTS']' \ -F 'business={partner-business-id} ' \ -F 'access_token={user-access-token}' https://graph.facebook.com/<API_VERSION>/<BUSINESS_CREATIVE_FOLDER_ID>/agencies
The response is in one of two types depending on the user's role in their business organization:
The API will establish a partnership agreement between user business and client business.
Response
If there is an established partnership agreement between the user business and your business (user business shared a folder with you, and you accepted a sharing request before):
{ "success": true }
If you did not accept any sharing request from the user business yet:
{ "success": true, "share_status": "In Progress" }
In this scenario, your business will need to accept the sharing request before your business is able to access all capabilities that are enabled by the share (view, create, and so on).
To list all partnership agreements that are pending approval, send a request to {business-id}/received_sharing_agreements
using your partner access token and set request_status
to IN_PROGRESS
. You need business_creative_management
and business_management
permission for this action.
List All Partnership Agreements
Request
curl -i -X GET https://graph.facebook.com/<API_VERSION>/<PARTNER_BUSINESS_ID>/received_sharing_agreements ?request_status=IN_PROGRESS &access_token={partner-access-token}"
You can accept a sharing request by sending a POST
to business_sharing_agreement_request_id
and set request_status
to APPROVE
. You only need to do this the first time someone shares a folder with your business. You need business_management
permission for this action:
Accept Partnership Agreements
Request
curl -X POST \ -F 'request_status=APPROVE' \ -F 'access_token={partner-access-token}' \ https://graph.facebook.com/<API_VERSION>/<BUSINESS_SHARING_AGREEMENT_REQUEST_ID>
Response
{ "success": true }
Alternatively, you can approve pending sharing requests in the Business Manager UI. To see pending requests in Business Manager, go to Settings > Requests > Received Requests, where you can see more information about the request.
The API triggers a Notification workflow to send an email notification to business admins to approve the request.
Response
{ "success": true, "share_status": "Pending" }
In response to this state, your app should inform the user that:
To list all pending agreements that have been initiated in the user’s business, send a request to {business-id}/attempted_sharing_agreements
and set request_status
to IN_PROGRESS
, set requesting_business_id
to the user's Business Manager ID. You need business_creative_management
and business_management
permission for this action.
List All Pending Folder Sharing Agreements
Request
curl -i -X GET \ https://graph.facebook.com/<API_VERSION>/<PARTNER_BUSINESS_ID>/attempted_sharing_agreements ?request_status=IN_PROGRESS &requesting_business_id=<user_business_id> &access_token={partner-access-token}
List All Pending Folder Sharing Agreements With Request ID
Alternatively, if you have the request ID, you can directly get status by sending a request to {request_id}
.
business_creative_management
permissionRequest
curl -i -X GET \ https://graph.facebook.com/<API_VERSION>/<REQUEST_ID>?fields=status
When a business admin approves the request, the status changes to APPROVE
and the folder is shared back to your Business Manager if the user’s business and your business have established a sharing agreement relationship (user business shared a folder with you, and you accepted a sharing request before). Otherwise, the share_status
is updated to IN_PROGRESS
. You can list all partnership agreements with IN_PROGRESS
status and accept them via API or in the Business Manager UI.
When the user shares a folder to you with permission for the VIEW_INSIGHTS
task, you can read insights of business images and videos under the shared folder by making a GET
request on <business_asset_id>/insights
endpoint.
business_creative_management
and business_creative_insights
permission.Request
curl -i -X GET \ https://graph.facebook.com/<API_VERSION>/<BUSINESS_ASSET_ID>/insights ?breakdowns=["age","gender"] &fields=impressions,inline_link_clicks,age,gender,date_start, &time_range={"since":"2019-08-01","until":"2019-08-22"} &access_token={partner-access-token}"
Response
{ "data": [ { "impressions": 99, "inline_link_clicks": 1, "age": "18-24", "gender": "female", "date_start": "2019-08-01", "date_end": "2019-08-22" }, { "impressions": 198, "inline_link_clicks": 2, "age": "18-24", "gender": "male", "date_start": "2019-08-01", "date_end": "2019-08-22" }, { "impressions": 464, "inline_link_clicks": 2, "age": "25-34", "gender": "female", "date_start": "2019-08-01", "date_end": "2019-08-22" }, ] }
The breakdown can be by:
gender
age
country
publisher_platform
platform_position
device_platform
ad_id
objective
optimization_goal
time_range
(requires a date in the format of "YYYY-MM-DD", which means from the beginning midnight of that day.)For managed service partners, you can manage the top-level folder with a partner access token if the folder has been shared back to you with proper permitted tasks which grant you:
CREATE_CONTENT
task permission on the folder, which allows your app to create subfolders and upload images and videos to the folder.VIEW_INSIGHTS
task permission, which your app can use to view performance insights of any creative assets stored in this folder.Call <business_id>/creative_folders
endpoint to get all parent folders that are shared to you under the user’s business.
business_creative_management
permissionGet folders from the user's business
Request
curl -X GET \ -F 'access_token={partner-access-token}' \ https://graph.facebook.com/<API_VERSION>/<partner_business_id>/creative_folders?filtering=[{field:"owner_business_id", operator:"EQUAL", value:"user_business_id"}]
Response
{ "data": [ { "id": "<shared_folder_id>" } ] }
Get permitted tasks you have on the folder
Request
curl -X GET \ -F 'access_token={partner-access-token}' \ https://graph.facebook.com/<API_VERSION>/<folder_id>/agencies
Response
{ "data": [ { "id": "<partner_business_id>", "name": "<partner business name>", "permitted_tasks": [ "VIEW_INSIGHTS", "VIEW_CONTENT", "CREATE_CONTENT", "MANAGE_CONTENT", "MANAGE_PERMISSIONS"] } ], }
CREATE_CONTENT
task permission task is required to upload images and videos to a shared folderVIEW_INSIGHTS
task permission task is required to query creative insights of images or videos under a shared folderWith CREATE_CONTENT
task permission on the parent folder, you can create a subfolder in a shared folder.
business_creative_management
permissionCreate subfolder
Request
curl -X POST \ -F "name={folder_name}" -F "description={description}" -F "parent_folder_id={parent-folder-id}" -F 'access_token={partner-access-token}' \ https://graph.facebook.com/<API_VERSION>/<BUSINESS_ID>/creative_folders
Response
{ "id": {subfolder-id} }
Follow the same steps listed in Step 5. Upload images and videos to subfolder with partner token.
When your app uploads an image or video to Facebook’s asset library, Facebook’s API will return an ID for that asset.
To facilitate ongoing continuity, your app will need to track the asset’s ID against the project/workspace that produced this image/video in your app.
This will allow for streamlined ‘edit’ and ‘update’ use cases, which will be supported in the future, for example:
media_library_url
fieldRequest
curl -X GET \ -F 'access_token={partner-access-token}' \ https://graph.facebook.com/<API_VERSION>/<asset_id>?fields=media_library_url
&action=CREATE_AD
or &action=CREATE_POST
at the end of the deep link of above step.Example:
https://business.facebook.com/asset_library/business_creatives/?object_id=2838437832929622&action=CREATE_AD