Graph API Version

Ad Creative

Format which provides layout and contains content for the ad. To see available ad creatives, visit Ads Guide. The guide also contains information on size requirements for each ad unit. See also Facebook for Business and Inline page post creation blog post.

Breaking Change: Political Ads

To increase transparency of ads on Facebook, we require advertisers running political ads to complete authorization. We will begin enforcing this in the next upcoming weeks. You must also indicate that your ad is political and provide the name of the funding source for the ad:

  • Your ad account must be authorized by a Page admin to run political ads for this Page. This is done by a Page admin on the Authorizations tab under Page Settings.

  • Ad account users must go through a verification process.

Examples

For example, get information about an ad creative, such as the ID of the newly created unpublished page post:

use FacebookAds\Object\AdCreative;
use FacebookAds\Object\Fields\AdCreativeFields;

$creative = new AdCreative(<CREATIVE_ID>);
$creative->read(array(
  AdCreativeFields::NAME,
  AdCreativeFields::OBJECT_STORY_ID,
));
from facebookads.adobjects.adcreative import AdCreative

creative = AdCreative(<CREATIVE_ID>)
creative.remote_read(
    fields=[AdCreative.Field.name, AdCreative.Field.object_story_id]
)
AdCreative adCreative2 = new AdCreative(<CREATIVE_ID>, context).get()
  .requestNameField()
  .requestObjectStoryIdField()
  .execute();
curl -G \
  -d 'fields=name,object_story_id' \
  -d 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v2.11/<CREATIVE_ID>

Create a link ad:

use FacebookAds\Object\AdCreative;
use FacebookAds\Object\AdCreativeLinkData;
use FacebookAds\Object\Fields\AdCreativeLinkDataFields;
use FacebookAds\Object\AdCreativeObjectStorySpec;
use FacebookAds\Object\Fields\AdCreativeObjectStorySpecFields;
use FacebookAds\Object\Fields\AdCreativeFields;

$link_data = new AdCreativeLinkData();
$link_data->setData(array(
  AdCreativeLinkDataFields::MESSAGE => 'try it out',
  AdCreativeLinkDataFields::LINK => '<URL>',
  AdCreativeLinkDataFields::IMAGE_HASH => '<IMAGE_HASH>',
));

$object_story_spec = new AdCreativeObjectStorySpec();
$object_story_spec->setData(array(
  AdCreativeObjectStorySpecFields::PAGE_ID => <PAGE_ID>,
  AdCreativeObjectStorySpecFields::LINK_DATA => $link_data,
));

$creative = new AdCreative(null, 'act_<AD_ACCOUNT_ID>');

$creative->setData(array(
  AdCreativeFields::NAME => 'Sample Creative',
  AdCreativeFields::OBJECT_STORY_SPEC => $object_story_spec,
));

$creative->create();
from facebookads.adobjects.adcreative import AdCreative
from facebookads.adobjects.adcreative'<LINK>'data import AdCreativeLinkData
from facebookads.adobjects.adcreativeobjectstoryspec \
    import AdCreativeObjectStorySpec

link_data = AdCreativeLinkData()
link_data[AdCreativeLinkData.Field.message] = 'try it out'
link_data[AdCreativeLinkData.Field.link] = '<LINK>'
link_data[AdCreativeLinkData.Field.image_hash] = '<IMAGE_HASH>'

object_story_spec = AdCreativeObjectStorySpec()
object_story_spec[AdCreativeObjectStorySpec.Field.page_id] = <PAGE_ID>
object_story_spec[AdCreativeObjectStorySpec.Field.link_data] = link_data

creative = AdCreative(parent_id='act_<AD_ACCOUNT_ID>')
creative[AdCreative.Field.name] = 'AdCreative for Link Ad'
creative[AdCreative.Field.object_story_spec] = object_story_spec
creative.remote_create()

print(creative)
AdCreative adCreative = new AdAccount(act_<AD_ACCOUNT_ID>, context).createAdCreative()
  .setName("Sample Creative")
  .setObjectStorySpec(
    new AdCreativeObjectStorySpec()
      .setFieldLinkData(
        new AdCreativeLinkData()
          .setFieldCaption("My caption")
          .setFieldImageHash(<IMAGE_HASH>)
          .setFieldLink(<URL>)
          .setFieldMessage("try it out")
      )
      .setFieldPageId(<PAGE_ID>)
  )
  .execute();
String ad_creative_id = adCreative.getId();
curl \
  -F 'name=Sample Creative' \
  -F 'object_story_spec={ 
    "link_data": { 
      "image_hash": "<IMAGE_HASH>", 
      "link": "<URL>", 
      "message": "try it out" 
    }, 
    "page_id": "<PAGE_ID>" 
  }' \
  -F 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v2.11/act_<AD_ACCOUNT_ID>/adcreatives

You can replace picture with image_hash to specify an image from your ad account's image library. You can also specify image cropping with image_crops in link_data. See Image Crop, Reference.

To create a political ad creative, use the field authorization_category with value POLITICAL. For example:

curl \
-F 'authorization_category=POLITICAL' \
-F 'object_story_spec={
    ...
}' \
-F 'access_token=<TOKEN>' \
https://graph.facebook.com/<VERSION>/<AD_ACCOUNT_ID>/adcreatives 

For guidelines on Facebook ads see Ad Guidelines.

Related Resources

Limits

Only returns 50,000 ad creatives, pagination past this is unavailable.

Fields-Level Limits

Limit Value

Maximum ad title length

25 characters, recommended

Minimum ad title length

1 character

Maximum ad body length

90 characters, recommended

Minimum ad body length

1 character

Maximum length of a URL

1024 characters

Maximum length of an individual word in title or body

30 characters, recommended

Title and Body Limits

  • Should be between minimum and maximum title and body lengths.
  • Cannot start with punctuation \ / ! . ? - * ( ) , ; :
  • Cannot have consecutive punctuation except of three full-stops ...
  • Words no longer than 30 characters
  • Only three 1-character words allowed

