Creating Branded Content with the Graph API

Verified pages (with the blue checkmark) can share branded content on Facebook. Branded content is typically posted by media companies, celebrities, or other influencers. Posts that include branded content must comply with our branded content policy and ads policy and use the branded content tool to tag marketers in their posts

This document covers the API for creating branded content. You can also use the branded content tool to create branded content for Pages, which is an additional icon in the composer used to create Page posts, available to verified pages.

Learn more about branded content in our media portal.

Overview

Branded content can be created on the following types of posts:

  • A status update, including text, sharing a link, or a multi-photo post
  • Photos
  • Videos
  • Live videos

Each type uses a different endpoint during creation, but all involve adding a sponsor_tags field in the post. A sponsor tag points at a Facebook Page.

Creating Branded Content

Creating a Status Update

Creating a status update means posting to a Page's feed endpoint. At a minimum, the POST must contain values for the sponsor_id and the message fields.


Posting a Photo

Creating a photo story requires posting to a Page's photos endpoint. At a minimum, the POST must contain values for the sponsor_id and the message fields.

You can use the url field to link to an existing photo, as in this example. You can also upload the photo as an attachment to the POST. See our guide on uploading photos for more information.


Posting a Video

Posting a video with branded content requires several steps. These include:

  1. Making a call that indicates that a video will be uploaded. The API returns the ID of the video object you can use to upload the video.
  2. Upload the video.
  3. Finalize the video transfer. When finalizing the transfer, you add the sponsor_id field to the request, which will add the branded content to the story.

For more information on uploading videos, please see our documentation on uploading videos.

In this example using curl, the request is started, the video is uploaded, and then the post is finalized with a sponsor_id.

curl -X POST "https://graph-video.facebook.com/v2.6/372501189608751/videos" \
  -F "access_token=$at" \
  -F "upload_phase=start" \
  -F "file_size=20314209"

{"video_id":"505657299626472","start_offset":"0","end_offset":"1048576","upload_session_id":"505657306293138"}
curl -X POST "https://graph-video.facebook.com/v2.6/372501189608751/videos" \
  -F "access_token=$at" \
  -F "upload_phase=transfer" \
  -F "start_offset=0" \
  -F "upload_session_id=505657306293138" \
  -F "video_file_chunk=@videos/test_video.mp4"

{"start_offset":"20314209","end_offset":"20314209"}
curl -X POST "https://graph-video.facebook.com/v2.6/372501189608751/videos" \
  -F "access_token=$at" \
  -F "upload_phase=finish" \
  -F "upload_session_id=505657306293138" \
  -F "sponsor_id=130533530354972"

{"success":true}

This is what the resulting branded content will look like:


Live Video

Creating a branded live video requires more than one step. The process for creating a branded live video is:

  1. Create the live video object
  2. Update the live video object and add the sponsor_id field
  3. Start your stream

Creating a live video object and starting your live video stream is out of the scope of this guide. To learn more about creating and managing live video streams, please see our documentation on live videos.

The example below queries the list of live videos for a page and uses that ID to update the sponsor_id. But instead of querying the list and updating the ID, you could use the ID that's returned when the live video is first created.

Query the list of live videos to get a live video id:

Update the live video with the sponsor_id:

The story created will include the brand:

Updating Branded Content

Updating stories with a brand ID is not supported on the web or on mobile devices, but it is possible to use the Graph API to update a story to include or change a sponsor. You can change the sponsor by changing the value of the sponsor_id field on a post object.

This is what is returned on a post that doesn't have a sponsor. Reading data is covered later in this document, but the information is contained in the sponsor_tags field:

To add a sponsor to a post, make POST on a Page post with the sponsor_id field set:

Here's what it would look like:

If you want to change the sponsor on a post, pass in the new sponsor_id field:

And an updated story:

Reading Branded Content

Reading the sponsor off of a post, video, live video, or video is done by accessing the individual type of node, and looking for the sponsor_tags field.

For example, here's how you can read the sponsors off of a post:

And reading the value off of a photo: