Graph API Version

Ad Creative Link Data

Reading

The specification for a link ad or carousel ad.

Example

Graph API Explorer
GET v5.0/...?fields={fieldname_of_type_AdCreativeLinkData} 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(
    '...?fields={fieldname_of_type_AdCreativeLinkData}',
    '{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(
    "...?fields={fieldname_of_type_AdCreativeLinkData}",
    function (response) {
      if (response && !response.error) {
        /* handle the result */
      }
    }
);
/* make the API call */
new GraphRequest(
    AccessToken.getCurrentAccessToken(),
    "...?fields={fieldname_of_type_AdCreativeLinkData}",
    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:@"...?fields={fieldname_of_type_AdCreativeLinkData}"
                                      parameters:params
                                      HTTPMethod:@"GET"];
[request startWithCompletionHandler:^(FBSDKGraphRequestConnection *connection,
                                      id result,
                                      NSError *error) {
    // Handle the result
}];
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

FieldDescription
additional_image_index
int32

The index (zero based) of the image from the additional images array to use as the ad image for a dynamic product ad

app_link_spec

Native deeplinks attached to the post

attachment_style
enum {link, default}

The style of the attachment

branded_content_shared_to_sponsor_status
string

The branded content shared to sponsor option

branded_content_sponsor_page_id
numeric string

The branded content sponsor page id

branded_content_sponsor_relationship
string

The branded content sponsor relationship option

call_to_action

An optional call to action button. If not specified, on Instagram, a default CTA would be used, {"type":"LEARN_MORE","value": {"link":<LINK VALUE OF LINK_DATA>,}}. Note that LIKE_PAGE is not supported

caption
string

Link caption. Overwrites the caption under the title in the link. The caption must be an actual URL and should accurately reflect the URL and associated advertiser or business someone visits when they click the link. See Post, Reference for more info. You do not use this setting in Instagram ads.

child_attachments

A 2-5 element array of link objects required for carousel ads. If multi_share_optimized is set to true, this array could have up to 10 objects. Facebook will automatically optimize the order in which the carousel cards are shown and display the top 5. We strongly recommend that you use at least 3 attachments for achieving optimal performance; allowing minimum of 2 attachments is for enabling lightweight integrations and using 2 objects might result in sub-optimal campaign results.
If this ad creative is used for an Instagram Carousel ad, you will need to have at least 3 attachments for MOBILE_APP_INSTALLS ads and 2 for the other objectives. If more than 5 are given, only the first 5 will be shown on Instagram, even if multi_share_optimized is true.

collection_thumbnails
list<AdCreativeCollectionThumbnailInfo>

List of Canvas media component IDs and their square cropping information provided by the advertiser for Collection style feed rendering

customization_rules_spec
list<AdCustomizationRuleSpec>

Customization rules for a dynamic ad

description
string

Link description. Overwrites the description in the link when your ad displays. See Post, Reference for more information. You do not use this setting for Instagram ads.

event_id
numeric string

The id of a Facebook event. This is only to be used if this creative is for a Website Clicks campaign, the Call To Action is Buy Tickets, and the link points to the ticketing website of this Facebook event

force_single_link
bool

Whether to force the post to render in a single link format

format_option
enum {carousel_images_multi_items, carousel_images_single_item, carousel_slideshows, single_image}

Options on how to render your ad. If not specified, default is carousel_images_multi_items. See Dynamic Ads, Ads Management

image_crops

How to the image should be cropped. You can use the crop spec with 100x100 key for Facebook News Feed and Instagram.

image_hash
string

Hash of an image in your ad account's image library. Provide a value for this field or `picture` but not both

image_layer_specs

How to render image overlays on a dynamic item in Dynamic Ads

image_overlay_spec

How to render image overlays on a dynamic item in Dynamic Ads

link
string

Link url. This url is required to be the same as the CTA link url. See post for more info. This field is required for a carousel ad

message
string

The main body of the post. See post for more info. This field is required for a carousel ad

multi_share_end_card
bool

If set to false, removes the end card which displays the page icon. Default is true. Used by carousel ads

multi_share_optimized
bool

If set to true, automatically select and order images and links. Default is true. Used by carousel ads

name
string

Name of the link. Overwrite the title of the link when you preview the ad. Facebook ignores this value when call-to-action type is LIKE_PAGE. See Post, Reference for more information

offer_id
numeric string

The id of a Facebook native offer

page_welcome_message
string

A welcome text from page to user on Messenger once a user performs send message action on an ad

picture
string

URL of a picture to use in the post. Specify this field or image_hash but not both. See post for more info. The image specified at the URL will be saved into the ad accounts image library

post_click_configuration
AdCreativePostClickConfiguration

Customized contents provided by the advertiser for the ad post-click experience

preferred_image_tags
list<string>

Select which image to display by its tag, if you have added tags to your images. Tags are specified in order of priority to try

retailer_item_ids
list<string>

List of product IDs provided by the advertiser for Collections

show_multiple_images
bool

Use with force_single_link = true in order to show a single dynamic item but in carousel format using multiple images from the catalog. See dynamic product ad

sponsorship_info
AdCreativeLinkDataSponsorshipInfoSpec

Details of the sponsor for the event ad

static_fallback_spec
AdCreativeStaticFallbackSpec

Give a fallback creative for dynamic ads

use_flexible_image_aspect_ratio
bool

Default value is true. This field only applies if you do not provide a cropping spec. We ignore it if you provide one.

If true, when the aspect ratio, or width:height ratio, is between 1.91:1 and 1:1, render the entire image. If the image is taller than the aspect ratio 1:1, automatically crop it to 1:1 and render the cropped image. If the image is wider than aspect ratio 1.91:1, automatically crop it to 1.91:1 and render the cropped image.

If set to false, when the aspect ratio, or width:height ratio, is 1.91:1, render the entire image. If the image aspect ratio is not 1.91:1, automatically crop it to 1.91:1 aspect ratio and render the cropped image.

Use this field only for single image ads, not carousel ads.

This field is not supported for Donation ads, Offer ads, Dynamic Ads, ads with image overlays, and ads using stock images.

Creating

You can't perform this operation on this endpoint.

Updating

You can't perform this operation on this endpoint.

Deleting

You can't perform this operation on this endpoint.