The following characters are not allowed:

  • IPA Symbols. Except: &#601;, &#602;, &#603;, &#604;, &#605;, &#606;, &#607;
  • Diacritical Marks. Precomposed version of a character + diacritical mark are allowed. Standalone diacritical marks are not allowed.
  • Superscript and subscript characters except &#8482; and &#8480;
  • These characters ^~_={}[]|<>

Exceptions

  • Link Ads cannot use special characters
  • Page Posts Ads allow special characters such as

Placement

See Placement Validation for restrictions on placement of your ad based on creative.

Reading

An ad creative object is an instance of a specific creative which is being used to define the creative field of one or more ads

Branded Content Posts

As a branded content sponsor, you can read the post IDs of branded content posts where your brand is tagged:

curl -G \
-d "access_token=<ACCESS_TOKEN>" \
"https://graph.facebook.com/<API_VERSION>/<SPONSOR_PAGE_ID>/bc_sponsored_posts?fields=post_id"

Read Thumbnail

Request thumbnail URL and dimensions:

use FacebookAds\Object\AdCreative;
use FacebookAds\Object\Fields\AdCreativeFields;

$creative = new AdCreative(<CREATIVE_ID>);
$fields = array(
  AdCreativeFields::THUMBNAIL_URL,
);
$params = array(
  'thumbnail_width' => 150,
  'thumbnail_height' => 120,
);
$creative->read($fields, $params);

echo $creative->{AdCreativeFields::THUMBNAIL_URL}.PHP_EOL;
from facebookads.adobjects.adcreative import AdCreative

creative = AdCreative(<CREATIVE_ID>)
fields = [AdCreative.Field.thumbnail_url]
params = {
    'thumbnail_width': 150,
    'thumbnail_height': 120,
}
creative.remote_read(fields=fields, params=params)

print(creative[AdCreative.Field.thumbnail_url])
AdCreative adCreative2 = new AdCreative(<CREATIVE_ID>, context).get()
  .setThumbnailWidth(150L)
  .setThumbnailHeight(120L)
  .requestThumbnailUrlField()
  .execute();
curl -G \
  -d 'thumbnail_width=150' \
  -d 'thumbnail_height=120' \
  -d 'fields=thumbnail_url' \
  -d 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v2.11/<CREATIVE_ID>

Example

Graph API Explorer
GET /v4.0/<CREATIVE_ID>/?fields=asset_feed_spec HTTP/1.1
Host: graph.facebook.com
/* PHP SDK v5.0.0 */
/* make the API call */
try {
  // Returns a `Facebook\FacebookResponse` object
  $response = $fb->get(
    '/<CREATIVE_ID>/',
    '{access-token}'
  );
} catch(Facebook\Exceptions\FacebookResponseException $e) {
  echo 'Graph returned an error: ' . $e->getMessage();
  exit;
} catch(Facebook\Exceptions\FacebookSDKException $e) {
  echo 'Facebook SDK returned an error: ' . $e->getMessage();
  exit;
}
$graphNode = $response->getGraphNode();
/* handle the result */
/* make the API call */
FB.api(
    "/<CREATIVE_ID>/",
    {
        "fields": "asset_feed_spec"
    },
    function (response) {
      if (response && !response.error) {
        /* handle the result */
      }
    }
);
Bundle params = new Bundle();
params.putString("fields", "asset_feed_spec");
/* make the API call */
new GraphRequest(
    AccessToken.getCurrentAccessToken(),
    "/<CREATIVE_ID>/",
    params,
    HttpMethod.GET,
    new GraphRequest.Callback() {
        public void onCompleted(GraphResponse response) {
            /* handle the result */
        }
    }
).executeAsync();
// For more complex open graph stories, use `FBSDKShareAPI`
// with `FBSDKShareOpenGraphContent`
NSDictionary *params = @{
  @"fields": @"asset_feed_spec",
};
/* make the API call */
FBSDKGraphRequest *request = [[FBSDKGraphRequest alloc]
                               initWithGraphPath:@"/<CREATIVE_ID>/"
                                      parameters:params
                                      HTTPMethod:@"GET"];
[request startWithCompletionHandler:^(FBSDKGraphRequestConnection *connection,
                                      id result,
                                      NSError *error) {
    // Handle the result
}];
curl https://graph.facebook.com/v4.0/<CREATIVE_ID>/?fields=asset_feed_spec
If you want to learn how to use the Graph API, read our Using Graph API guide.

Parameters

ParameterDescription
thumbnail_height
int64
Default value: 64

Rendered height of thumbnails provided in thumbnail_url, in pixels

thumbnail_width
int64
Default value: 64

Rendered width of thumbnails accessible in thumbnail_url, in pixels

Fields

FieldDescription
id
numeric string

Unique ID for an ad creative, numeric string.

account_id
numeric string

Ad account ID for the account this ad creative belongs to.

actor_id
numeric string

The actor ID (Page ID) of this creative

adlabels

Ad Labels associated with this creative. Used to group it with related ad objects.

applink_treatment
enum {deeplink_with_web_fallback, deeplink_with_appstore_fallback, web_only}

Used for Dynamic Ads. Specify what action should occur if a person clicks a link in the ad, but the business' app is not installed on their device. For example, open a webpage displaying the product, or open the app in an app store on the person's mobile device.

asset_feed_spec

Used for Dynamic Creative to automatically experiment and deliver different variations of an ad's creative. Specifies an asset feed with multiple images, text and other assets used to generate variations of an ad. Formatted as a JSON string.

authorization_category
enum

Specifies whether ad is political or not. If your ad has political content, set this to POLITICAL, otherwise it defaults to null. Your ad will be disapproved if it contains political content but not labeled POLITICAL. See Facebook Advertising Policies. This field cannot be used for Dynamic Ads.

auto_update
bool

deprecated

body
string

The body of the ad. Not supported for video post creatives

branded_content_sponsor_page_id
numeric string

ID for page representing business which runs Branded Content ads. See Creating Branded Content Ads.

bundle_folder_id
numeric string

The Dynamic Ad's bundle folder ID

