Graph API Version

Ad Account Ad Creatives

Contains creative content for an ad account that you can use in your ads. Includes images, videos and so on. Using an ad account creative for a particular ad is subject to validation rules based on the ad type and other rules. See Facebook Ads Guide and Validation, Objectives and Creative.

To retrieve an account's ad creatives, make an HTTP GET call to

use FacebookAds\Object\AdAccount;
use FacebookAds\Object\Fields\AdCreativeFields;

$account = new AdAccount('act_<AD_ACCOUNT_ID>');
$adcreatives = $account->getAdCreatives(array(
  AdCreativeFields::NAME,
));
from facebookads.adobjects.adaccount import AdAccount
from facebookads.adobjects.adcreative import AdCreative

ad_account = AdAccount('act_<AD_ACCOUNT_ID>')
ad_account.get_ad_creatives(fields=[AdCreative.Field.object_story_id])
APINodeList<AdCreative> adCreatives = new AdAccount(act_<AD_ACCOUNT_ID>, context).getAdCreatives()
  .requestNameField()
  .execute();
ad_account = FacebookAds::AdAccount.get('act_<AD_ACCOUNT_ID>')
creatives = ad_account.adcreatives
curl -G \
  -d 'fields=name' \
  -d 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v2.11/act_<AD_ACCOUNT_ID>/adcreatives

Reading

The Ad Creatives that belong to this Ad Account.

Example

Graph API Explorer
GET /v4.0/act_<AD_ACCOUNT_ID>/adcreatives?fields=name 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(
    '/act_<AD_ACCOUNT_ID>/adcreatives',
    '{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(
    "/act_<AD_ACCOUNT_ID>/adcreatives",
    {
        "fields": "name"
    },
    function (response) {
      if (response && !response.error) {
        /* handle the result */
      }
    }
);
Bundle params = new Bundle();
params.putString("fields", "name");
/* make the API call */
new GraphRequest(
    AccessToken.getCurrentAccessToken(),
    "/act_<AD_ACCOUNT_ID>/adcreatives",
    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": @"name",
};
/* make the API call */
FBSDKGraphRequest *request = [[FBSDKGraphRequest alloc]
                               initWithGraphPath:@"/act_<AD_ACCOUNT_ID>/adcreatives"
                                      parameters:params
                                      HTTPMethod:@"GET"];
[request startWithCompletionHandler:^(FBSDKGraphRequestConnection *connection,
                                      id result,
                                      NSError *error) {
    // Handle the result
}];
curl https://graph.facebook.com/v4.0/act_<AD_ACCOUNT_ID>/adcreatives?fields=name
If you want to learn how to use the Graph API, read our Using Graph API guide.

Parameters

This endpoint doesn't have any parameters.

Fields

Reading from this edge will return a JSON formatted result:

{ "data": [], "paging": {}, "summary": {} }

data

A list of AdCreative nodes.

paging

For more details about pagination, see the Graph API guide.

summary

Aggregated information about the edge, such as counts. Specify the fields to fetch in the summary param (like summary=total_count).

FieldDescription
total_count
unsigned int32

Total number of creatives in the ad account.

Validation Rules

ErrorDescription
100Invalid parameter
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.
200Permissions error
2500Error parsing graph query

Creating

When creating ad creatives, if the obect_story_id being used is already in use by an existing creative, then the API will return the value of the existing creative_id instead of creating a new one.

You can make a POST request to adcreatives edge from the following paths:
When posting to this edge, no Graph object will be created.

Example

Graph API Explorer
POST /v4.0/act_<AD_ACCOUNT_ID>/adcreatives HTTP/1.1
Host: graph.facebook.com

