Format which provides layout and contains content for the ad. To see available ad creatives, visit Ads Guide. The guide also contains information on size requirements for each ad unit. See also Facebook for Business and Inline page post creation blog post.
Advertisers running ads about social issues, elections, and politics need to specify special_ad_categories
while creating an ad campaign. In addition, businesses still have to set authorization_category
to flag at the ad creative level. Learn more about the requirements.
For example, get information about an ad creative, such as the ID of the newly created unpublished page post:
curl -G \
-d 'fields=name,object_story_id' \
-d 'access_token=<ACCESS_TOKEN>' \
https://graph.facebook.com/v21.0
/<CREATIVE_ID>
Create a link ad:
curl \
-F 'name=Sample Creative' \
-F 'object_story_spec={
"link_data": {
"image_hash": "<IMAGE_HASH>",
"link": "<URL>",
"message": "try it out"
},
"page_id": "<PAGE_ID>"
}' \
-F 'access_token=<ACCESS_TOKEN>' \
https://graph.facebook.com/v21.0
/act_<AD_ACCOUNT_ID>/adcreatives
You can replace picture
with image_hash
to specify an image from your ad account's image library. You can also specify image cropping with image_crops
in link_data
. See Image Crop, Reference.
To create a political ad creative, use the field authorization_category
with value POLITICAL
. For example:
curl \
-F 'authorization_category=POLITICAL' \
-F 'object_story_spec={
...
}' \
-F 'access_token=<ACCESS_TOKEN>' \
https://graph.facebook.com/v21.0
/act_<AD_ACCOUNT_ID>/adcreatives
Beginning January 9, 2024, to create an issue, electoral, or political ad creative that uses media that is digitally created or altered, use the authorization_category
field with the POLITICAL_WITH_DIGITALLY_CREATED_MEDIA
value. For example:
curl \
-F 'authorization_category=POLITICAL_WITH_DIGITALLY_CREATED_MEDIA' \
-F 'object_story_spec={
...
}' \
-F 'access_token=<ACCESS_TOKEN>' \
https://graph.facebook.com/v21.0
/act_<AD_ACCOUNT_ID>/adcreatives
For guidelines on Facebook ads see Ad Guidelines.
Only returns 50,000 ad creatives, pagination past this is unavailable.
Limit | Value |
---|---|
Maximum ad title length | 25 characters, recommended |
Minimum ad title length | 1 character |
Maximum ad body length | 90 characters, recommended |
Minimum ad body length | 1 character |
Maximum length of a URL | 1000 characters |
Maximum length of an individual word in title or body | 30 characters, recommended |
\ / ! . ? - * ( ) , ; :
...
The following characters are not allowed:
^~_={}[]|<>
★
See Placement for restrictions on placement of your ad based on creative.
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
Request the thumbnail URL and dimensions:
curl -G \
-d 'thumbnail_width=150' \
-d 'thumbnail_height=120' \
-d 'fields=thumbnail_url' \
-d 'access_token=<ACCESS_TOKEN>' \
https://graph.facebook.com/v21.0
/<CREATIVE_ID>
GET /v21.0/<CREATIVE_ID>/?fields=asset_feed_spec HTTP/1.1
Host: graph.facebook.com
/* PHP SDK v5.0.0 */
/* make the API call */
try {
// Returns a `Facebook\FacebookResponse` object
$response = $fb->get(
'/<CREATIVE_ID>/?fields=asset_feed_spec',
'{access-token}'
);
} catch(Facebook\Exceptions\FacebookResponseException $e) {
echo 'Graph returned an error: ' . $e->getMessage();
exit;
} catch(Facebook\Exceptions\FacebookSDKException $e) {
echo 'Facebook SDK returned an error: ' . $e->getMessage();
exit;
}
$graphNode = $response->getGraphNode();
/* handle the result */
/* make the API call */
FB.api(
"/<CREATIVE_ID>/",
{
"fields": "asset_feed_spec"
},
function (response) {
if (response && !response.error) {
/* handle the result */
}
}
);
Bundle params = new Bundle();
params.putString("fields", "asset_feed_spec");
/* make the API call */
new GraphRequest(
AccessToken.getCurrentAccessToken(),
"/<CREATIVE_ID>/",
params,
HttpMethod.GET,
new GraphRequest.Callback() {
public void onCompleted(GraphResponse response) {
/* handle the result */
}
}
).executeAsync();
NSDictionary *params = @{
@"fields": @"asset_feed_spec",
};
/* make the API call */
FBSDKGraphRequest *request = [[FBSDKGraphRequest alloc]
initWithGraphPath:@"/<CREATIVE_ID>/"
parameters:params
HTTPMethod:@"GET"];
[request startWithCompletionHandler:^(FBSDKGraphRequestConnection *connection,
id result,
NSError *error) {
// Handle the result
}];
curl -X GET -G \
-d 'fields="asset_feed_spec"' \
-d 'access_token=<ACCESS_TOKEN>' \
https://graph.facebook.com/v21.0/<CREATIVE_ID>/
Parameter | Description |
---|---|
thumbnail_height int64 | Default value: 64 Rendered height of thumbnails provided in thumbnail_url, in pixels |
thumbnail_width int64 | Default value: 64 Rendered width of thumbnails accessible in thumbnail_url, in pixels |
Field | Description |
---|---|
id numeric string | Unique ID for an ad creative, numeric string. |
account_id numeric string | Ad account ID for the account this ad creative belongs to. |
actor_id numeric string | The actor ID (Page ID) of this creative |
adlabels | Ad Labels associated with this creative. Used to group it with related ad objects. |
applink_treatment enum | Used for Dynamic Ads. Specify what action should occur if a person clicks a link in the ad, but the business' app is not installed on their device. For example, open a webpage displaying the product, or open the app in an app store on the person's mobile device. |
asset_feed_spec | Used for Dynamic Creative to automatically experiment and deliver different variations of an ad's creative. Specifies an asset feed with multiple images, text and other assets used to generate variations of an ad. Formatted as a JSON string. |
authorization_category enum | Specifies whether ad was configured to be labeled as a political ad or not. See Facebook Advertising Policies. This field cannot be used for Dynamic Ads. |
body string | The body of the ad. Not supported for video post creatives |
branded_content AdCreativeBrandedContentAds | branded_content |
bundle_folder_id numeric string | The Dynamic Ad's bundle folder ID |
call_to_action_type enum {OPEN_LINK, LIKE_PAGE, SHOP_NOW, PLAY_GAME, INSTALL_APP, USE_APP, CALL, CALL_ME, VIDEO_CALL, 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, CALL_NOW, APPLY_NOW, CONTACT, BUY_NOW, GET_OFFER, GET_OFFER_VIEW, BUY_TICKETS, UPDATE_APP, GET_DIRECTIONS, BUY, SEND_UPDATES, MESSAGE_PAGE, DONATE, SUBSCRIBE, SAY_THANKS, SELL_NOW, SHARE, DONATE_NOW, GET_QUOTE, CONTACT_US, ORDER_NOW, START_ORDER, ADD_TO_CART, VIDEO_ANNOTATION, RECORD_NOW, INQUIRE_NOW, CONFIRM, REFER_FRIENDS, REQUEST_TIME, GET_SHOWTIMES, LISTEN_NOW, WOODHENGE_SUPPORT, SOTTO_SUBSCRIBE, FOLLOW_USER, RAISE_MONEY, EVENT_RSVP, WHATSAPP_MESSAGE, FOLLOW_NEWS_STORYLINE, SEE_MORE, BOOK_NOW, FIND_A_GROUP, FIND_YOUR_GROUPS, PAY_TO_ACCESS, PURCHASE_GIFT_CARDS, FOLLOW_PAGE, SEND_A_GIFT, SWIPE_UP_SHOP, SWIPE_UP_PRODUCT, SEND_GIFT_MONEY, PLAY_GAME_ON_FACEBOOK, GET_STARTED, OPEN_INSTANT_APP, AUDIO_CALL, GET_PROMOTIONS, JOIN_CHANNEL, MAKE_AN_APPOINTMENT, ASK_ABOUT_SERVICES, BOOK_A_CONSULTATION, GET_A_QUOTE, BUY_VIA_MESSAGE, ASK_FOR_MORE_INFO, CHAT_WITH_US, VIEW_PRODUCT, VIEW_CHANNEL} | Type of call to action button in your ad. This determines the button text and header text for your ad. See Ads Guide for campaign objectives and permitted call to action types. |
categorization_criteria enum | The Dynamic Category Ad's categorization field, e.g. brand |
category_media_source enum | The Dynamic Ad's rendering mode for category ads |
collaborative_ads_lsb_image_bank_id numeric string | Used for CPAS local delivery image bank |
contextual_multi_ads AdCreativeContextualMultiAds | contextual_multi_ads |
creative_sourcing_spec | AdCreativeSourcingSpec stores metadata about the ad that can be used for creative optimization. For instance, it may include a product set ID, which can be utilized in the 'add catalog items' creative optimization feature. |
degrees_of_freedom_spec | Specifies the types of transformations that are enabled for the given creative |
destination_set_id numeric string | The ID of the Product Set for a Destination Catalog that will be used to link with Travel Catalogs |
dynamic_ad_voice string | Used for Store Traffic Objective inside Dynamic Ads. Allows you to control the voice of your ad. If set to |
effective_authorization_category enum | Specifies whether ad is a political ad or not. See Facebook Advertising Policies. This field cannot be used for Dynamic Ads. This value can be different than the authorization_category value in case our systems have identified the ad as political even though it was not configured to be labeled as such. |
effective_instagram_media_id numeric string | The ID of an Instagram post to use in an ad |
effective_instagram_story_id numeric string | Used for Instagram Ads. The ID of an Instagram post to display as an Instagram ad. |
effective_object_story_id token with structure: Post ID | The ID of a page post to use in an ad, regardless of whether it's an organic or unpublished page post. It will return empty if the page is not yet published. |
enable_direct_install bool | Whether Direct Install should be enabled on supported devices |
enable_launch_instant_app bool | Whether Instant App should be enabled on supported devices |
facebook_branded_content AdCreativeFacebookBrandedContent | Stores fields for Facebook Branded Content |
image_crops | A JSON object defining crop dimensions for the image specified. See image crop reference for more details |
image_hash string | Image hash for ad creative. If provided, do not add |
image_url string | A URL for the image for this creative. We save the image at this URL to the ad account's image library. If provided, do not include |
instagram_actor_id numeric string | Used for Instagram Ads. Provide Instagram account ID used for running these ads. |
instagram_branded_content AdCreativeInstagramBrandedContent | Instagram branded content |
instagram_permalink_url string | URL for a post on Instagram you want to run as an ad. Also known as Instagram media. |
instagram_story_id numeric string | Used for Instagram Stories as Ads. Specifies the Instagram story you want to run as an ad. This field will be deprecated in the future. Use |
instagram_user_id numeric string | Instagram actor ID |
interactive_components_spec | Specification for all the interactive components that would show up on the ad |
link_destination_display_url string | Overwrites the display URL for link ads when |
link_og_id numeric string | The Open Graph (OG) ID for the link in this creative if the landing page has OG tags |
link_url string | Identify a specific landing tab on your Facebook page by the Page tab's URL. See connection objects for retrieving Page tab URLs. You can add app_data parameters to the URL to pass data to a Page's tab. |
messenger_sponsored_message string | Used for Messenger sponsored message. JSON string with message for this ad creative. See Messenger Platform, Send API Reference. |
name string | Name of this ad creative as seen in the ad account's library. This field has a limit of 100 characters. |
object_id numeric string | ID for Facebook object being promoted with ads or relevant to the ad or ad type. For example a page ID if you are running ads to generate Page Likes. See promoted_object. |
object_store_url string | iTunes or Google Play of the destination of an app ad |
object_story_id token with structure: Post ID | ID of a Facebook Page post to use in an ad. You can get this ID by querying the posts of the page. If this post includes an image, it should not exceed 8 MB. Facebook will upload the image from the post to your ad account's image library. If you create an unpublished page post via |
object_story_spec | 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 |
object_type enum {APPLICATION, DOMAIN, EVENT, OFFER, PAGE, PHOTO, SHARE, STATUS, STORE_ITEM, VIDEO, INVALID, PRIVACY_CHECK_FAIL, POST_DELETED} | The type of Facebook object you want to advertise. Allowed values are: |
object_url string | URL that opens if someone clicks your link on a link ad. This URL is not connected to a Facebook page. |
page_welcome_message string | Page welcome message for CTM ads |
photo_album_source_object_story_id string | photo_album_source_object_story_id |
place_page_set_id numeric string | The ID of the page set for this creative. See theLocal Awareness guide |
platform_customizations | Use this field to specify the exact media to use on different Facebook placements. You can currently use this setting for images and videos. Facebook replaces the media originally defined in ad creative with this media when the ad displays in a specific placements. For example, if you define a media here for |
playable_asset_id numeric string | The ID of the playable asset in this creative |
portrait_customizations AdCreativePortraitCustomizations | This field describes the rendering customizations selected for portrait mode ads like IG Stories, FB Stories, IGTV, etc |
product_data list<AdCreativeProductData> | product_data |
product_set_id numeric string | Used for Dynamic Ad. An ID for a product set, which groups related products or other items being advertised. |
recommender_settings AdCreativeRecommenderSettings | Used for Dynamic Ads. Settings to display Dynamic ads based on product recommendations. |
referral_id numeric string | The ID of Referral Ad Configuration in this creative |
source_instagram_media_id numeric string | The ID of an Instagram post for creating ads |
status enum {ACTIVE, IN_PROCESS, WITH_ISSUES, DELETED} | The status of the creative. |
template_url string | Used for Dynamic Ads when you want to use third-party click tracking. See Dynamic Ads, Click Tracking and Templates. |
template_url_spec | Used for Dynamic Ads when you want to use third-party click tracking. See Dynamic Ads, Click Tracking and Templates. |
thumbnail_id numeric string | thumbnail_id |
thumbnail_url string | URL for a thumbnail image for this ad creative. You can provide dimensions for this with |
title string | Title for link ad, which does not belong to a page. |
url_tags string | A set of query string parameters which will replace or be appended to urls clicked from page post ads, message of the post, and canvas app install creatives only |
use_page_actor_override bool | Used for App Ads. If |
video_id numeric string | Facebook object ID for video in this ad creative. |
Edge | Description |
---|---|
Edge<AdPreview> | The HTML Snippets for previewing this creative |
Error | Description |
---|---|
100 | Invalid parameter |
190 | Invalid OAuth 2.0 Access Token |
80004 | There 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#ads-management. |
270 | This Ads API request is not allowed for apps with development access level (Development access is by default for all apps, please request for upgrade). Make sure that the access token belongs to a user that is both admin of the app and admin of the ad account |
2500 | Error parsing graph query |
200 | Permissions error |
Define creative as part of an ad set or standalone. In either case, we store your ad creative in your ad account's creative library to use in ads. If you try to add an creative that isn't unique, we do not generate it and return the creative ID of the existing ad creative. For example, create a Link Ad with a call to action:
curl \
-F 'name=Sample Creative' \
-F 'object_story_spec={
"link_data": {
"call_to_action": {"type":"SIGN_UP","value":{"link":"<URL>"}},
"link": "<URL>",
"message": "try it out"
},
"page_id": "<PAGE_ID>"
}' \
-F 'access_token=<ACCESS_TOKEN>' \
https://graph.facebook.com/v21.0
/act_<AD_ACCOUNT_ID>/adcreatives
You use link_caption
to pass the call to action object. By doing this, you can customize the call to action caption. To customize the call to action description, pass link_description
in the call to action object.
Create a carousel ad
curl \
-F 'name=Sample Creative' \
-F 'object_story_spec={
"link_data": {
"child_attachments": [
{
"description": "$8.99",
"image_hash": "<IMAGE_HASH>",
"link": "https:\/\/www.link.com\/product1",
"name": "Product 1",
"video_id": "<VIDEO_ID>"
},
{
"description": "$9.99",
"image_hash": "<IMAGE_HASH>",
"link": "https:\/\/www.link.com\/product2",
"name": "Product 2",
"video_id": "<VIDEO_ID>"
},
{
"description": "$10.99",
"image_hash": "<IMAGE_HASH>",
"link": "https:\/\/www.link.com\/product3",
"name": "Product 3"
}
],
"link": "<URL>"
},
"page_id": "<PAGE_ID>"
}' \
-F 'access_token=<ACCESS_TOKEN>' \
https://graph.facebook.com/v21.0
/act_<AD_ACCOUNT_ID>/adcreatives
As a partnership ads sponsor, you can create ads with posts where your brand is tagged. Create a campaign, ad set, as ads as your normally do. The only difference is in the ad creative.
Set the sponsor_page_id
field for facebook_branded_content
and/or the sponsor_id
field for instagram_branded_content
in the ad creative. For example:
curl \ -F 'access_token=<TOKEN>' \ -F 'facebook_branded_content':{'sponsor_page_id=<PAGE_ID>'}\ // OR -F 'instagram_branded_content':{'sponsor_id=<Instagram_user_ID>'}\ -F 'object_story_id=<OBJECT_STORY_ID>' \ https://graph.facebook.com/<VERSION>/<ACCOUNT_ID>/adcreatives
Where object_story_id
is the post id in the format of: postOwnerID_postID
.
Most ad creatives rely on page posts for creative content. While you may create page posts separately then reference them by ID, it is easier to create them in the same call you use to provide ad creative. Specify the page post content with object_story_spec
which creates an unpublished page post. See Inline Page Post, Blog.
You can get the new ID by retrieving object_story_id
from the ad creative. To get post ids created with object_story_spec
through /promotable_posts
, pass include_inline=true
in your HTTP GET
. If include_inline
value is false
, we don't return any ids.
Many ad creatives require object_id
for a relevant Facebook object, app ID, or page tab's URL. See Connection Objects for more information.
Create a Video Page Like ad:
curl \
-F 'name=Sample Creative' \
-F 'object_story_spec={
"page_id": "<PAGE_ID>",
"video_data": {
"call_to_action": {"type":"LIKE_PAGE","value":{"page":"<PAGE_ID>"}},
"image_url": "<THUMBNAIL_URL>",
"video_id": "<VIDEO_ID>"
}
}' \
-F 'access_token=<ACCESS_TOKEN>' \
https://graph.facebook.com/v21.0
/act_<AD_ACCOUNT_ID>/adcreatives
Create an ad from an existing page post
curl \
-F 'name=Sample Promoted Post' \
-F 'object_story_id=<POST_ID>' \
-F 'access_token=<ACCESS_TOKEN>' \
https://graph.facebook.com/v21.0
/act_<AD_ACCOUNT_ID>/adcreatives
Create a Photo Ad with Branded Content from another page. This is available for photo, video, and link ads.
curl \
-F 'name=Sample Creative' \
-F 'object_story_spec={
"page_id": "<PAGE_ID>",
"photo_data": {
"branded_content_sponsor_page_id": "<SPONSOR_PAGE_ID>",
"image_hash": "<IMAGE_HASH>"
}
}' \
-F 'access_token=<ACCESS_TOKEN>' \
https://graph.facebook.com/v21.0
/act_<AD_ACCOUNT_ID>/adcreatives
Adding url_tags
to an ad
curl \
-F 'object_story_id=<POST_ID>' \
-F 'url_tags=key1=val1&key2=val2' \
-F 'access_token=<ACCESS_TOKEN>' \
https://graph.facebook.com/v21.0
/act_<AD_ACCOUNT_ID>/adcreatives
curl \
-F 'name=New creative name 1517287550' \
-F 'access_token=<ACCESS_TOKEN>' \
https://graph.facebook.com/v21.0
/<CREATIVE_ID>
/{ad_creative_id}
.Parameter | Description |
---|---|
account_id numeric string | Ad account ID for the account this ad creative belongs to. |
adlabels list<Object> | Ad Labels associated with this creative. Used to group it with related ad objects. |
name string | The name of the creative in the creative library. This field takes a string of up to 100 characters. |
status enum {ACTIVE, IN_PROCESS, WITH_ISSUES, DELETED} | The status of this ad creative. See Storing and Retrieving Ad Objects. |
success
: bool, Error | Description |
---|---|
200 | Permissions error |
100 | Invalid parameter |
curl -X DELETE \
-d 'access_token=<ACCESS_TOKEN>' \
https://graph.facebook.com/v21.0
/<CREATIVE_ID>/
/{ad_creative_id}
.Parameter | Description |
---|---|
account_id numeric string | Ad account ID for the account this ad creative belongs to. |
adlabels list<Object> | Ad Labels associated with this creative. Used to group it with related ad objects. |
name string | Name of this ad creative as seen in the ad account's library. |
status enum {ACTIVE, IN_PROCESS, WITH_ISSUES, DELETED} | The status of this ad creative. See Storing and Retrieving Ad Objects. |
success
: bool, Error | Description |
---|---|
200 | Permissions error |
100 | Invalid parameter |