call_to_action_type
enum {OPEN_LINK, LIKE_PAGE, SHOP_NOW, PLAY_GAME, INSTALL_APP, USE_APP, CALL, CALL_ME, INSTALL_MOBILE_APP, USE_MOBILE_APP, MOBILE_DOWNLOAD, BOOK_TRAVEL, LISTEN_MUSIC, WATCH_VIDEO, LEARN_MORE, SIGN_UP, DOWNLOAD, WATCH_MORE, NO_BUTTON, VISIT_PAGES_FEED, APPLY_NOW, CONTACT, BUY_NOW, GET_OFFER, GET_OFFER_VIEW, BUY_TICKETS, UPDATE_APP, GET_DIRECTIONS, BUY, MESSAGE_PAGE, DONATE, SUBSCRIBE, SAY_THANKS, SELL_NOW, SHARE, DONATE_NOW, GET_QUOTE, CONTACT_US, ORDER_NOW, ADD_TO_CART, VIDEO_ANNOTATION, MOMENTS, RECORD_NOW, GET_SHOWTIMES, LISTEN_NOW, WOODHENGE_SUPPORT, SOTTO_SUBSCRIBE, EVENT_RSVP, WHATSAPP_MESSAGE, FOLLOW_NEWS_STORYLINE, SEE_MORE, FIND_A_GROUP, FIND_YOUR_GROUPS}

Type of call to action button in your ad. This determines the button text and header text for your ad. See Ads Guide for campaign objectives and permitted call to action types.

categorization_criteria
enum

The Dynamic Category Ad's categorization field, e.g. brand

category_media_source
enum

The Dynamic Ad's rendering mode for category ads

destination_set_id
numeric string

The ID of the Product Set for a Destination Catalog that will be used to link with Travel Catalogs

dynamic_ad_voice
string

Used for Store Traffic Objective inside Dynamic Ads. Allows you to control the voice of your ad. If set to DYNAMIC, page name and profile picture in your ad post come from the nearest page location. If set to STORY_OWNER, page name and profile picture in your ad post come from the main page location.

effective_authorization_category
enum

effective_authorization_category

effective_instagram_story_id
numeric string

Used for Instagram Ads. The ID of an Instagram post to display as an Instagram ad.

effective_object_story_id
token with structure: Post ID

The ID of a page post to use in an ad, regardless of whether it's an organic or unpublished page post

enable_direct_install
bool

Whether Direct Install should be enabled on supported devices

enable_launch_instant_app
bool

Whether Instant App should be enabled on supported devices

image_crops

A JSON object defining crop dimensions for the image specified. See image crop reference for more details

image_hash
string

Image hash for ad creative. If provided, do not add image_url. See image library for more details.

image_url
string

A URL for the image for this creative. We save the image at this URL to the ad account's image library. If provided, do not include image_hash.

instagram_actor_id
numeric string

Used for Instagram Ads. Provide Instagram account ID used for running these ads.

instagram_permalink_url
string

URL for a post on Instagram you want to run as an ad. Also known as Instagram media.

instagram_story_id
numeric string

Used for Instagram Stories as Ads. Specifies the Instagram story you want to run as an ad. This field will be deprecated in the future. Use SOURCE_INSTAGRAM_STORY_ID

interactive_components_spec
AdCreativeInteractiveComponentsSpec

Specification for all the interactive components that would show up on the ad

link_deep_link_url
string

to be removed

link_og_id
numeric string

The Open Graph (OG) ID for the link in this creative if the landing page has OG tags

link_url
string

Identify a specific landing tab on your Facebook page by the Page tab's URL. See connection objects for retrieving Page tab URLs. You can add app_data parameters to the URL to pass data to a Page's tab.

messenger_sponsored_message
string

Used for Messenger sponsored message. JSON string with message for this ad creative. See Messenger Platform, Send API Reference.

name
string

Name of this ad creative as seen in the ad account's library.

object_id
numeric string

ID for Facebook object being promoted with ads or relevant to the ad or ad type. For example a page ID if you are running ads to generate Page Likes. See promoted_object.

object_store_url
string

iTunes or Google Play of the destination of an app ad

object_story_id
token with structure: Post ID

ID of a Facebook Page post to use in an ad. You can get this ID by querying the posts of the page. If this post includes an image, it should not exceed 8 MB. Facebook will upload the image from the post to your ad account's image library. If you create an unpublished page post via object_story_spec at the same time as creating the ad, this ID will be null. However, the effective_object_story_id will be the ID of the page post regardless of whether it's an organic or unpublished page post.

object_story_spec

Use if you want to create a new unpublished page post and turn the post into an ad. The Page ID and the content to create a new unpublished page post. Specify link_data, photo_data, video_data, text_data or template_data with the content.

object_type
enum {APPLICATION, DOMAIN, EVENT, OFFER, PAGE, PHOTO, SHARE, STATUS, STORE_ITEM, VIDEO, INVALID}

The type of Facebook object you want to advertise. Allowed values are:
PAGE
DOMAIN
EVENT
STORE_ITEM: refers to an iTunes or Google Play store destination
SHARE: from a page
PHOTO
STATUS: of a page
VIDEO
APPLICATION: app on Facebook
INVALID: when an invalid object_id was specified such as a deleted object or if you do not have permission to see the object. In very few cases, this field may be empty if Facebook is unable to identify the type of advertised object

object_url
string

URL that opens if someone clicks your link on a link ad. This URL is not connected to a Facebook page.

place_page_set_id
numeric string

The ID of the page set for this creative. See theLocal Awareness guide

platform_customizations

Use this field to specify the exact media to use on different Facebook placements. You can currently use this setting for images and videos. Facebook replaces the media originally defined in ad creative with this media when the ad displays in a specific placements. For example, if you define a media here for instagram, Facebook uses that media instead of the media defined in the ad creative when the ad appears on Instagram.

playable_asset_id
numeric string

The ID of the playable asset in this creative

portrait_customizations
AdCreativePortraitCustomizations

This field describes the rendering customizations selected for portrait mode ads like IG Stories, FB Stories, IGTV, etc

