Reference

Media-Level Ad Format Validation

Business Creative Media Validation Results

Placement Label

FACEBOOK_STORY_MOBILE

Facebook Stories

MOBILE_FULLWIDTH

Mobile (full width)

MOBILE_INTERSTITIAL

Audience Network Interstitial

MOBILE_MEDIUM_RECTANGLE

Audience Network Medium Rectangle

MOBILE_NATIVE

Audience Network Native

INSTAGRAM_STANDARD

Instagram Feed

INSTAGRAM_STORY

Instagram Stories

INSTANT_ARTICLE_STANDARD

Instant Articles

MESSENGER_MOBILE_INBOX_MEDIA

Messenger Inbox

MESSENGER_MOBILE_STORY_MEDIA

Messenger Stories

DESKTOP_FEED_STANDARD

Desktop News Feed

MOBILE_FEED_STANDARD

Mobile News Feed

RIGHT_COLUMN_STANDARD

Desktop Right Column

Supported Video Ad Placements

Placement Label

FACEBOOK_STORY_MOBILE

Facebook Stories

MOBILE_FULLWIDTH

Mobile (Full width)

AUDIENCE_NETWORK_INSTREAM_VIDEO

Audience Network In-Stream Video

AUDIENCE_NETWORK_INSTREAM_VIDEO_MOBILE

Audience Network In-Stream Video (Mobile)

MOBILE_INTERSTITIAL

Audience Network Interstitial

MOBILE_MEDIUM_RECTANGLE

Audience Network Medium Rectangle

AUDIENCE_NETWORK_REWARDED_VIDEO

Audience Network Rewarded Video

INSTAGRAM_STANDARD

Instagram Feed

INSTAGRAM_STORY

Instagram Stories

INSTANT_ARTICLE_STANDARD

Instant Articles

INSTREAM_VIDEO_DESKTOP

Facebook In-Stream Video (Desktop)

INSTREAM_VIDEO_MOBILE

Facebook In-Stream Video (Mobile)

MESSENGER_MOBILE_INBOX_MEDIA

Messenger Inbox

MESSENGER_MOBILE_STORY_MEDIA

Messenger Stories

DESKTOP_FEED_STANDARD

Desktop News Feed

MOBILE_FEED_STANDARD

Mobile News Feed

SUGGESTED_VIDEO_MOBILE

Suggested Videos (Mobile)

Supported Endpoints

Ad Placement Validation on Existing Images or Videos

To see validation results for an existing image or video, send a GET request to the {business-image-id}/ad_placement_validation_results or {business-video-id}/ad_placement_validation_results edge.

Example Response (Image)

{
  "data": [
    {
      "ad_placement": "FACEBOOK_STORY_MOBILE",
      "ad_placement_label": "Facebook Stories",
      "is_valid": false,
      "error_messages": [
        "Fb Story Ads Resolution Is Too Low: The width of photo and video has to be larger than 500px for ads in Facebook Stories."
      ]
    },
...
    {
      "ad_placement": "INSTANT_ARTICLE_STANDARD",
      "ad_placement_label": "Instant Articles",
      "is_valid": true
    }
  ]
}

Example Response (Video)

{
  "data": [
    {
      "ad_placement": "INSTREAM_VIDEO_MOBILE",
      "ad_placement_label": "Facebook In-Stream Video (Mobile)",
      "is_valid": false,
      "error_messages": [
        "Ad Video Duration Is Too Short: Duration of the video used in the ad is too short."
      ]
    },
...
    {
      "ad_placement": "FACEBOOK_STORY_MOBILE",
      "ad_placement_label": "Facebook Stories",
      "is_valid": true
    }
  ]
}

Ad Placement Validation on all Business Creatives

You can also conveniently run validation against all creatives within a business by adding the ad_placement_validation_results field on a GET request to the {business-id}/creatives edge.

Example Request

curl -i -X GET \
 "https://graph.facebook.com/{version}/{business-id}/creatives?fields=ad_placement_validation_results&access_token={access_token}"

Ad Placement Validation at Upload Endpoints

When adding creatives to a folder, you can also run ad placement validation when uploading the creative by providing an array of ad placements through the optional validation_ad_placements parameter on either image/video upload POST request.

The supported placement types can be found in the Placement column in Supported Video Ad Placements. The API runs validations against the provided ad placements, rejects the upload if validation fails on any of them, and returns the validation results in the response.

