Create Partnership Ads by Boosting an Existing Post

Advertisers can now boost more types of organic Instagram content as partnership ads, including branded content with the paid partnership label, Instagram Collab posts, @mentions, people tags, product tags, and other content without the paid partnership label, but advertisers can still use the ad code or an existing media ID to create partnership ads for all types of contents.

This document shows you how to:

• Fetch branded content media
• Fetch creator content recommendations that Meta predicts will be the best performing partnership ads for objectives
• Create partnership ads using the branded content media
• Create partnership ads using the partnership ad code

Before You Start

Review the requirements for creating partnership ads.

Limitations

• Recommendations are currently only available for partnership ads posts that have explicitly used the Paid Partnership Label.

Fetch the Branded Content Media

To get all media that an advertiser is tagged in, that are available to be used in an ad, send a GET request to the /<INSTAGRAM_ID>/branded_content_advertisable_medias endpoint where the INSTAGRAM_ID is the ID for the Instagram Professional account for your brand.

Parameters

Sample Request

Formatted for readability.

curl -i -X GET \
  -d 'creator_username=<CREATOR_USERNAME>' \
  -d 'access_token=<PAGE_ACCESS_TOKEN>' \
  -d 'permalinks=[<’PERMALINK1’,’PERMALINK2’>]' \
  -d 'only_fetch_allowlisted=<BOOLEAN>' \
  -d 'only_fetch_recommended_content=<BOOLEAN>' \
  -d 'ad_code=<CREATOR_AD_CODE>' \
'https://graph.facebook.com/v24.0/<INSTAGRAM_ACCOUNT_ID>/branded_content_advertisable_medias?fields=eligibility_errors,owner_id,permalink,id&access_token=<ACCESS_TOKEN>,has_permission_for_partnership_ad'

Sample Response

Upon success, your app will receive a list of media containing the media id, eligibility errors (if any), permalink, if advertiser has permissions to boost the post and owner ID of the media that can be used in ads.