product_set_id
numeric string

Used for Dynamic Ad. An ID for a product set, which groups related products or other items being advertised.

recommender_settings
AdCreativeRecommenderSettings

Used for Dynamic Ads. Settings to display Dynamic ads based on product recommendations.

status
enum {ACTIVE, IN_PROCESS, WITH_ISSUES, DELETED}

WITH_ISSUES and IN_PROCESS are available for 4.0 or higher

template_url
string

Used for Dynamic Ads when you want to use third-party click tracking. See Dynamic Ads, Click Tracking and Templates.

template_url_spec

Used for Dynamic Ads when you want to use third-party click tracking. See Dynamic Ads, Click Tracking and Templates.

thumbnail_url
string

URL for a thumbnail image for this ad creative. You can provide dimensions for this with thumbnail_width and thumbnail_height. See example.

title
string

Title for link ad, which does not belong to a page.

url_tags
string

A set of query string parameters which will replace or be appended to urls clicked from page post ads, message of the post, and canvas app install creatives only

use_page_actor_override
bool

Used for App Ads. If true, we display the Facebook page associated with the app ads.

video_id
numeric string

Facebook object ID for video in this ad creative.

Edges

EdgeDescription

The HTML Snippets for previewing this creative

Validation Rules

ErrorDescription
100Invalid parameter
278Reading advertisements requires an access token with the extended permission ads_read
80004There have been too many calls to this ad-account. Wait a bit and try again. For more info, please refer to https://developers.facebook.com/docs/graph-api/overview/rate-limiting.
275Cannot determine the target object for this request. Currently supported objects include ad account, business account and associated objects.
270This Ads API request is not allowed for apps with development access level (Development access is by default for all apps, please request for upgrade). Make sure that the access token belongs to a user that is both admin of the app and admin of the ad account

Creating

Define creative as part of an ad set or standalone. In either case, we store your ad creative in your ad account's creative library to use in ads. If you try to add an creative that isn't unique, we do not generate it and return the creative ID of the existing ad creative. For example, create a Link Ad with a call to action:

use FacebookAds\Object\AdCreative;
use FacebookAds\Object\AdCreativeLinkData;
use FacebookAds\Object\Fields\AdCreativeLinkDataFields;
use FacebookAds\Object\AdCreativeObjectStorySpec;
use FacebookAds\Object\Fields\AdCreativeObjectStorySpecFields;
use FacebookAds\Object\Fields\AdCreativeFields;
use FacebookAds\Object\Values\AdCreativeCallToActionTypeValues;

$link_data = new AdCreativeLinkData();
$link_data->setData(array(
  AdCreativeLinkDataFields::MESSAGE => 'try it out',
  AdCreativeLinkDataFields::LINK => '<URL>',
  AdCreativeLinkDataFields::CALL_TO_ACTION => array(
    'type' => AdCreativeCallToActionTypeValues::SIGN_UP,
    'value' => array(
      'link' => '<URL>',
    ),
  ),
));

$object_story_spec = new AdCreativeObjectStorySpec();
$object_story_spec->setData(array(
  AdCreativeObjectStorySpecFields::PAGE_ID => <PAGE_ID>,
  AdCreativeObjectStorySpecFields::LINK_DATA => $link_data,
));

$creative = new AdCreative(null, 'act_<AD_ACCOUNT_ID>');

$creative->setData(array(
  AdCreativeFields::NAME => 'Sample Creative',
  AdCreativeFields::OBJECT_STORY_SPEC => $object_story_spec,
));

$creative->create();
from facebookads.adobjects.adcreative import AdCreative
from facebookads.adobjects.adcreativelinkdata import AdCreativeLinkData
from facebookads.adobjects.adcreativeobjectstoryspec \
    import AdCreativeObjectStorySpec

link_data = AdCreativeLinkData()
link_data[AdCreativeLinkData.Field.message] = 'My message'
link_data[AdCreativeLinkData.Field.link] = '<URL>'
link_data[AdCreativeLinkData.Field.caption] = 'www.domain.com'

call_to_action = {
    'type': 'SIGN_UP',
    'value': {
        'link': '<URL>',
    },
}

link_data[AdCreativeLinkData.Field.call_to_action] = call_to_action

object_story_spec = AdCreativeObjectStorySpec()
object_story_spec[AdCreativeObjectStorySpec.Field.page_id] = <PAGE_ID>
object_story_spec[AdCreativeObjectStorySpec.Field.link_data] = link_data

creative = AdCreative(parent_id='act_<AD_ACCOUNT_ID>')
creative[AdCreative.Field.name] = 'AdCreative for Link Ad with CTA'
creative[AdCreative.Field.object_story_spec] = object_story_spec
creative.remote_create()
print(creative)
AdCreative adCreative = new AdAccount(act_<AD_ACCOUNT_ID>, context).createAdCreative()
  .setName("Sample Creative")
  .setObjectStorySpec(
    new AdCreativeObjectStorySpec()
      .setFieldLinkData(
        new AdCreativeLinkData()
          .setFieldCallToAction(
            new AdCreativeLinkDataCallToAction()
              .setFieldType(AdCreativeLinkDataCallToAction.EnumType.VALUE_SIGN_UP)
              .setFieldValue(
                new AdCreativeLinkDataCallToActionValue()
                  .setFieldLink(<URL>)
                  .setFieldLinkCaption("Sign up!")
              )
          )
          .setFieldCaption("My caption")
          .setFieldLink(<URL>)
          .setFieldMessage("try it out")
      )
      .setFieldPageId(<PAGE_ID>)
  )
  .execute();
String ad_creative_id = adCreative.getId();
curl \
  -F 'name=Sample Creative' \
  -F 'object_story_spec={ 
    "link_data": { 
      "call_to_action": {"type":"SIGN_UP","value":{"link":"<URL>"}}, 
      "link": "<URL>", 
      "message": "try it out" 
    }, 
    "page_id": "<PAGE_ID>" 
  }' \
  -F 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v2.11/act_<AD_ACCOUNT_ID>/adcreatives

