Marketing API Version

Ad Creative

To see the types of ad creatives available, it's best to check the ads product guide for the most up to date information. The product guide also contains information on size requirements for each ad unit.

Limits

The ad creative API will only return 50k ad creatives, pagination past 50k is unavailable.

Limits on Fields in an Ad Creative

LimitValue

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 the title or body

30 characters (recommended)

Title and Body Parameters

Rules for title and body parameters:

  • Should be between minimum and maximum title and body lengths noted above.
  • Cannot start with punctuation (\ / ! . ? - * ( ) , ; :)
  • Cannot have consecutive punctuation characters with the exception of 3 periods...
  • Words cannot be greater than 30 characters in length
  • Only three 1-character words are allowed
  • Cannot consist entirely of capital letters

The following characters are not allowed:

  • IPA Symbols (exception: ə, ɚ, ɛ, ɜ, ɝ, ɞ, ɟ)
  • Diacritical Marks (precomposed version of a character + diacritical mark are allowed, standalone diacritical marks are not allowed)
  • Superscript and Subscript characters with the exception of ™ and ℠
  • The following characters ^~_={}[]|<>

Exceptions

  • Link Ads cannot use special characters and will throw an error if an invalid special character is used.
  • For Page Posts Ads the use of special characters (characters like ) is allowed.

Guidelines

For general guidelines on Facebook advertising see here

Placement

Please check the validation documentation for restrictions on placement of your ad depending on the 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.

If you want to learn how to use the Graph API, read our Using Graph API guide.

Parameters

NameDescription
thumbnail_height
unsigned int32
Default value: 64

Height of thumbnails accessible in thumbnail_url

thumbnail_width
unsigned int32
Default value: 64

Width of thumbnails accessible in thumbnail_url

Fields

FieldDescription

id

numeric string

The ID of this creative

actor_id

numeric string

The actor ID (Page ID) of this creative. This field is available only for mobile app ads created before 2015

actor_image_hash

string

The image used for actor's icon. This field is available only for mobile app ads created before 2015

actor_image_url

string

The URL of the icon for the actor (Page ID) of this creative. This field is only available for mobile app ads created before 2015

actor_name

string

The title text used for actor. This field is available only for mobile app ads created before 2015

adlabels

Ad Labels that are associated with this creative

applink_treatment

enum {deeplink_with_web_fallback, deeplink_with_appstore_fallback, web_only}

Deep link fallback behavior for dynamic product ads if the app is not installed.

body

string

The body of the ad

call_to_action_type

enum {OPEN_LINK, LIKE_PAGE, SHOP_NOW, PLAY_GAME, INSTALL_APP, USE_APP, INSTALL_MOBILE_APP, USE_MOBILE_APP, BOOK_TRAVEL, LISTEN_MUSIC, WATCH_VIDEO, LEARN_MORE, SIGN_UP, DOWNLOAD, WATCH_MORE, NO_BUTTON, CALL_NOW, BUY_NOW, GET_OFFER, GET_OFFER_VIEW, GET_DIRECTIONS, MESSAGE_PAGE, SUBSCRIBE, SELL_NOW, DONATE_NOW, GET_QUOTE, CONTACT_US, RECORD_NOW, VOTE_NOW, REGISTER_NOW, OPEN_MOVIES}

The call to action button text and header text of legacy ads.

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.

image_crops

AdsImageCrops

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

image_hash

string

Image hash for an image you can use in creatives. See image library for more details

image_url

string

A URL for the image for this creative. The image specified at this URL will be saved into the ad account's image library

instagram_actor_id

numeric string

Instagram actor ID

instagram_permalink_url

string

Instagram permalink

instagram_story_id

numeric string

The ID of an Instagram post to use in an ad.

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

Used to identify a specific landing tab on the Page (e.g. a Page tab app) by the Page tab's URL. See connection objects for retrieving Page tabs' URLs. The likes tab is not supported.
app_data parameters may be added to the url to pass data to a tab app

name

string

The name of the creative in the creative library. Ad Creative names should be unique.

object_id

numeric string

The ID of the promoted_object or object that is relevant to the ad and ad type

object_story_id

token with structure: Post ID

The ID of a page post to use in an ad. This ID can be retrieved by using the graph API to query the posts of the page. If an image is used in the post, it will be downloaded and available in your account's image library. If an unpublished page post was used to create the ad, this ID will be null, but 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

AdCreativeObjectStorySpec

The page id and the content to create a new unpublished page post specified using one of link_data, photo_data, video_data, offer_data, text_data or template_data

object_type

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

The type of object that is being advertised. Allowed values are:
PAGE
DOMAIN
EVENT
STORE_ITEM: refers to an iTunes or Google Play store destination
OFFER
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