{
 "data": [
 	{
     "eligibility_errors": [
        "Cannot use Reels containing tappable elements can't be used for ads. Choose a different post to create an ad."
      ],
      "recommended_campaign_objectives": [
        "OUTCOME_ENGAGEMENT",
        "OUTCOME_TRAFFIC",
        "OUTCOME_LEADS"
      ],
      "has_permission_for_partnership_ad":true
      "owner_id": "16502228360082",
      "permalink": "https://www.instagram.com/reel/CzboAd3R91-/",
      "id": "16502230933174"
    },
    {
      "owner_id": "90010135660647",
      "permalink": "https://www.instagram.com/p/CywLmKWu6Zs/",
      "id": "90013017840068",
      "has_permission_for_partnership_a":true
    },
    {
      "owner_id": "90010489752294",
      "permalink": "https://www.instagram.com/p/CyWe6-ExB7p/",
      "id": "90012928652981",
      "has_permission_for_partnership_ad":false
    },
    {
      "eligibility_errors": [
        "Can’t use GIF stickersRemove or choose a different sticker."
      ],
      "owner_id": "90010135660647",
      "permalink": "https://www.instagram.com/reel/CyEb6q4OuoN/",
      "id": "90012872006248"
    },
  ...
 ],
 "paging": {
    "cursors": {
      "before": "QVFIUkR6amZAhLVVVWGpfTlRBenRsOUJCQ3lR==",
      "after": "QVFIUlhBX1hoQzI4SkVFaTRoeEpTdEpJMFdIUh=="
    }}

Recommended creator content

The API responds to a only_fetch_recommended_content request with recommended_campaign_objectives. When reviewing recommendations, remember that different ad objectives have distinct recommendations.

To help you understand the mapping, here is a breakdown of the equivalent campaign objectives in Ads Manager:

Note: The same content is eligible to be recommended for multiple objectives.

You may encounter content without any associated recommendations. This could be due to the following reasons:

• Recommendations require a 3-day lag to generate, allowing organic engagement metrics to stabilize.
• Recommendations are only available for content published within the last 60 days.
• If no recommendations are available, there will be no associated information displayed.

Owned and tagged media

Use the media_relationship parameter to fetch the owned and tagged media of an Instagram account.

Example requests

Fetch all tagged media of a specific Instagram account

curl -i -X GET \
  -F 'media_relationship=["IS_TAGGED"]' \
  -F 'access_token=<ACCESS_TOKEN>' \
'https://graph.facebook.com/v24.0/<INSTAGRAM_ACCOUNT_ID>/branded_content_advertisable_medias'

Fetch all owned media of a specific Instagram account

curl -i -X GET \
  -F 'media_relationship=["OWNED"]' \
  -F 'access_token=<ACCESS_TOKEN>' \
'https://graph.facebook.com/v24.0/<INSTAGRAM_ACCOUNT_ID>/branded_content_advertisable_medias'

Fetch all owned and tagged media of a specific Instagram account

curl -i -X GET \
  -F 'media_relationship=["OWNED","IS_TAGGED"]' \
  -F 'access_token=<ACCESS_TOKEN>' \
'https://graph.facebook.com/v24.0/<INSTAGRAM_ACCOUNT_ID>/branded_content_advertisable_medias'

Fetch tagged media, filtered to only return media by the specified creator, and all owned media

curl -i -X GET \
  -F 'creator_username=<CREATOR_USERNAME>' \
  -F 'media_relationship=["OWNED","IS_TAGGED"]' \
  -F 'access_token=<ACCESS_TOKEN>' \
'https://graph.facebook.com/v24.0/<INSTAGRAM_ACCOUNT_ID>/branded_content_advertisable_medias'

Create an Ad Creative

Parameters

Using the Instagram Media ID

To create ads, you will use the Marketing API as you normally would for ads creation.

Send a POST request to the /act_<AD_ACCOUNT_ID>/adcreatives endpoint with the object_id field set to the ID for the Facebook Page for your brand and the source_instagram_media_id field set to the ID for the Instagram Post for the branded content you want to use in your ad.

Request

Formatted for readability.

curl -X POST \
  -F 'object_id=<PAGE_ID>' \
  -F 'source_instagram_media_id=<IG_MEDIA_ID>' \
  -F 'access_token=<ACCESS_TOKEN>' \
  -F 'facebook_branded_content={
    "sponsor_page_id": "<ADVERTISER_FB_PAGE_ID>"
  }' \
  -F 'instagram_branded_content={
    "sponsor_id": "<ADVERTISER_IG_ID>"
  }' \
  -F 'branded_content={
    "ad_format": "<AD_FORMAT_TYPE>"
  }' \
'https://graph.facebook.com/v24.0/act_<AD_ACCOUNT_ID>/adcreatives'

Response

Upon success, your app will receive an ID for the ad creative.

{
  "id": "<CREATIVE_ID>"
}

Using the Facebook Post ID

Ads can similarly be created from facebook posts with some minor changes to the API payload. Instead of the source_instagram_media_id, facebook content requires the object_story_id which is a combination of the creator's FB profile, post IDs.

Request

Formatted for readability.

curl -X POST \
  -F 'object_story_id="<CREATOR_PAGE_ID>_<CREATOR_POST_ID>' \
  -F 'access_token=<ACCESS_TOKEN>' \
  -F 'facebook_branded_content={
    "sponsor_page_id": "<ADVERTISER_FB_PAGE_ID>"
  }' \
  -F 'instagram_branded_content={
    "sponsor_id": "<ADVERTISER_IG_ID>"
  }' \
  -F 'branded_content'={
    "ad_format": "<AD_FORMAT_TYPE>"
  }' \
'https://graph.facebook.com/v24.0/act_<AD_ACCOUNT_ID>/adcreatives'

Response

Similarly upon success, your app will receive an ID for the ad creative.