You use link_caption to pass the call to action object. By doing this, you can customize the call to action caption. To customize the call to action description, pass link_description in the call to action object.

Create a carousel ad

use FacebookAds\Object\AdCreative;
use FacebookAds\Object\Fields\AdCreativeFields;
use FacebookAds\Object\Fields\AdCreativeLinkDataFields;
use FacebookAds\Object\Fields\AdCreativeObjectStorySpecFields;
use FacebookAds\Object\Fields\AdCreativeLinkDataChildAttachmentFields;
use FacebookAds\Object\AdCreativeLinkDataChildAttachment;
use FacebookAds\Object\AdCreativeLinkData;
use FacebookAds\Object\AdCreativeObjectStorySpec;

$product1 = (new AdCreativeLinkDataChildAttachment())->setData(array(
  AdCreativeLinkDataChildAttachmentFields::LINK =>
    'https://www.link.com/product1',
  AdCreativeLinkDataChildAttachmentFields::NAME => 'Product 1',
  AdCreativeLinkDataChildAttachmentFields::DESCRIPTION => '$8.99',
  AdCreativeLinkDataChildAttachmentFields::IMAGE_HASH => '<IMAGE_HASH>',
  AdCreativeLinkDataChildAttachmentFields::VIDEO_ID => '<VIDEO_ID>',
));

$product2 = (new AdCreativeLinkDataChildAttachment())->setData(array(
  AdCreativeLinkDataChildAttachmentFields::LINK =>
    'https://www.link.com/product2',
  AdCreativeLinkDataChildAttachmentFields::NAME => 'Product 2',
  AdCreativeLinkDataChildAttachmentFields::DESCRIPTION => '$9.99',
  AdCreativeLinkDataChildAttachmentFields::IMAGE_HASH => '<IMAGE_HASH>',
  AdCreativeLinkDataChildAttachmentFields::VIDEO_ID => '<VIDEO_ID>',
));

$product3 = (new AdCreativeLinkDataChildAttachment())->setData(array(
  AdCreativeLinkDataChildAttachmentFields::LINK =>
    'https://www.link.com/product3',
  AdCreativeLinkDataChildAttachmentFields::NAME => 'Product 3',
  AdCreativeLinkDataChildAttachmentFields::DESCRIPTION => '$10.99',
  AdCreativeLinkDataChildAttachmentFields::IMAGE_HASH => '<IMAGE_HASH>',
));

$link_data = new AdCreativeLinkData();
$link_data->setData(array(
  AdCreativeLinkDataFields::LINK => '<URL>',
  AdCreativeLinkDataFields::CHILD_ATTACHMENTS => array(
    $product1, $product2, $product3,
  ),
));

$object_story_spec = new AdCreativeObjectStorySpec();
$object_story_spec->setData(array(
  AdCreativeObjectStorySpecFields::PAGE_ID => <PAGE_ID>,
  AdCreativeObjectStorySpecFields::LINK_DATA => $link_data,
));

$creative = new AdCreative(null, 'act_<AD_ACCOUNT_ID>');
$creative->setData(array(
  AdCreativeFields::NAME => 'Sample Creative',
  AdCreativeFields::OBJECT_STORY_SPEC => $object_story_spec,
));

$creative->create();
from facebookads.adobjects.adcreative import AdCreative
from facebookads.adobjects.adcreativelinkdata import AdCreativeLinkData
from facebookads.adobjects.adcreativeobjectstoryspec \
    import AdCreativeObjectStorySpec
from facebookads.adobjects.adcreativelinkdatachildattachment \
    import AdCreativeLinkDataChildAttachment

product1 = AdCreativeLinkDataChildAttachment()
product1[AdCreativeLinkDataChildAttachment.Field.link] = '<URL>' + '/product1'
product1[AdCreativeLinkDataChildAttachment.Field.name] = 'Product 1'
product1[AdCreativeLinkDataChildAttachment.Field.description] = '$8.99'
product1[AdCreativeLinkDataChildAttachment.Field.image_hash] = '<IMAGE_HASH>'
product1[AdCreativeLinkDataChildAttachment.Field.video_id] = '<VIDEO_ID>'

product2 = AdCreativeLinkDataChildAttachment()
product2[AdCreativeLinkDataChildAttachment.Field.link] = '<URL>' + '/product2'
product2[AdCreativeLinkDataChildAttachment.Field.name] = 'Product 2'
product2[AdCreativeLinkDataChildAttachment.Field.description] = '$9.99'
product2[AdCreativeLinkDataChildAttachment.Field.image_hash] = '<IMAGE_HASH>'

product3 = AdCreativeLinkDataChildAttachment()
product3[AdCreativeLinkDataChildAttachment.Field.link] = '<URL>' + '/product3'
product3[AdCreativeLinkDataChildAttachment.Field.name] = 'Product 3'
product3[AdCreativeLinkDataChildAttachment.Field.description] = '$10.99'
product3[AdCreativeLinkDataChildAttachment.Field.image_hash] = '<IMAGE_HASH>'

link = AdCreativeLinkData()
link[link.Field.link] = '<URL>'
link[link.Field.child_attachments] = [product1, product2, product3]

story = AdCreativeObjectStorySpec()
story[story.Field.page_id] = <PAGE_ID>
story[story.Field.link_data] = link

