Business Creative Assets

Use the Business Creative Asset Manager API to create folders to store and share ad creatives between your business and another. Advertisers own business creative and assets in the folders. You send sharing requests to business admins in Business Manager and email notifications to business admins for their approval.

Note: This API is under limited availability. Please contact your Facebook Representative for access.

Business Creative Folder

A folder contains both images and videos which you can use for ads creation through Ads Manager or Marketing API. Only a business admin can create this folder. The business admin can then grant employees permissions to manage the business creative folder and share folders to other businesses.

We represent shared creative assets as business_image_id or business_video_id.

Business Creative Asset Sharing Agreement

When you share a business creative folder, the other business must agree that certain creative-level insights for the creative are owned by your business. Another business can accept or decline this agreement in Business Manager Settings or via third party apps.

Business Creative Insights

The /insights edge provides aggregated business creative level metrics that allow you to view impressions, inline link clicks, and video plays for your business creative object. These metrics are aggregated from the past 28 days for ads that use this business creative.

Requirements

Permissions

To use this API, your app must undergo App Review for the following permissions:

  • business_creative_management - Manage business creative folders and business creatives. Required for all Business Creative Asset Manager API endpoints.
  • business_creative_insights - Access business creative asset insights.
  • business_management - Manage business users and accept partnership agreement requests.

Implement Facebook Login

See Facebook Login documentation to install an SDK and add Facebook Login into your app. People using your app can authenticate and grant your app permission, in the form of access tokens, to access their data on Facebook.

Advertisers log in to your app or website and can agree to give your app business_creative_management and business_creative_insight permissions.

Using the advertiser's access token, you can make API calls on their behalf. Note, the advertiser represented in this request must be a business admin for their business.

Create a Business Creative Folder

Create a business creative folder on behalf of the advertiser's business by making a POST request to the {business-id}/creative_folders endpoint where {business-id} is the advertiser's business ID. The business_creative_management permission is required for this action.

Example Request

curl -X POST \
  -F 'name={folder-name}' \
  -F 'access_token={access-token}' \
  https://graph.facebook.com/<API_VERSION>/<BUSINESS_ID>/creative_folders

Example Response

{ “id”: “{business-creative-folder-id}” }

Assign Permissions to Business Users

Anyone who creates a folder automatically has full permissions to that folder. If anyone else wants to manage folder assets or view asset insights, the business admin can give them permission by sending a POST request to {business-creative-folder-id}/assigned_users where {permitted-task} is one or more of the MANAGE_PERMISSIONS, MANAGE_CONTENT, CREATE_CONTENT, VIEW_CONTENT, or VIEW_INSIGHTS permissions. You need business_creative_management permission to perform this action:

curl -X POST \
  -F 'tasks=['{permitted_task}']' \
  -F 'user={app-scoped-business-user-id}' \
  -F 'access_token={access-token}' \
  https://graph.facebook.com/<API_VERSION>/<BUSINESS_CREATIVE_FOLDER_ID>/assigned_users

The response:

{ "success": true }

Get Business Users

To list people who can access this folder, send a request to the {business-id}/business_users. You need business_creative_management and business_management permissions for this action.

curl -i -X GET https://graph.facebook.com/<API_VERSION>/<BUSINESS_ID>/business_users?access_token={access-token}

Get Business Creative Folder Users

To get a list of people who can manage a business creative folder, send a request to the {business-creative-folder-id}/assigned_users?business={business-id}, where {business-id} is your business ID. You need business_creative_management permission for this action.

curl -i -X GET https://graph.facebook.com/<API_VERSION>/<BUSINESS_CREATIVE_FOLDER_ID>/assigned_users?business={business-id}&access_token={access-token=access-token)}

Share Creative Folders

Ask a business to share their creative folder by sending a request. Send a POST request to {business-creative-folder-id}/agencies and assign permitted_tasks to MANAGE_CONTENT. You need business_creative_management permission for this action.

Example — The VIEW_INSIGHTS permission is added to view insights for the creative assets in the folder:

curl -X POST \
  -F 'permitted_tasks=['MANAGE_CONTENT','VIEW_INSIGHTS']' \
  -F 'business={partner-business-id} ' \
  -F 'access_token={access-token}' \
     https://graph.facebook.com/<API_VERSION>/<BUSINESS_CREATIVE_FOLDER_ID>/agencies

Response — If a business shared a folder with you, and they accepted a sharing request from you:

{ "success": true }

Response — If the business did not accept a sharing request yet:

{
  "success": true,
  "share_status": "In Progress"
}

See In-Progress Requests

To list all partnership agreements that do not have a response, send a request to {business-id}/received_sharing_agreements and set request_status to IN_PROGRESS. You need business_creative_management permission for this action.