name=Sample+Promoted+Post&object_story_id=%3CPAGE_ID%3E_%3CPOST_ID%3E
/* PHP SDK v5.0.0 */
/* make the API call */
try {
  // Returns a `Facebook\FacebookResponse` object
  $response = $fb->post(
    '/act_<AD_ACCOUNT_ID>/adcreatives',
    array (
      'name' => 'Sample Promoted Post',
      'object_story_id' => '<PAGE_ID>_<POST_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(
    "/act_<AD_ACCOUNT_ID>/adcreatives",
    "POST",
    {
        "name": "Sample Promoted Post",
        "object_story_id": "<PAGE_ID>_<POST_ID>"
    },
    function (response) {
      if (response && !response.error) {
        /* handle the result */
      }
    }
);
Bundle params = new Bundle();
params.putString("name", "Sample Promoted Post");
params.putString("object_story_id", "<PAGE_ID>_<POST_ID>");
/* make the API call */
new GraphRequest(
    AccessToken.getCurrentAccessToken(),
    "/act_<AD_ACCOUNT_ID>/adcreatives",
    params,
    HttpMethod.POST,
    new GraphRequest.Callback() {
        public void onCompleted(GraphResponse response) {
            /* handle the result */
        }
    }
).executeAsync();
// For more complex open graph stories, use `FBSDKShareAPI`
// with `FBSDKShareOpenGraphContent`
NSDictionary *params = @{
  @"name": @"Sample Promoted Post",
  @"object_story_id": @"<PAGE_ID>_<POST_ID>",
};
/* make the API call */
FBSDKGraphRequest *request = [[FBSDKGraphRequest alloc]
                               initWithGraphPath:@"/act_<AD_ACCOUNT_ID>/adcreatives"
                                      parameters:params
                                      HTTPMethod:@"POST"];
[request startWithCompletionHandler:^(FBSDKGraphRequestConnection *connection,
                                      id result,
                                      NSError *error) {
    // Handle the result
}];
curl -X POST \
     -d "name=Sample+Promoted+Post" \
     -d "object_story_id=%3CPAGE_ID%3E_%3CPOST_ID%3E" \
        https://graph.facebook.com/v4.0/act_<AD_ACCOUNT_ID>/adcreatives
If you want to learn how to use the Graph API, read our Using Graph API guide.

Parameters

ParameterDescription
actor_id
int64

The actor ID (Page ID) of this creative.

adlabels
list<Object>

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
Object

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.

Supports Emoji
images
list<Object>

hash
string

url
URL

image_crops
dictionary { enum{191x100, 100x72, 400x150, 600x360, 100x100, 400x500, 90x160} : <list<list<int64>>> }

url_tags
string

adlabels
list<Object>

tag
string

videos
list<Object>

video_id
int64

thumbnail_url
URL

thumbnail_hash
string

caption_ids
list<numeric string>

url_tags
string

adlabels
list<Object>

do_not_clone_flag
boolean

tag
string

thumbnail_source
string

bodies
list<Object>

text
string

Supports Emoji
url_tags
string

adlabels
list<Object>

call_to_action_types
list<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}>

descriptions
list<Object>

text
string

Supports Emoji
url_tags
string

adlabels
list<Object>

link_urls
list<Object>

website_url
URL

display_url
string

deeplink_url
string

carousel_see_more_url
URL

url_tags
string

adlabels
list<Object>

titles
list<Object>

text
string

Supports Emoji
url_tags
string

adlabels
list<Object>

captions
list<Object>

text
string

url_tags
string

adlabels
list<Object>

ad_formats
list<enum {AUTOMATIC_FORMAT, CAROUSEL, CAROUSEL_IMAGE, CAROUSEL_VIDEO, COLLECTION, SINGLE_IMAGE, SINGLE_VIDEO}>

groups
list<JSON or object-like arrays>

image_label
Object

video_label
Object

body_label
Object

description_label
Object

link_url_label
Object

title_label
Object

caption_label
Object

target_rules
list<JSON or object-like arrays>

targeting
JSON or object-like arrays

age_min
int64

age_max
int64

audience_network_positions
list<enum{classic, rewarded_video, instream_video}>

device_platforms
list<enum{desktop, mobile}>

facebook_positions
list<enum{feed, instant_article, instream_video, marketplace, right_hand_column, story, suggested_video, video_feeds}>

instagram_positions
list<enum{stream, story}>

messenger_positions
list<enum{messenger_home, story}>

genders
list<int64>

publisher_platforms
list<enum{facebook, instagram, audience_network, messenger, whatsapp}>

interests
list<JSON or object-like arrays>

id
int64

name
string

behaviors
list<JSON or object-like arrays>

id
int64

name
string

customization_spec
JSON or object-like arrays

age_min
int64

age_max
int64

audience_network_positions
list<enum{classic, rewarded_video, instream_video}>

device_platforms
list<enum{desktop, mobile}>

facebook_positions
list<enum{feed, instant_article, instream_video, marketplace, right_hand_column, story, suggested_video, video_feeds}>

instagram_positions
list<enum{stream, story}>

genders
list<int64>

publisher_platforms
list<enum{facebook, instagram, audience_network, messenger, whatsapp}>

interests
list<JSON or object-like arrays>

id
int64

name
string

behaviors
list<JSON or object-like arrays>

id
int64

name
string

locales
array<int64>

geo_locations
JSON object

image_label
Object

video_label
Object

body_label
Object

description_label
Object

link_url_label
Object

title_label
Object

caption_label
Object

call_to_action_label
Object

priority
int64

is_default
boolean

asset_customization_rules
list<JSON or object-like arrays>

targeting
JSON or object-like arrays

age_min
int64

age_max
int64

audience_network_positions
list<enum{classic, rewarded_video, instream_video}>

device_platforms
list<enum{desktop, mobile}>

facebook_positions
list<enum{feed, instant_article, instream_video, marketplace, right_hand_column, story, suggested_video, video_feeds}>

instagram_positions
list<enum{stream, story}>

messenger_positions
list<enum{messenger_home, story}>

genders
list<int64>

publisher_platforms
list<enum{facebook, instagram, audience_network, messenger, whatsapp}>

interests
list<JSON or object-like arrays>

id
int64

name
string

behaviors
list<JSON or object-like arrays>

id
int64

name
string

customization_spec
JSON or object-like arrays

age_min
int64

age_max
int64

audience_network_positions
list<enum{classic, rewarded_video, instream_video}>

device_platforms
list<enum{desktop, mobile}>

facebook_positions
list<enum{feed, instant_article, instream_video, marketplace, right_hand_column, story, suggested_video, video_feeds}>

instagram_positions
list<enum{stream, story}>

genders
list<int64>

publisher_platforms
list<enum{facebook, instagram, audience_network, messenger, whatsapp}>

interests
list<JSON or object-like arrays>

id
int64

name
string

behaviors
list<JSON or object-like arrays>

id
int64

name
string

locales
array<int64>

geo_locations
JSON object

image_label
Object

video_label
Object

body_label
Object

description_label
Object

link_url_label
Object

title_label
Object

caption_label
Object

call_to_action_label
Object

priority
int64

is_default
boolean

optimization_type
enum{REGULAR, LANGUAGE, PLACEMENT, VIDEO_BANDWIDTH, BRAND, ASSET_CUSTOMIZATION, DCO_PARITY, PREVIEW_DYNAMIC_RENDERING, LOCALIZED_PLACEMENTS, DEGREES_OF_FREEDOM, FORMAT_AUTOMATION}

call_to_actions
list<Object>

type
enum{BOOK_TRAVEL, CONTACT_US, DONATE, DONATE_NOW, DOWNLOAD, GET_DIRECTIONS, GO_LIVE, INTERESTED, LEARN_MORE, LIKE_PAGE, MESSAGE_PAGE, SAVE, SEND_TIP, SHOP_NOW, SIGN_UP, VIEW_INSTAGRAM_PROFILE, INSTAGRAM_MESSAGE, LOYALTY_LEARN_MORE, GET_MOBILE_APP, 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, GET_SHOWTIMES, LISTEN_NOW, GET_EVENT_TICKETS, SEARCH_MORE, PRE_REGISTER, BOOK_TEST_DRIVE, CHECK_AVAILABILITY, CALL, MISSED_CALL, CALL_NOW, CALL_ME, APPLY_NOW, BUY, GET_QUOTE, SUBSCRIBE, RECORD_NOW, VOTE_NOW, GIVE_FREE_RIDES, REGISTER_NOW, OPEN_MESSENGER_EXT, EVENT_RSVP, CIVIC_ACTION, SEND_INVITES, REQUEST_TIME, SEE_MENU, WHATSAPP_MESSAGE, SEARCH, TRY_IT, TRY_ON, LINK_CARD, DIAL_CODE, FIND_YOUR_GROUPS}

Required
value
Object

Supports Emoji
link
URL

app_link
string

page
numeric string or integer

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

Supports Emoji
link_caption
string

product_link
string

get_movie_showtimes
boolean

sponsorship
Object

link
URL

image
URL

video_annotation
Object

annotations
list<Object>

start_time_in_sec
int64

end_time_in_sec
int64

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

offer_id
numeric string or integer

offer_view_id
numeric string or integer

advanced_data
Object

offer_id
numeric string or integer

lead_gen_form_id
numeric string or integer

fundraiser_campaign_id
numeric string or integer

event_id
numeric string or integer

event_tour_id
numeric string or integer

app_destination
enum {MESSENGER, MESSENGER_EXTENSIONS, MESSENGER_GAMES, LINK_CARD, MARKETPLACE}

app_destination_page_id
numeric string or integer

is_canvas_video_transition_enabled
boolean

whatsapp_number
string

preinput_text
string

customized_message_page_cta_text
string

external_offer_provider_id
numeric string or integer

adlabels
list<Object>

autotranslate
array<string>

additional_data
JSON object

authorization_category
enum{NONE, POLITICAL}

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.

body
string

The body of the ad.

Supports Emoji
branded_content_sponsor_page_id
numeric string or integer

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

bundle_folder_id
numeric string or integer

The Dynamic Ad's bundle folder ID

call_to_action
Object

This field promotes an onsite or offsite action.

Supports Emoji
type
enum{BOOK_TRAVEL, CONTACT_US, DONATE, DONATE_NOW, DOWNLOAD, GET_DIRECTIONS, GO_LIVE, INTERESTED, LEARN_MORE, LIKE_PAGE, MESSAGE_PAGE, SAVE, SEND_TIP, SHOP_NOW, SIGN_UP, VIEW_INSTAGRAM_PROFILE, INSTAGRAM_MESSAGE, LOYALTY_LEARN_MORE, GET_MOBILE_APP, 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, GET_SHOWTIMES, LISTEN_NOW, GET_EVENT_TICKETS, SEARCH_MORE, PRE_REGISTER, BOOK_TEST_DRIVE, CHECK_AVAILABILITY, CALL, MISSED_CALL, CALL_NOW, CALL_ME, APPLY_NOW, BUY, GET_QUOTE, SUBSCRIBE, RECORD_NOW, VOTE_NOW, GIVE_FREE_RIDES, REGISTER_NOW, OPEN_MESSENGER_EXT, EVENT_RSVP, CIVIC_ACTION, SEND_INVITES, REQUEST_TIME, SEE_MENU, WHATSAPP_MESSAGE, SEARCH, TRY_IT, TRY_ON, LINK_CARD, DIAL_CODE, FIND_YOUR_GROUPS}

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
numeric string or integer

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

Supports Emoji
link_caption
string

product_link
string

get_movie_showtimes
boolean

sponsorship
Object

link
URL

image
URL

video_annotation
Object

annotations
list<Object>

start_time_in_sec
int64

end_time_in_sec
int64

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

offer_id
numeric string or integer

offer_view_id
numeric string or integer

advanced_data
Object

offer_id
numeric string or integer

lead_gen_form_id
numeric string or integer

fundraiser_campaign_id
numeric string or integer

event_id
numeric string or integer

event_tour_id
numeric string or integer

app_destination
enum {MESSENGER, MESSENGER_EXTENSIONS, MESSENGER_GAMES, LINK_CARD, MARKETPLACE}

app_destination_page_id
numeric string or integer

is_canvas_video_transition_enabled
boolean

whatsapp_number
string

preinput_text
string

customized_message_page_cta_text
string

external_offer_provider_id
numeric string or integer

categorization_criteria
enum{brand, category, product_type}

The Dynamic Category Ad's categorization criteria

category_media_source
enum{CATEGORY, MIXED, PRODUCTS_COLLAGE, PRODUCTS_SLIDESHOW}

The Dynamic Ad's rendering mode for category ads

destination_set_id
Product Set ID

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

dynamic_ad_voice
enum{DYNAMIC, STORY_OWNER}

Determines the Page voice to be used in Dynamic Local Ads

enable_direct_install
boolean

Whether Direct Install should be enabled on supported devices.

enable_launch_instant_app
boolean

Whether Instant App should be enabled on supported devices.

image_crops
dictionary { enum{191x100, 100x72, 400x150, 600x360, 100x100, 400x500, 90x160} : <list<list<int64>>> }

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. If object_story_spec or object_story_id is specified, this field will be ignored

image_hash
string

Image hash for an image you have uploaded and can be used in a creative. If object_story_spec or object_story_id is specified, this field will be ignored

image_url
URL

URL for the image in this ad creative. Do not use image URLs returned by Facebook. Instead you should host the image on your own servers. Facebook saves the image from your URL to your ad account's image library. Images cannot exceed 8 MB. You must also provide one of these three fields: image_file, image_hash, or image_url.

instagram_actor_id
numeric string or integer

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

instagram_permalink_url
URL

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

interactive_components_spec
JSON object

The specification for interactive component overlay on the media.

Supports Emoji
components
list<JSON object>

poll_spec
JSON object

RequiredSupports Emoji
option_a_text
string

Required
option_b_text
string

Required
question_text
string
Default value: ""

position_spec
JSON object

type
enum {1}

Required
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

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

The JSON string of messenger sponsored message for this creative. See (docs/messenger-platform/reference/send-api) for more detail

name
string

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

object_id
int64

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

object_story_id
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.

object_story_spec
string (ObjectStorySpec)

JSON string of AdCreativeObjectStorySpec type. 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.

Supports Emoji
object_type
string

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
OFFER
SHARE: from a page
PHOTO
STATUS: of a page
VIDEO
APPLICATION: app on Facebook

object_url
URL

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

platform_customizations
JSON or object-like arrays

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.

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 { enum{191x100, 100x72, 400x150, 600x360, 100x100, 400x500, 90x160} : <list<list<int64>>> }

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

playable_asset_id
numeric string or integer

The ID of the playable asset in this creative.

portrait_customizations
JSON object

Use this field to customizations how ads look in portrait mode format example for IG Stories, Facebook Stories, IGTV, etc

specifications
list<JSON object>

Required
background_color
JSON object

Required
bottom_color
string

Required
top_color
string

Required
product_set_id
numeric string or integer

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

recommender_settings
JSON object

The recommender settings that can be used to control recommendations for Dynamic Ads.

preferred_events
list<enum{ViewContent, Search, AddToCart, AddToWishlist, InitiateCheckout, AddPaymentInfo, Purchase, Lead, CompleteRegistration, CustomConversion, AggregateCustomConversion, Other}>

product_sales_channel
enum {ONLINE, IN_STORE, OMNI}

template_url
URL

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

template_url_spec
string (TemplateURLSpec)

An optional structured collection of templated web and app-link descriptors that override the fallbacks that would otherwise be pulled from a Dynamic Ad`s catalog

android
Object

app_name
string

package
string

url
string

config
Object

app_id
string

ios
Object

app_name
string

app_store_id
string

url
string

ipad
Object

app_name
string

app_store_id
string

url
string

iphone
Object

app_name
string

app_store_id
string

url
string

windows_phone
Object

app_name
string

app_id
string

url
string

web
Object

url
URL

should_fallback
string

thumbnail_url
URL

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 a Page Likes ad, which appears in the right-hand column on Facebook.

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
boolean

If true, we show the page actor for mobile app ads.

Return Type

This endpoint supports read-after-write and will read the node represented by id in the return type.
Struct {
id: numeric string,
success: bool,
}

Validation Rules

ErrorDescription
100Invalid parameter
200Permissions error
500Message contains banned content
294Managing advertisements requires an access token with the extended permission for ads_management
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.
105The number of parameters exceeded the maximum for this operation

Updating

You can't perform this operation on this endpoint.

Deleting

You can't perform this operation on this endpoint.