creative = AdCreative(parent_id='act_<AD_ACCOUNT_ID>')
creative[AdCreative.Field.name] = 'MPA Creative'
creative[AdCreative.Field.object_story_spec] = story
creative.remote_create()
print(creative)
AdCreative adCreative = new AdAccount(act_<AD_ACCOUNT_ID>, context).createAdCreative()
  .setName("Sample Creative")
  .setObjectStorySpec(
    new AdCreativeObjectStorySpec()
      .setFieldLinkData(
        new AdCreativeLinkData()
          .setFieldCaption("My caption")
          .setFieldChildAttachments(Arrays.asList(
            new AdCreativeLinkDataChildAttachment()
              .setFieldDescription("$8.99")
              .setFieldImageHash(<IMAGE_HASH>)
              .setFieldLink("https://www.link.com/product1")
              .setFieldName("Product 1")
              .setFieldVideoId(<VIDEO_ID>)
          , 
            new AdCreativeLinkDataChildAttachment()
              .setFieldDescription("$9.99")
              .setFieldImageHash(<IMAGE_HASH>)
              .setFieldLink("https://www.link.com/product2")
              .setFieldName("Product 2")
              .setFieldVideoId(<VIDEO_ID>)
          , 
            new AdCreativeLinkDataChildAttachment()
              .setFieldDescription("$10.99")
              .setFieldImageHash(<IMAGE_HASH>)
              .setFieldLink("https://www.link.com/product3")
              .setFieldName("Product 3")
          ))
          .setFieldLink(<URL>)
      )
      .setFieldPageId(<PAGE_ID>)
  )
  .execute();
String ad_creative_id = adCreative.getId();
curl \
  -F 'name=Sample Creative' \
  -F 'object_story_spec={ 
    "link_data": { 
      "child_attachments": [ 
        { 
          "description": "$8.99", 
          "image_hash": "<IMAGE_HASH>", 
          "link": "https:\/\/www.link.com\/product1", 
          "name": "Product 1", 
          "video_id": "<VIDEO_ID>" 
        }, 
        { 
          "description": "$9.99", 
          "image_hash": "<IMAGE_HASH>", 
          "link": "https:\/\/www.link.com\/product2", 
          "name": "Product 2", 
          "video_id": "<VIDEO_ID>" 
        }, 
        { 
          "description": "$10.99", 
          "image_hash": "<IMAGE_HASH>", 
          "link": "https:\/\/www.link.com\/product3", 
          "name": "Product 3" 
        } 
      ], 
      "link": "<URL>" 
    }, 
    "page_id": "<PAGE_ID>" 
  }' \
  -F 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v2.11/act_<AD_ACCOUNT_ID>/adcreatives

Branded Content Posts

As a branded content sponsor, you can create ads with branded content posts where your brand is tagged. Create a campaign, ad set, as ads as your normally do. The only difference is in the ad creative. Note that your ad set targeting can not include instagram:

Set the field branded_content_sponsor_page_id in the ad creative. This represents the sponsor's page id. For example:

curl \
 -F 'access_token=<TOKEN>' \
 -F 'branded_content_sponsor_page_id=<PAGE_ID>' \
 -F 'object_story_id=<OBJECT_STORY_ID' \
https://graph.facebook.com/<VERSION>/<ACCOUNT_ID>/adcreatives

Where object_story_id is the post id in the format of: postOwnerID_postID.

Inline Page Post Creation

Most ad creatives rely on page posts for creative content. While you may create page posts separately then reference them by ID, it is easier to create them in the same call you use to provide ad creative. Specify the page post content with object_story_spec which creates an unpublished page post. See Inline Page Post, Blog.

You can get the new ID by retrieving object_story_id from the ad creative. To get post ids created with object_story_spec through /promotable_posts, pass include_inline=true in your HTTP GET. If include_inline value is false, we don't return any ids.

Get Related Objects

Many ad creatives require object_id for a relevant Facebook object, app ID, or page tab's URL. See Connection Objects for more information.

Get Page Posts

Use Graph API to get a Page's posts, see Pages. To get a list of Page's promotable posts provide a valid Page access_token or user access_token:

curl -G \\
-d "access_token=<ACCESS_TOKEN>" \\
"https://graph.facebook.com/<API_VERSION>/<PAGE_ID>/promotable_posts"

The response includes any existing page post IDs.

Examples

Create a link ad, not connected to a Page:

use FacebookAds\Object\AdCreative;
use FacebookAds\Object\Fields\AdCreativeFields;

$creative = new AdCreative(null, 'act_<AD_ACCOUNT_ID>');

$creative->setData(array(
  AdCreativeFields::NAME => 'Sample Creative',
  AdCreativeFields::TITLE => 'my title',
  AdCreativeFields::BODY => 'my body',
  AdCreativeFields::OBJECT_URL => 'https://www.link.com',
  AdCreativeFields::LINK_URL => 'https://www.link.com',
  AdCreativeFields::IMAGE_HASH => '<IMAGE_HASH>',
));

$creative->create();
from facebookads.adobjects.adcreative import AdCreative

creative = AdCreative(parent_id='act_<AD_ACCOUNT_ID>')
creative[AdCreative.Field.title] = 'my title'
creative[AdCreative.Field.body] = 'my body'
creative[AdCreative.Field.object_url] = 'https://www.link.com'
creative[AdCreative.Field.link_url] = 'https://www.link.com'
creative[AdCreative.Field.image_hash] = '<IMAGE_HASH>'

creative.remote_create()
AdCreative adCreative = new AdAccount(act_<AD_ACCOUNT_ID>, context).createAdCreative()
  .setName("Sample Creative")
  .setTitle("my title")
  .setBody("my body")
  .setObjectUrl("https://www.link.com")
  .setLinkUrl("https://www.link.com")
  .setImageHash(<IMAGE_HASH>)
  .execute();
String ad_creative_id = adCreative.getId();
curl \
  -F 'name=Sample Creative' \
  -F 'title=my title' \
  -F 'body=my body' \
  -F 'object_url=https://www.link.com' \
  -F 'link_url=https://www.link.com' \
  -F 'image_hash=<IMAGE_HASH>' \
  -F 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v2.11/act_<AD_ACCOUNT_ID>/adcreatives

Create a Video Page Like ad:

use FacebookAds\Object\AdCreative;
use FacebookAds\Object\AdCreativeVideoData;
use FacebookAds\Object\Fields\AdCreativeVideoDataFields;
use FacebookAds\Object\AdCreativeObjectStorySpec;
use FacebookAds\Object\Fields\AdCreativeObjectStorySpecFields;
use FacebookAds\Object\Fields\AdCreativeFields;
use FacebookAds\Object\Values\AdCreativeCallToActionTypeValues;