curl -i -X GET "https://graph.facebook.com/<API_VERSION>/<BUSINESS_ID>/received_sharing_agreements
     ?request_status=IN_PROGRESS
     &access_token={access-token}"

Accept a Request

You can accept a sharing request by sending a POST to business_sharing_agreement_request_id and set request_status to APPROVE. Note: You only need to do this the first time someone shares a folder with your business.

You need business_management permission for this action:

curl -X POST \
     -F 'request_status=APPROVE' \
     -F 'access_token={access-token}' \
     https://graph.facebook.com/<API_VERSION>/<BUSINESS_SHARING_AGREEMENT_REQUEST_ID>

Response

{ "success": true }

Alternatively, to see pending requests, go to Business Manager Settings > Requests > Received Requests.

Share Creative Folders

If you have an agency or partner create your ads you should share your creative folder. Developers can also build a flow so advertisers can share their folders to another business. Your app should send a POST request to creative_folder_id/agencies and set the business field to the partner's business ID and permitted_tasks field to MANAGE_CONTENT. You need business_creative_management permission for this action.

Example — Add the VIEW_INSIGHTS permission where your app's users can view the insights for creative assets in the folder:

curl -X POST \
  -F 'permitted_tasks=['MANAGE_CONTENT','VIEW_INSIGHTS']' \
  -F 'business={partner-business-id}' \
  -F 'access_token={access-token}' \
  https://graph.facebook.com/<API_VERSION>/<BUSINESS_CREATIVE_FOLDER_ID>/agencies

Response

{
  "success":true,
  "share_status": "In Progress"
}

Add Creative to Folders

Add existing creative assets to a folder by making a POST request to {business-id}/images or {business-id}/videos. You need business_creative_management permission for this action.

Add Images

Example — To add an image:

curl -X POST \
  -F 'bytes={image-content-in-bytes-format}' \
  -F 'name={image-name}' \
  -F 'access_token={access-token}' \
  -F 'creative_folder_id={business-creative-folder-id}' \
  https://graph.facebook.com/{version}/{business-id}/images

Response

{
  "images":{
    "{image-name}":{
      "id":"{business-creative-image-id}",
      "hash":"{hash}",
      "url":"{image-url}"
    }
  }
}

Upload Videos

Upload a video in a single request, if it is less than a few megabytes, or upload it in chunks. 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 business creative folder ID.

curl -X POST \
  -F 'name={video-name}' \
  -F 'source='@{video-path}'' \
  -F 'access_token={access-token}' \
  -F 'creative_folder_id={business-creative-folder-id}' \
  https://graph-video.facebook.com/{version}/{business-id}/videos

Response

{ "id": "{video-id}" }

The returned ID is the actual video_id node. You can query business-video-id from creative_folder_id/videos.

Upload Chunked Videos

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.

curl -X POST \
  -F 'title={video-name}' \
  -F 'creative_folder_id={business-creative-folder-id}' \
  -F 'access_token={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

curl -X POST \
  -F 'title={video-name}' \
  -F 'access_token={access-token}' \
  -F 'creative_folder_id={business-creative-folder-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

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:

curl -X POST \
  -F 'title={video-name}' \
  -F 'access_token={access-token}' \
  -F 'creative_folder_id={business-creative-folder-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

Send all additional chunks until start_offset equals end_offset:

{
  "start_offset": "152043520",
  "end_offset": "152043520"
}

This means you uploaded the whole file. Now you need to post this video and close the upload session.

curl -X POST \
  -F 'title={video-name}' \
  -F 'access_token={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:

Once you upload creative to a folder, advertisers with access to the folder can create ads either on Ads Manager or with Marketing API.

All uploaded creatives appear in Ads Manager > Business section > Media Selection UI. You can use them in Ads Creation and Ads Editing.

Example

For videos:

Create Ads

If you have permission to run ads on behalf of advertisers, create ads with business creative IDs. If you don't have permissions, use the creatives uploaded to business creative folders.

View Shared Creative Insights

To view insights, send a request to {business-image-id}/insights or {business-video-id}/insights. You need business_creative_management and business_creative_insights permissions for this action.

  • The default date range is the last 28 days; you can also query with the time_range parameter.
  • Current supported metrics are: impressions, inline_link_clicks, and video_play_actions.
  • Current supported breakdowns are: age, gender, country.

Example Request

curl -i -X GET "https://graph.facebook.com/{version}/{business-creative-id}/insights?fields=impressions,inline_link_clicks,date_end,date_start,age&time_range={"since":"2019-08-01","until":"2019-08-05"}&breakdowns=['age']&access_token={access-token}"

Example Response

{
  "data": [
    {"impressions": 273,     "inline_link_clicks": 3,       "date_end": "2019-08-05",            "date_start": "2019-08-01",    "age": "18-24"    },    {
     "impressions": 1201,    "inline_link_clicks": 10,      "date_end": "2019-08-05",           "date_start": "2019-08-01",    "age": "25-34"    },    {
     "impressions": 612,     "inline_link_clicks": 2,       "date_end": "2019-08-05",           "date_start": "2019-08-01",    "age": "35-44"    },    {
     "impressions": 154,     "inline_link_clicks": 0,       "date_end": "2019-08-05",           "date_start": "2019-08-01",    "age": "45-54"    },    {
     "impressions": 33,      "inline_link_clicks": 1,       "date_end": "2019-08-05",           "date_start": "2019-08-01",    "age": "55-64"    },    {
     "impressions": 19,      "inline_link_clicks": 0,       "date_end": "2019-08-05",           "date_start": "2019-08-01",    "age": "65+"    }
          ]
 }

Business creative insights are under development. These metrics are still being tested and may change as we improve our methodologies. See Estimated & In-Development Metrics Guide for more information.

Example

curl -i -X GET "https://graph.facebook.com/{version}/{business-creative-id}/insights?access_token={access-token}"

Response

{
  "data":[
    {
      "impressions": 3657,
      "inline_link_clicks": 39,
      "date_start": "2019-05-05",
      "date_end":"2019-06-02"
    }
  ]
}

Media-Level Ad Format Validation

Business Creative Media Validation Results

Placement Label

FACEBOOK_STORY_MOBILE

Facebook Stories

MOBILE_FULLWIDTH

Mobile (full width)

MOBILE_INTERSTITIAL

Audience Network Interstitial

MOBILE_MEDIUM_RECTANGLE

Audience Network Medium Rectangle

MOBILE_NATIVE

Audience Network Native

INSTAGRAM_STANDARD

Instagram Feed

INSTAGRAM_STORY

Instagram Stories

INSTANT_ARTICLE_STANDARD

Instant Articles

MESSENGER_MOBILE_INBOX_MEDIA

Messenger Inbox

MESSENGER_MOBILE_STORY_MEDIA

Messenger Stories

DESKTOP_FEED_STANDARD

Desktop News Feed

MOBILE_FEED_STANDARD

Mobile News Feed

RIGHT_COLUMN_STANDARD

Desktop Right Column

Supported Video Ad Placements

Placement Label

FACEBOOK_STORY_MOBILE

Facebook Stories

MOBILE_FULLWIDTH

Mobile (Full width)

AUDIENCE_NETWORK_INSTREAM_VIDEO

Audience Network In-Stream Video

AUDIENCE_NETWORK_INSTREAM_VIDEO_MOBILE

Audience Network In-Stream Video (Mobile)

MOBILE_INTERSTITIAL

Audience Network Interstitial

MOBILE_MEDIUM_RECTANGLE

Audience Network Medium Rectangle

AUDIENCE_NETWORK_REWARDED_VIDEO

Audience Network Rewarded Video

INSTAGRAM_STANDARD

Instagram Feed

INSTAGRAM_STORY

Instagram Stories

INSTANT_ARTICLE_STANDARD

Instant Articles

INSTREAM_VIDEO_DESKTOP

Facebook In-Stream Video (Desktop)

INSTREAM_VIDEO_MOBILE

Facebook In-Stream Video (Mobile)

MESSENGER_MOBILE_INBOX_MEDIA

Messenger Inbox

MESSENGER_MOBILE_STORY_MEDIA

Messenger Stories

DESKTOP_FEED_STANDARD

Desktop News Feed

MOBILE_FEED_STANDARD

Mobile News Feed

SUGGESTED_VIDEO_MOBILE

Suggested Videos (Mobile)

Supported Endpoints

Ad Placement Validation on Existing Images or Videos

To see validation results for an existing image or video, send a GET request to the {business-image-id}/ad_placement_validation_results or {business-video-id}/ad_placement_validation_results edge.

Example Response (Image)

{
  "data": [
    {
      "ad_placement": "FACEBOOK_STORY_MOBILE",
      "ad_placement_label": "Facebook Stories",
      "is_valid": false,
      "error_messages": [
        "Fb Story Ads Resolution Is Too Low: The width of photo and video has to be larger than 500px for ads in Facebook Stories."
      ]
    },
...
    {
      "ad_placement": "INSTANT_ARTICLE_STANDARD",
      "ad_placement_label": "Instant Articles",
      "is_valid": true
    }
  ]
}

Example Response (Video)