Destination URL for a link ads not connected to a page

platform_customizations

AdCreativePlatformCustomization

Use this field to customize the media for different Facebook placements. Currently you can use this field for customizing images only. The media specified here replaces the original media defined in the ad creative when the ad displays on those placements. For example, if you define a media here for the instagram key, Facebook uses that media instead of the media defined in the ad creative when showing the ad on Instagram.

product_set_id

numeric string

The ID of the product set for this creative. See dynamic product ads for more detail

run_status

enum {ACTIVE, DELETED}

The run status of this creative. Allowed values are:
ACTIVE
DELETED

template_url

string

The Tracking URL for dynamic product ads. See dynamic product ads for more detail

thumbnail_url

string

The URL to a thumbnail for this creative. You can optionally request dimensions of this thumbnail by providing the thumbnail_width and thumbnail_height parameters. See example for more detail

title

string

Title for a link ad (not connected 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

Edges

EdgeDescription

previews

The HTML Snippets for previewing this creative

Validation Rules

ErrorDescription
100Invalid parameter
275Cannot determine the target object for this request. Currently supported objects include ad account, business account and associated objects.
274The ad account is not enabled for usage in Ads API. Please add it in developers.facebook.com/apps -> select your app -> settings -> advanced -> advertising accounts -> Ads API
278Reading advertisements requires an access token with the extended permission ads_read
272This Ads API call requires the user to be admin of the application

Creating

Ad creatives can be created as part of an ad group or individually on their own. In either case the ad creative is then stored in the creative library of the account for use in other ad groups. The creative library provides a single location for managing ad creatives and using them in ads.

If you add an ad creative that isn't unique, a new ad creative is not generated and the creative ID of the existing ad creative is returned.

Inline Page Post Creation

Most ad creatives rely on page posts as the means for specifying the creative content. While it's possible to create those page posts separately then reference them by ID, it is more convenient to create them inline in the same API call as creating the ad creative. You can do this by specifying the page post content using the object_story_spec which will create an unpublished page post.

The ID of the new unpublished page post can then be retrieved by retrieving the object_story_id field of the ad creative.

In order to retrive posts created through object_story_spec through /promotable_posts endpoint, it's required to pass the is_inline=true parameter in the HTTP GET request. If is_inline value is false, posts created this way won't be returned.

Obtaining Objects

Many ad creatives require an object_id of a relevant Facebook object, app ID, or URL of a Page tab. You can obtain a list of object IDs using the Graph API with

https://graph.facebook.com/<API_VERSION>/act_<AD_ACCOUNT_ID>/connectionobjects

which returns the objects for the session user. Learn more about connection objects here

Obtaining Page Posts

You can use the Graph API for obtaining posts of a Page (see Pages):

To retrieve a list of Page's promotable posts call

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

with any valid Page access_token or user access_token.

The response is the ID of the page post.

Examples

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::CAPTION => 'My caption',
  AdCreativeLinkDataFields::CALL_TO_ACTION => array(
    'type' => AdCreativeCallToActionTypeValues::SIGN_UP,
    'value' => array(
      'link' => '<URL>',
      'link_caption' => 'Sign up!',
    ),
  ),
));

$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_caption': 'Sign up!',
    }
}

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_caption":"Sign up!"}}, 
      "caption": "My caption", 
      "link": "<URL>", 
      "message": "try it out" 
    }, 
    "page_id": "<PAGE_ID>" 
  }' \
  -F 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v2.7/act_<AD_ACCOUNT_ID>/adcreatives

In the above example you will see the use of link_caption while passing the call to action object. This parameter allows you to customize the call to action caption. If you also wish to customize the call to action description, you can do so by passing the parameter 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::CAPTION => 'My caption',
  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]
link[link.Field.caption] = 'My caption'

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": { 
      "caption": "My caption", 
      "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.7/act_<AD_ACCOUNT_ID>/adcreatives

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::CAPTION => 'My caption',
  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.caption] = 'My caption'
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": { 
      "caption": "My caption", 
      "image_hash": "<IMAGE_HASH>", 
      "link": "<URL>", 
      "message": "try it out" 
    }, 
    "page_id": "<PAGE_ID>" 
  }' \
  -F 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v2.7/act_<AD_ACCOUNT_ID>/adcreatives

In the above example you could replace the picture field with image_hash to specify an image from your ad account's image library. You can also optionally specify how the image is to be cropped using the image_crops field of the link_data object. See Image Crop for more information.

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.7/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::DESCRIPTION => 'try it out',
  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>)
              )
          )
          .setFieldDescription("try it out")
          .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>"}}, 
      "description": "try it out", 
      "image_url": "<THUMBNAIL_URL>", 
      "video_id": "<VIDEO_ID>" 
    } 
  }' \
  -F 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v2.7/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.7/act_<AD_ACCOUNT_ID>/adcreatives