$video_data = new AdCreativeVideoData();
$video_data->setData(array(
  AdCreativeVideoDataFields::IMAGE_URL => '<THUMBNAIL_URL>',
  AdCreativeVideoDataFields::VIDEO_ID => <VIDEO_ID>,
  AdCreativeVideoDataFields::CALL_TO_ACTION => array(
    'type' => AdCreativeCallToActionTypeValues::LIKE_PAGE,
    'value' => array(
      'page' => <PAGE_ID>,
    ),
  ),
));

$object_story_spec = new AdCreativeObjectStorySpec();
$object_story_spec->setData(array(
  AdCreativeObjectStorySpecFields::PAGE_ID => <PAGE_ID>,
  AdCreativeObjectStorySpecFields::VIDEO_DATA => $video_data,
));

$creative = new AdCreative(null, 'act_<AD_ACCOUNT_ID>');

$creative->setData(array(
  AdCreativeFields::NAME => 'Sample Creative',
  AdCreativeFields::OBJECT_STORY_SPEC => $object_story_spec,
));

$creative->create();
from facebookads.adobjects.adcreative import AdCreative
from facebookads.adobjects.adcreativeobjectstoryspec \
    import AdCreativeObjectStorySpec
from facebookads.adobjects.adcreativevideodata \
    import AdCreativeVideoData

video_data = AdCreativeVideoData()
video_data[AdCreativeVideoData.Field.description] = 'My Description'
video_data[AdCreativeVideoData.Field.video_id] = <VIDEO_ID>
video_data[AdCreativeVideoData.Field.image_url] = '<IMAGE_URL>'
video_data[AdCreativeVideoData.Field.call_to_action] = {
    'type': 'LIKE_PAGE',
    'value': {
        'page': <PAGE_ID>,
    },
}

object_story_spec = AdCreativeObjectStorySpec()
object_story_spec[AdCreativeObjectStorySpec.Field.page_id] = <PAGE_ID>
object_story_spec[AdCreativeObjectStorySpec.Field.video_data] = video_data

creative = AdCreative(parent_id='act_<AD_ACCOUNT_ID>')
creative[AdCreative.Field.name] = 'Video Ad Creative'
creative[AdCreative.Field.object_story_spec] = object_story_spec
creative.remote_create()
AdCreative adCreative = new AdAccount(act_<AD_ACCOUNT_ID>, context).createAdCreative()
  .setName("Sample Creative")
  .setObjectStorySpec(
    new AdCreativeObjectStorySpec()
      .setFieldPageId(<PAGE_ID>)
      .setFieldVideoData(
        new AdCreativeVideoData()
          .setFieldCallToAction(
            new AdCreativeLinkDataCallToAction()
              .setFieldType(AdCreativeLinkDataCallToAction.EnumType.VALUE_LIKE_PAGE)
              .setFieldValue(
                new AdCreativeLinkDataCallToActionValue()
                  .setFieldPage(<PAGE_ID>)
              )
          )
          .setFieldImageUrl(<THUMBNAIL_URL>)
          .setFieldVideoId(<VIDEO_ID>)
      )
  )
  .execute();
String ad_creative_id = adCreative.getId();
curl \
  -F 'name=Sample Creative' \
  -F 'object_story_spec={ 
    "page_id": "<PAGE_ID>", 
    "video_data": { 
      "call_to_action": {"type":"LIKE_PAGE","value":{"page":"<PAGE_ID>"}}, 
      "image_url": "<THUMBNAIL_URL>", 
      "video_id": "<VIDEO_ID>" 
    } 
  }' \
  -F 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v2.11/act_<AD_ACCOUNT_ID>/adcreatives

Create an ad from an existing page post

use FacebookAds\Object\AdCreative;
use FacebookAds\Object\Fields\AdCreativeFields;

$creative = new AdCreative(null, 'act_<AD_ACCOUNT_ID>');

$creative->setData(array(
  AdCreativeFields::NAME => 'Sample Promoted Post',
  AdCreativeFields::OBJECT_STORY_ID => <POST_ID>,
));

$creative->create();
from facebookads.adobjects.adcreative import AdCreative

creative = AdCreative(parent_id='act_<AD_ACCOUNT_ID>')
creative[AdCreative.Field.object_story_id] = <POST_ID>
creative[AdCreative.Field.name] = 'AdCreative with post ID'

creative.remote_create()
print(creative)
AdCreative adCreative = new AdAccount(act_<AD_ACCOUNT_ID>, context).createAdCreative()
  .setName("Sample Promoted Post")
  .setObjectStoryId(object_story_id)
  .execute();
String ad_creative_id = adCreative.getId();
curl \
  -F 'name=Sample Promoted Post' \
  -F 'object_story_id=<POST_ID>' \
  -F 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v2.11/act_<AD_ACCOUNT_ID>/adcreatives

Create a Photo Ad with Branded Content from another page. This is available for photo, video, and link ads.

use FacebookAds\Object\AdCreative;
use FacebookAds\Object\AdCreativePhotoData;
use FacebookAds\Object\Fields\AdCreativePhotoDataFields;
use FacebookAds\Object\AdCreativeObjectStorySpec;
use FacebookAds\Object\Fields\AdCreativeObjectStorySpecFields;
use FacebookAds\Object\Fields\AdCreativeFields;

$photo_data = new AdCreativePhotoData();
$photo_data->setData(array(
  AdCreativePhotoDataFields::IMAGE_HASH => '<IMAGE_HASH>',
  AdCreativePhotoDataFields::BRANDED_CONTENT_SPONSOR_PAGE_ID =>
    <SPONSOR_PAGE_ID>,
));

$object_story_spec = new AdCreativeObjectStorySpec();
$object_story_spec->setData(array(
  AdCreativeObjectStorySpecFields::PAGE_ID => <PAGE_ID>,
  AdCreativeObjectStorySpecFields::PHOTO_DATA => $photo_data,
));

$creative = new AdCreative(null, 'act_<AD_ACCOUNT_ID>');

