Get Started

Learn how to implement creative asset management.

Requirements

To use this API, you need:

Permissions

To use this API, your app must undergo App Review and request 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.

Step 1: 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. The advertiser represented in this request must be a business admin for their business.

Step 2: 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. In this case, {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}” }

You can also create subfolders.

Step 3: 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-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

{ 
    "success": true, 
    "business_video_id": "{business-video-id}" 
}

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

Sample 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:

Step 4: 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.