{
  "id": "<CREATIVE_ID>"
}

Using a Partnership Ad Code

To create ads using a Partnership Ad Code, you will use the Marketing API as you normally would for ads creation.

Send a POST request to the /act_<AD_ACCOUNT_ID>/adcreatives endpoint with the object_id field (creator Facebook Page ID) set to the ID for the Facebook Page for your brand and the instagram_boost_post_access_token given by the creator.

Request for using Instagram Media

These are the required fields to be passed in the API call (example in JavaScript):

curl -X POST \
  -F 'object_id=<BRAND_PAGE_ID>' \
  -F 'branded_content ={
       "instagram_boost_post_access_token": "<AD_CODE>",
       "ad_format": "<AD_FORMAT_TYPE>"
   }' \
  -F 'access_token=<ACCESS_TOKEN>' \
  -F 'facebook_branded_content={
    "sponsor_page_id": "<ADVERTISER_FB_PAGE_ID>"
  }' \
  -F 'instagram_branded_content={
    "sponsor_id": "<ADVERTISER_IG_ID>"
  }' \
'https://graph.facebook.com/v24.0/act_<AD_ACCOUNT_ID>/adcreatives'

Request for using Facebook Post

curl -X POST \
  -F 'branded_content ={
       "facebook_boost_post_access_token" : "<AD_CODE>",
       "ad_format": "<AD_FORMAT_TYPE>"
   }' \
  -F 'access_token=<ACCESS_TOKEN>' \
  -F 'facebook_branded_content={
    "sponsor_page_id": "<ADVERTISER_FB_PAGE_ID>"
  }' \
  -F 'instagram_branded_content={
    "sponsor_id": "<ADVERTISER_IG_ID>"
  }' \
'https://graph.facebook.com/v24.0/act_<AD_ACCOUNT_ID>/adcreatives'

Response

Upon success, your app will receive an ID for the ad creative.

{
  "id": "<CREATIVE_ID>"
}

Create an Ad

Next, you will use the ad creative, to create the ad.

Send a POST request to the /act_<AD_ACCOUNT_ID>/ads endpoint with the name field set to the name for your ad, the adset_id field set to the ID for your ad set, the creative field with the creative_id parameter set to the ID for your ad creative, and the status intially set PAUSED.

This will work for ad creatives created from both Instagram media and Facebook posts.

Request

curl -X POST \
  -F 'name": "Ad Name"' \
  -F 'adset_id: <ADSET_ID>' \
  -F 'creative: {"creative_id": <CREATIVE_ID>}' \
  -F 'status: "PAUSED"' \
  -F 'access_token=<ACCESS_TOKEN>' \
'https://graph.facebook.com/v24.0/act_<AD_ACCOUNT_ID>/ads'

Response

Upon success, your app will receive an ID for the ad.

{
"id": "<AD_ID>"
}

You can use this ad ID to publish your ad.

Troubleshooting

Uploading an Instagram Video to Facebook

If you are working on boosting video media, you might encounter the error "Instagram Video Must Be Uploaded To Facebook".

If you have the partnership ad code, you may leverage the following workaround using the the partnership_ad_ad_code parameter to upload the video asset to the Facebook video ad library, instead of resorting to source file information:

• partnership_ad_ad_code – Partnership ad code (numerical). Use this parameter to include a partnership ad code, bypassing the need to know source file information.
• is_partnership_ad – [Optional] Use this parameter to identify that the ad will be a partnership ad.

curl -X POST \
  -F 'source_instagram_media_id=<MEDIA-ID>' \
  -F 'partnership_ad_ad_code=<PARTNERSHIP_AD_AD_CODE>' \
  -F 'is_partnership_ad=true' \
'https://graph.facebook.com/v24.0/act_<AD_ACCOUNT_ID>/advideos'

Upon success, your app will receive an ID for the video.

{
  "id": "<VIDEO-ID>"
}

If you don't have a partnership ad code, refer to the Ad Videos documentation.