Marketing 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])
curl -G \
-d 'fields=object_story_id' \
https://graph.facebook.com/<API_VERSION>/act_<AD_ACCOUNT_ID>/adcreatives/

Reading

The ad creatives of this ad account

Example

Graph API Explorer
GET /v2.11/{ad-account-id}/adcreatives 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(
    '/{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(
    "/{ad-account-id}/adcreatives",
    function (response) {
      if (response && !response.error) {
        /* handle the result */
      }
    }
);
/* make the API call */
new GraphRequest(
    AccessToken.getCurrentAccessToken(),
    "/{ad-account-id}/adcreatives",
    null,
    HttpMethod.GET,
    new GraphRequest.Callback() {
        public void onCompleted(GraphResponse response) {
            /* handle the result */
        }
    }
).executeAsync();
// For more complex open graph stories, use `FBSDKShareAPI`
// with `FBSDKShareOpenGraphContent`
/* make the API call */
FBSDKGraphRequest *request = [[FBSDKGraphRequest alloc]
                               initWithGraphPath:@"/{ad-account-id}/adcreatives"
                                      parameters:params
                                      HTTPMethod:@"GET"];
[request startWithCompletionHandler:^(FBSDKGraphRequestConnection *connection,
                                      id result,
                                      NSError *error) {
    // Handle the result
}];

Permissions

Developers usually request these permissions for this endpoint:

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

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
200Permissions error
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

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.

Example

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
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. Can only be used with instagram_story_id.

Supports Emoji
type
enum{SHOP_NOW, BOOK_TRAVEL, LEARN_MORE, SIGN_UP, DOWNLOAD, GET_DIRECTIONS, LIKE_PAGE, DONATE_NOW, CONTACT_US, VIEW_INSTAGRAM_PROFILE, 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, GET_SHOWTIMES, LISTEN_NOW, GET_EVENT_TICKETS, 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}

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
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
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
whatsapp_number
string
preinput_text
string
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. 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_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 { 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.

product_set_id
numeric string or integer

The Dynamic Product Ad's product set ID

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

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

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
380There was a problem uploading your thumbnail file. Please try again.
105The number of parameters exceeded the maximum for this operation
272This Ads API call requires the user to be admin of the application
273This Ads API call requires the user to be admin of the ad account
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
324Missing or invalid image file

Updating

You can't perform this operation on this endpoint.

Deleting

You can't perform this operation on this endpoint.