$creative->setData(array(
  AdCreativeFields::NAME => 'Sample Creative',
  AdCreativeFields::OBJECT_STORY_SPEC => $object_story_spec,
));

$creative->create();
from facebookads.adobjects.adcreative import AdCreative
from facebookads.adobjects.adcreativeobjectstoryspec \
    import AdCreativeObjectStorySpec
from facebookads.adobjects.adcreativephotodata \
    import AdCreativePhotoData

photo_data = AdCreativePhotoData()
photo_data[AdCreativePhotoData.Field.image_hash] = '<IMAGE_HASH>'
photo_data[AdCreativePhotoData.Field.branded_content_sponsor_page_id] = <SPONSOR_PAGE_ID>

object_story_spec = AdCreativeObjectStorySpec()
object_story_spec[AdCreativeObjectStorySpec.Field.page_id] = <PAGE_ID>
object_story_spec[AdCreativeObjectStorySpec.Field.photo_data] = photo_data

creative = AdCreative(parent_id='act_<AD_ACCOUNT_ID>')
creative[AdCreative.Field.name] = 'AdCreative for Branded Content Sponsor Ad'
creative[AdCreative.Field.object_story_spec] = object_story_spec
creative.remote_create()

print(creative)
AdCreative adCreative = new AdAccount(act_<AD_ACCOUNT_ID>, context).createAdCreative()
  .setName("Sample Creative")
  .setObjectStorySpec(
    new AdCreativeObjectStorySpec()
      .setFieldPageId(<PAGE_ID>)
      .setFieldPhotoData(
        new AdCreativePhotoData()
          .setFieldBrandedContentSponsorPageId(<SPONSOR_PAGE_ID>)
          .setFieldCaption("My caption")
          .setFieldImageHash(<IMAGE_HASH>)
      )
  )
  .execute();
String ad_creative_id = adCreative.getId();
curl \
  -F 'name=Sample Creative' \
  -F 'object_story_spec={ 
    "page_id": "<PAGE_ID>", 
    "photo_data": { 
      "branded_content_sponsor_page_id": "<SPONSOR_PAGE_ID>", 
      "image_hash": "<IMAGE_HASH>" 
    } 
  }' \
  -F 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v2.11/act_<AD_ACCOUNT_ID>/adcreatives

Adding url_tags to an ad

use FacebookAds\Object\AdCreative;
use FacebookAds\Object\Fields\AdCreativeFields;

$creative = new AdCreative(null, 'act_<AD_ACCOUNT_ID>');

$creative->setData(array(
  AdCreativeFields::OBJECT_STORY_ID => <POST_ID>,
  AdCreativeFields::URL_TAGS => 'key1=val1&key2=val2',
));

$creative->create();
from facebookads.adobjects.adcreative import AdCreative

creative = AdCreative(parent_id='act_<AD_ACCOUNT_ID>')
creative[AdCreative.Field.object_story_id] = <POST_ID>
creative[AdCreative.Field.name] = 'Ad Creative with URL tag'
creative[AdCreative.Field.url_tags] = 'key1=val1&key2=val2'

creative.remote_create()
print(creative)
AdCreative adCreative = new AdAccount(act_<AD_ACCOUNT_ID>, context).createAdCreative()
  .setObjectStoryId(object_story_id)
  .setUrlTags("key1=val1&key2=val2")
  .execute();
String ad_creative_id = adCreative.getId();
curl \
  -F 'object_story_id=<POST_ID>' \
  -F 'url_tags=key1=val1&key2=val2' \
  -F 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v2.11/act_<AD_ACCOUNT_ID>/adcreatives

You can't perform this operation on this endpoint.

Updating

Examples

use FacebookAds\Object\AdCreative;
use FacebookAds\Object\Fields\AdCreativeFields;

$creative = new AdCreative(<CREATIVE_ID>);

$creative->setData(array(
  AdCreativeFields::NAME => 'New creative name ' . date('U'),
));

$creative->update();
from facebookads.adobjects.adcreative import AdCreative

creative = AdCreative(<CREATIVE_ID>)
creative[AdCreative.Field.name] = <CREATIVE_NAME>

creative.remote_update()
print(creative)
new AdCreative(<CREATIVE_ID>, context).update()
  .setName("Updated creative name")
  .execute();
curl \
  -F 'name=New creative name 1517287550' \
  -F 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v2.11/<CREATIVE_ID>

You can update an AdCreative by making a POST request to /{ad_creative_id}.

Parameters

ParameterDescription
account_id
numeric string

Ad account ID for the account this ad creative belongs to.

adlabels
list<Object>

Ad Labels associated with this creative. Used to group it with related ad objects.

name
string

The name of the creative in the creative library.

status
enum {ACTIVE, IN_PROCESS, WITH_ISSUES, DELETED}

The status of this ad creative. See Storing and Retrieving Ad Objects.

Return Type

This endpoint supports read-after-write and will read the node to which you POSTed.
Struct {
success: bool,
}

Validation Rules

ErrorDescription
200Permissions error
100Invalid parameter
294Managing advertisements requires an access token with the extended permission for ads_management

Deleting

Examples

use FacebookAds\Object\AdCreative;

$creative = new AdCreative(<CREATIVE_ID>);
$creative->deleteSelf();
from facebookads.adobjects.adcreative import AdCreative

creative = AdCreative(<CREATIVE_ID>)
creative.remote_delete()
curl -X DELETE \
  -d 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v2.11/<CREATIVE_ID>/

You can delete an AdCreative by making a DELETE request to /{ad_creative_id}.

Parameters

ParameterDescription
account_id
numeric string

Ad account ID for the account this ad creative belongs to.

adlabels
list<Object>

Ad Labels associated with this creative. Used to group it with related ad objects.

name
string

Name of this ad creative as seen in the ad account's library.

status
enum {ACTIVE, IN_PROCESS, WITH_ISSUES, DELETED}

The status of this ad creative. See Storing and Retrieving Ad Objects.

Return Type

Struct {
success: bool,
}

Validation Rules

ErrorDescription
200Permissions error
100Invalid parameter