{
  "data": [
    {
      "ad_placement": "INSTREAM_VIDEO_MOBILE",
      "ad_placement_label": "Facebook In-Stream Video (Mobile)",
      "is_valid": false,
      "error_messages": [
        "Ad Video Duration Is Too Short: Duration of the video used in the ad is too short."
      ]
    },
...
    {
      "ad_placement": "FACEBOOK_STORY_MOBILE",
      "ad_placement_label": "Facebook Stories",
      "is_valid": true
    }
  ]
}

Ad Placement Validation on all Business Creatives

You can also conveniently run validation against all creatives within a business by adding the ad_placement_validation_results field on a GET request to the {business-id}/creatives edge.

Example Request

curl -i -X GET \
 "https://graph.facebook.com/{version}/{business-id}/creatives?fields=ad_placement_validation_results&access_token={access_token}"

Ad Placement Validation at Upload Endpoints

When adding creatives to a folder, you can also run ad placement validation when uploading the creative by providing an array of ad placements through the optional validation_ad_placements parameter on either image/video upload POST request. The supported placement types can be found in the Placement column in Supported Video Ad Placements. The API runs validations against the provided ad placements, rejects the upload if validation fails on any of them, and returns the validation results in the response.

An example call could include the parameter like this:

"validation_ad_placements"=["FACEBOOK_STORY_MOBILE", "MESSENGER_MOBILE_STORY_MEDIA"]

The results of the validation will be returned in a example response like this:

"validation_results" => [
    {
        "ad_placement" => "FACEBOOK_STORY_MOBILE"
        "ad_placement_label" => "Facebook Stories"
        "error_messages" => ["The width of the media in the ad is too low. Try to use a different media.""The height of the media in the ad is too low. Try to use a different media."],
        "is_valid" => false,
    },
    {
        "ad_placement" => "MESSENGER_MOBILE_STORY_MEDIA"
        "ad_placement_label" => "Messenger Stories",
        "error_messages" => [],
        "is_valid" => true.
    },
]

Conditional Results

  • If the validation fails (as in the above example), then only validation_results are returned in the response.
  • If all validation passes, then the validation_results will be appended to the normal upload response.
  • If you ONLY run validations against the uploaded media (and never persist the upload), then you can include a validation_only parameter that, if set to true, will cause the API to always reject uploads and solely returns the validation results.
  • If validation_only is flagged true, but no ad placements are provided through validation_ad_placements, then the API will default to running validation for all ad placements.

Reference

Post

EndpointDescription

/{ad-account-id}/ads

Create an ad.

/{agreement-request-id}

Approve or decline a pending business agreement request.

/{business-creative-folder-id}

Create and update a business creative folder.

/{business-id}/creative_folders

Provide a business creative folder.

/{business-id}/images

Upload images to a creative folder.

/{business-id}/videos

Upload videos to a creative folder.

/{business-creative-folder-id}/agencies

Add a partner to a creative folder.

/{business-creative-folder-id}/assigned_users

Get a list of people who have access to the business creative folder.

Read

EndpointDescription
/{business-creative-folder-id}

Get details about a business creative folder.

/{business-id}/creative_folders

Get a list of business creative folders a business can access.

/{business-id}/creatives

Get business images and business videos of the business.

/{business-id}/initiated_sharing_agreement

Get a list of pending agreement requests.

/{business-id}/received_sharing_agreement

Get a list of pending agreement requests send to another business from yours.

/{business-image-id}

Get details for an image.

/{business-image-id}/insights

Get insights for a shared image.

/{business-video-id}

Get details of the shared video.

/{business-video-id}/insights

Get the insights for the shared video.

/{business-creative-folder-id}/agencies

Get a list of businesses who have access to your creative folder.

/{business-creative-folder-id}/assigned_users

Get a list of people who have access to your creative folder.

Delete

EndpointDescription
/{business-creative-folder-id}

Delete a creative folder.

/{business-creative-folder-id}/agencies

Remove a partner from the creative folder.

/{business-creative-folder-id}/assigned_users

Remove a user from the creative folder.

/{business-image-id}

Remove a shared image.

/{business-video-id}

Remove a shared video.

Permitted Tasks

Business User Permitted TaskDescription

CREATE_CONTENT

This user can create folders.

MANAGE_CONTENT

This user can manage creative folder assets.

MANAGE_PERMISSIONS

This user can manage business creative folder permissions.

VIEW_CONTENT

This user can view assets in a creative folder.

VIEW_INSIGHTS

This user can view the insights for a creative asset.

Insights

These metrics are under development.

Metric NameDescription
impressions

The number of times your image or video appeared in an ad.

inline_link_clicks

The number of clicks on links in your ad. Inline link clicks use a fixed 1-day-click attribution window.

video_play_actions

The number of times your video starts to play. We cound this for each video impression, and exclude replays.

The following breakdowns are available:

  • age
  • gender
  • country