Marketing API Version

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

Permissions

Developers usually request these permissions for this endpoint:

Marketing Apps
Permissions are not usually requested.
Page management Apps
No data
Other Apps
No data
If you want to learn how to use the Graph API, read our Using Graph API guide.

Parameters

NameDescription
thumbnail_height
int64
Default value: 64

Height of thumbnails accessible in thumbnail_url

thumbnail_width
int64
Default value: 64

Width of thumbnails accessible in thumbnail_url

Fields

FieldDescription

id

numeric string

The ID of this creative

account_id

numeric string

Account ID

actor_id

numeric string

The actor ID (Page ID) of this creative.

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, LEARN_MORE, SIGN_UP, DOWNLOAD, WATCH_MORE, NO_BUTTON, CALL_NOW, APPLY_NOW, BUY_NOW, GET_OFFER, GET_OFFER_VIEW, GET_DIRECTIONS, MESSAGE_PAGE, MESSAGE_USER, SUBSCRIBE, SELL_NOW, DONATE_NOW, GET_QUOTE, CONTACT_US, RECORD_NOW, VOTE_NOW, REGISTER_NOW, REQUEST_TIME, SEE_MENU, 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

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 for creating ads.

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

The page id and the content to create a new unpublished page post specified using one of link_data, photo_data, video_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
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

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

use_page_actor_override

bool

If this is true, we will show the page actor for mobile app ads

video_id

numeric string

The ID of the video in this creative

Edges

EdgeDescription

previews

The HTML Snippets for previewing this creative

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
275Cannot determine the target object for this request. Currently supported objects include ad account, business account and associated objects.
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

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<int64>

Action spec

Deprecated
actor_id
int64

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

adlabels
list<Object>

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

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, GO_LIVE, DONATE, SEND_TIP, 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, 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}

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
Supports Emoji
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
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
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}
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
int64

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
int64

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

object_instagram_id
int64

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

use_page_actor_override
boolean

If this is true, we will show the page actor for mobile app ads

Return Type

Struct {
id: numeric string,
}

Validation Rules

ErrorDescription
100Invalid parameter
275Cannot determine the target object for this request. Currently supported objects include ad account, business account and associated objects.

Updating

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

Permissions

Developers usually request these permissions for this endpoint:

Marketing Apps
  • ads_management
Page management Apps
No data
Other Apps
No data

Parameters

NameDescription
account_id
numeric string

Account ID

adlabels
list<Object>

Ad Labels that are associated with this creative

name
string

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

run_status
int64

The status of this 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
275Cannot determine the target object for this request. Currently supported objects include ad account, business account and associated objects.

Deleting

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

Permissions

Developers usually request these permissions for this endpoint:

Marketing Apps
  • ads_management
Page management Apps
No data
Other Apps
No data

Parameters

NameDescription
account_id
numeric string

Account ID

adlabels
list<Object>

Ad Labels that are associated with this creative

name
string

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

run_status
int64

The status of this 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