An example call could include the parameter like this:

"validation_ad_placements"=["FACEBOOK_STORY_MOBILE", "MESSENGER_MOBILE_STORY_MEDIA"]

The results of the validation are returned in a example response like this:

"validation_results" => [
    {
        "ad_placement" => "FACEBOOK_STORY_MOBILE"
        "ad_placement_label" => "Facebook Stories"
        "error_messages" => ["The width of the media in the ad is too low. Try to use a different media.""The height of the media in the ad is too low. Try to use a different media."],
        "is_valid" => false,
    },
    {
        "ad_placement" => "MESSENGER_MOBILE_STORY_MEDIA"
        "ad_placement_label" => "Messenger Stories",
        "error_messages" => [],
        "is_valid" => true.
    },
]

Conditional Results

  • If the validation fails (as in the above example), only validation_results are returned in the response.
  • If all validation passes, the validation_results are appended to the normal upload response.
  • If you only run validations against the uploaded media (and never persist the upload), you can include a validation_only parameter that. If set to true, that parameter causes the API to always reject uploads and solely returns the validation results.
  • If validation_only is flagged true, but no ad placements are provided through validation_ad_placements, the API defaults to running validation for all ad placements.

Reference

Post

EndpointDescription

/{ad-account-id}/ads

Create an ad.

/{agreement-request-id}

Approve or decline a pending business agreement request.

/{business-creative-folder-id}

Create and update a business creative folder.

/{business-id}/creative_folders

Provide a business creative folder.

/{business-id}/images

Upload images to a creative folder.

/{business-id}/videos

Upload videos to a creative folder.

/{business-creative-folder-id}/agencies

Add a partner to a creative folder.

/{business-creative-folder-id}/assigned_users

Get a list of people who have access to the business creative folder.

Read

EndpointDescription
/{business-creative-folder-id}

Get details about a business creative folder.

/{business-id}/creative_folders

Get a list of business creative folders a business can access.

/{business-id}/creatives

Get business images and business videos of the business.

/{business-id}/initiated_sharing_agreement

Get a list of pending agreement requests.

/{business-id}/received_sharing_agreement

Get a list of pending agreement requests send to another business from yours.

/{business-image-id}

Get details for an image.

/{business-image-id}/insights

Get insights for a shared image.

/{business-video-id}

Get details of the shared video.

/{business-video-id}/insights

Get the insights for the shared video.

/{business-creative-folder-id}/agencies

Get a list of businesses who have access to your creative folder.

/{business-creative-folder-id}/assigned_users

Get a list of people who have access to your creative folder.

Delete

EndpointDescription
/{business-creative-folder-id}

Delete a creative folder.

/{business-creative-folder-id}/agencies

Remove a partner from the creative folder.

/{business-creative-folder-id}/assigned_users

Remove a user from the creative folder.

/{business-image-id}

Remove a shared image.

/{business-video-id}

Remove a shared video.

Permitted Tasks

Business User Permitted TaskDescription

CREATE_CONTENT

This user can create folders.

MANAGE_CONTENT

This user can manage creative folder assets.

MANAGE_PERMISSIONS

This user can manage business creative folder permissions.

VIEW_CONTENT

This user can view assets in a creative folder.

VIEW_INSIGHTS

This user can view the insights for a creative asset.

Insights

These metrics are under development.

Metric NameDescription
impressions

The number of times your image or video appeared in an ad.

inline_link_clicks

The number of clicks on links in your ad. Inline link clicks use a fixed 1-day-click attribution window.

video_play_actions

The number of times your video starts to play. We cound this for each video impression, and exclude replays.

actions

The total number of actions attributed to your ads. Actions include engagement, clicks, or conversions. See types of actions.

video_thruplay_watched_actions

The number of times your video was played to completion, or for at least 15 seconds.

quality_ranking

A ranking of your ad's perceived quality. Quality is measured using an ad's feedback and the post-click experience. An ad is ranked against other ads that competed for the same audience.


Possible values include:

  • BELOW_AVERAGE_10
  • BELOW_AVERAGE_20
  • BELOW_AVERAGE_35
  • AVERAGE
  • ABOVE_AVERAGE
  • UNKNOWN, if there is not enough information about the ad.

This is related to ad relevance diagnostics.

The following breakdowns are available:

  • age
  • gender
  • country
  • objective
  • publisher_platform
  • platform_position
  • device_platform
  • optimization_goal