Create a Photo Ad with utilizing branded content from another page. Branded content 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::CAPTION => 'My caption',
  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.caption] = 'My caption'
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>", 
      "caption": "My caption", 
      "image_hash": "<IMAGE_HASH>" 
    } 
  }' \
  -F 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v2.7/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.7/act_<AD_ACCOUNT_ID>/adcreatives
You can make a POST request to adcreatives edge from the following paths:
When posting to this edge, an AdCreative will be created.

Parameters

NameDescription
action_spec
list<unsigned int32>

Action spec

Deprecated
actor_id
unsigned int32

The Facebook object ID that is the actor for a link ad (not connected to a Page)

actor_image_hash
string

The image used for actor's icon.

Deprecated
actor_image_url
URL

The URL of the icon for the actor (Page ID) of this creative.

Deprecated
actor_name
string

The title text used for actor.

Deprecated
adlabels
list<Object>

Labels to be associated with this creative

applink_treatment
enum{deeplink_with_web_fallback, deeplink_with_appstore_fallback, web_only}

Deep link fallback behavior for dynamic product ads if the app is not installed.

body
string

The body of the ad

Supports Emoji
call_to_action
Object

A call to action button required when passing instagram_story_id.

Supports Emoji
type
enum{SHOP_NOW, BOOK_TRAVEL, LEARN_MORE, SIGN_UP, DOWNLOAD, GET_DIRECTIONS, LIKE_PAGE, DONATE_NOW, CONTACT_US, MESSAGE_PAGE, SAVE, INSTALL_MOBILE_APP, USE_MOBILE_APP, INSTALL_APP, USE_APP, PLAY_GAME, WATCH_VIDEO, WATCH_MORE, OPEN_LINK, NO_BUTTON, LISTEN_MUSIC, MOBILE_DOWNLOAD, GET_OFFER, GET_OFFER_VIEW, BUY_NOW, BUY_TICKETS, UPDATE_APP, BET_NOW, ADD_TO_CART, ORDER_NOW, SELL_NOW, CALL, MISSED_CALL, CALL_NOW, CALL_ME, APPLY_NOW, BUY, GET_QUOTE, SUBSCRIBE, RECORD_NOW, VIDEO_ANNOTATION, VOTE_NOW, GIVE_FREE_RIDES, REGISTER_NOW, OPEN_MESSENGER_EXT, EVENT_RSVP, CIVIC_ACTION, SEND_INVITES}

The type of the action. Not all types can be used for all ads. Check Ads Product Guide to see which type can be used for based on the objective of your campaign.

Required
value
Object
Default value: Array

JSON containing the call to action data.

Supports Emoji
link
URL
app_link
string
page
string
link_format
enum {VIDEO_LEAD, VIDEO_LPP, VIDEO_NEKO, VIDEO_NON_LINK, VIDEO_SHOP}
application
numeric string or integer
link_title
string
Supports Emoji
link_description
string
product_link
string
get_movie_showtimes
boolean
sponsorship
Object
link
URL
image
URL
video_annotation
Object
annotations
list<Object>
start_time_in_sec
unsigned int32
end_time_in_sec
unsigned int32
link
URL
link_title
string
link_description
string
link_caption
string
image_url
URL
header_color
string
logo_url
URL
post_click_cta_title
string
post_click_description_title
string
leadgen
Object
info_fields
list<Object>
policy_url
URL
fallback_test_url
URL
follow_up_title
string
follow_up_action_url
URL
follow_up_action_text
string
tcpa_compliant
boolean
need_split_flow
boolean
split_flow_use_post
boolean
landing_page_cta
string
offer_id
numeric string or integer
offer_view_id
numeric string or integer
advanced_data
Object
offer_id
numeric string or integer
app_destination
enum {MESSENGER, MESSENGER_EXTENSIONS}
is_canvas_video_transition_enabled
boolean
link_caption
string
follow_redirect
boolean

When adding social context to a link ad (not connected to a Page), providing this parameter indicates that Facebook should follow any HTTP redirects encountered at the link_url in order to find the Facebook object to apply social context from.

image_crops
dictionary

Crop dimensions for the image specified. See image crop reference for more details.

image_file
string

Reference to a local image file to upload for use in a creative. Not to exceed 8MB in size. One of these three fields should be specified: image_file, image_hash, and image_url.

image_hash
string

Image hash for an image you have uploaded and can be used in a creative. One of these three fields should be specified: image_file, image_hash, or image_url.

image_url
URL

A URL for the image for this creative. You should not use image URLs returned from the FB CDN but instead have the image hosted on your own servers. The image specified at the URL will be saved into the ad account's image library and cannot exceed 8 MB in size. One of these three fields should be specified: image_file, image_hash, or image_url.

instagram_actor_id
numeric string or integer

Instagram account ID

instagram_permalink_url
URL

Instagram post URL

instagram_story_id
unsigned int32

Instagram story ID

link_og_id
string

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

link_url
URL

Used to identify a specific landing tab on the Page (e.g. a Page tab app) by the Page tab's URL. See connection objects for retrieving Page tabs' URLs. app_data parameters may be added to the url to pass data to a tab app.

name
string

The name of the creative in the creative library. Must be unique

object_id
unsigned int32

The Facebook object ID that is relevant to the ad. See connection objects

object_instagram_id
unsigned int32

Instagram post ID

object_story_id
post_id

The ID of a page post to use in an ad. This ID can be retrieved by using the graph API to query the posts of the page. If an image, not exceeding 8 MB in size, is used in the post, it will be downloaded and available in your account's image library.

object_story_spec
string (ObjectStorySpec)

JSON string of AdCreativeObjectStorySpec type. The page id and the content to create a new unpublished page post specified using one of link_data, photo_data, video_data, offer_data, text_data or template_data.

Supports Emoji
object_type
string

The type of object that is being advertised. Allowed values are:
PAGE
DOMAIN
EVENT
STORE_ITEM: refers to an iTunes or Google Play store destination
OFFER
SHARE: from a page
PHOTO
STATUS: of a page
VIDEO
APPLICATION: app on Facebook

object_url
URL

Destination URL for a link ad (not connected to a page)

platform_customizations
JSON or object-like arrays

Use this field to specify the media to use on different Facebook placements. You can currently use this setting for images only. The media specified here replaces the media originally defined in the ad creative when the ad displayeds in those placements. For example, if you define a media here for the instagram key, Facebook uses that media instead of the media defined in the ad creative when showing the ad on Instagram.

instagram
JSON or object-like arrays

Specify the media to display in an Instagram ad. This displays instead of the media defined in the ad creative.

image_url
URL

The URL of the image used for the platform specific media. Either this field or image_hash is required.

image_hash
string

The ad image used for the platform specific media. Either this field or image_url is required.

image_crops
dictionary

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

product_set_id
numeric string or integer

The Dynamic Product Ad's product set ID

template_url
URL

The product link url, which overrides the one set in Dynamic Product Ad's product feeds.

thumbnail_url
URL

The URL to a thumbnail for this creative. You can optionally request dimensions of this thumbnail by providing the thumbnail_width and thumbnail_height parameters. See example for more detail

title
string

Title for a link ad (not connected 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.

video_id
unsigned int32

Video ID

Deprecated

Return Type

Struct {
id: numeric string,
}

Validation Rules

ErrorDescription
100Invalid parameter
274The ad account is not enabled for usage in Ads API. Please add it in developers.facebook.com/apps -> select your app -> settings -> advanced -> advertising accounts -> Ads API

Updating

Examples

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

$creative = new AdCreative(<CREATIVE_ID>);

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

$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' \
  -F 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v2.7/<CREATIVE_ID>
You can update an AdCreative by making a POST request to /{ad_creative_id}.

Parameters

NameDescription
account_id
numeric string

Account ID

adlabels
list<Object>

Labels to be associated with this creative

name
string

The name of the creative in the creative library. Must be unique

run_status
unsigned int32

Status of creative. Allowed values:
ACTIVE, DELETED

Return Type

Struct {
success: bool,
}
You may perform a POST request to the following edge from this node:

Validation Rules

ErrorDescription
100Invalid parameter
274The ad account is not enabled for usage in Ads API. Please add it in developers.facebook.com/apps -> select your app -> settings -> advanced -> advertising accounts -> Ads API

Deleting

Examples

use FacebookAds\Object\AdCreative;

$creative = new AdCreative(<CREATIVE_ID>);
$creative->delete();
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.7/<CREATIVE_ID>
You can delete an AdCreative by making a DELETE request to /{ad_creative_id}.

Parameters

NameDescription
account_id
numeric string

Account ID

adlabels
list<Object>

Labels to be associated with this creative

name
string

The name of the creative in the creative library. Must be unique

run_status
unsigned int32

Status of creative. Allowed values:
ACTIVE, DELETED

Return Type

Struct {
success: bool,
}
You may perform a DELETE request to the following edge from this node:

Validation Rules

ErrorDescription
100Invalid parameter