Guides Reference Samples Support

Creatives

The Creatives resource provides a way to submit new creatives to Google's creative verification pipeline.

For a list of methods for this resource, see the end of this page.

Resource representations

A creative and its classification data.

{
  "kind": "adexchangebuyer#creative",
  "accountId": integer,
  "buyerCreativeId": string,
  "creativeStatusIdentityType": string,
  "agencyId": long,
  "version": integer,
  "apiUploadTimestamp": datetime,
  "HTMLSnippet": string,
  "nativeAd": {
    "headline": string,
    "body": string,
    "callToAction": string,
    "advertiser": string,
    "image": {
      "url": string,
      "width": integer,
      "height": integer
    },
    "logo": {
      "url": string,
      "width": integer,
      "height": integer
    },
    "appIcon": {
      "url": string,
      "width": integer,
      "height": integer
    },
    "starRating": double,
    "impressionTrackingUrl": [
      string
    ],
    "clickLinkUrl": string,
    "clickTrackingUrl": string,
    "price": string,
    "store": string,
    "videoURL": string
  },
  "videoURL": string,
  "videoVastXML": string,
  "clickThroughUrl": [
    string
  ],
  "adChoicesDestinationUrl": string,
  "impressionTrackingUrl": [
    string
  ],
  "vendorType": [
    integer
  ],
  "attribute": [
    integer
  ],
  "width": integer,
  "height": integer,
  "advertiserName": string,
  "dealsStatus": string,
  "openAuctionStatus": string,
  "servingRestrictions": [
    {
      "reason": string,
      "contexts": [
        {
          "contextType": string,
          "geoCriteriaId": [
            integer
          ],
          "platform": [
            string
          ],
          "auctionType": [
            string
          ]
        }
      ],
      "disapprovalReasons": [
        {
          "reason": string,
          "details": [
            string
          ]
        }
      ]
    }
  ],
  "advertiserId": [
    long
  ],
  "sensitiveCategories": [
    integer
  ],
  "restrictedCategories": [
    integer
  ],
  "productCategories": [
    integer
  ],
  "languages": [
    string
  ],
  "detectedDomains": [
    string
  ],
  "corrections": [
    {
      "reason": string,
      "details": [
        string
      ],
      "contexts": [
        {
          "contextType": string,
          "geoCriteriaId": [
            integer
          ],
          "platform": [
            string
          ],
          "auctionType": [
            string
          ]
        }
      ]
    }
  ],
  "filteringReasons": {
    "date": string,
    "reasons": [
      {
        "filteringStatus": integer,
        "filteringCount": long
      }
    ]
  }
}
Property name Value Description Notes
HTMLSnippet string The HTML snippet that displays the ad when inserted in the web page. If set, videoURL, videoVastXML, and nativeAd should not be set. writable
accountId integer Account ID.
adChoicesDestinationUrl string The link to the Ad Preferences page. This is only supported for native ads. writable
advertiserId[] list Detected advertiser ID, if any. Read-only. This field should not be set in requests.
advertiserName string The name of the company being advertised in the creative. The value provided must exist in the advertisers.txt file.
agencyId long The agency id for this creative. writable
apiUploadTimestamp datetime The last upload timestamp of this creative if it was uploaded via API. Read-only. The value of this field is generated, and will be ignored for uploads. (formatted RFC 3339 timestamp).
attribute[] list List of buyer selectable attributes for the ads that may be shown from this snippet. Each attribute is represented by an integer as defined in buyer-declarable-creative-attributes.txt. writable
buyerCreativeId string A buyer-specific ID identifying the creative in this ad.
clickThroughUrl[] list The set of destination URLs for the snippet.
corrections[] list Shows any corrections that were applied to this creative. Read-only. This field should not be set in requests.
corrections[].contexts[] list All known serving contexts containing serving status information.
corrections[].contexts[].auctionType[] list Only set when contextType=AUCTION_TYPE. Represents the auction types this correction applies to.
corrections[].contexts[].contextType string The type of context (e.g., location, platform, auction type, SSL-ness).

Acceptable values are:
  • "ALL"
  • "AUCTION_TYPE"
  • "LOCATION"
  • "PLATFORM"
  • "SSL_REQUEST"
  • "UNKNOWN_TYPE"
corrections[].contexts[].geoCriteriaId[] list Only set when contextType=LOCATION. Represents the geo criterias this correction applies to.
corrections[].contexts[].platform[] list Only set when contextType=PLATFORM. Represents the platforms this correction applies to.
corrections[].details[] list Additional details about the correction.
corrections[].reason string The type of correction that was applied to the creative.

Acceptable values are:
  • "FLASHLESS_ATTRIBUTE"
  • "FLASH_ATTRIBUTE"
  • "FLASH_ATTRIBUTE_REMOVED"
  • "IN_BANNER_VIDEO_ATTRIBUTE_ADDED"
  • "MRAID_ATTRIBUTE_ADDED"
  • "REQUIRED_ATTRIBUTE"
  • "REQUIRED_VENDOR"
  • "SSL_ATTRIBUTE"
  • "SSL_ATTRIBUTE_ADDED"
  • "VENDOR_IDS"
  • "VIDEO_IN_SNIPPET_ATTRIBUTE_ADDED"
creativeStatusIdentityType string Creative status identity type that the creative item applies to. Ad Exchange real-time bidding is migrating to the sizeless creative verification. Originally, Ad Exchange assigned creative verification status to a unique combination of a buyer creative ID and creative dimensions. Post-migration, a single verification status will be assigned at the buyer creative ID level. This field allows to distinguish whether a given creative status applies to a unique combination of a buyer creative ID and creative dimensions, or to a buyer creative ID as a whole.

Acceptable values are:
  • "CREATIVE_IDENTITY_TYPE_UNSPECIFIED"
  • "CREATIVE_ID_AND_SIZE"
  • "CREATIVE_ID_ONLY"
dealsStatus string Top-level deals status. Read-only. This field should not be set in requests. If disapproved, an entry for auctionType=DIRECT_DEALS (or ALL) in servingRestrictions will also exist. Note that this may be nuanced with other contextual restrictions, in which case it may be preferable to read from servingRestrictions directly.

Acceptable values are:
  • "APPROVED"
  • "CONDITIONALLY_APPROVED"
  • "DISAPPROVED"
  • "NOT_CHECKED"
  • "UNKNOWN"
detectedDomains[] list Detected domains for this creative. Read-only. This field should not be set in requests.
filteringReasons object The filtering reasons for the creative. Read-only. This field should not be set in requests.
filteringReasons.date string The date in ISO 8601 format for the data. The data is collected from 00:00:00 to 23:59:59 in PST.
filteringReasons.reasons[] list The filtering reasons.
filteringReasons.reasons[].filteringCount long The number of times the creative was filtered for the status. The count is aggregated across all publishers on the exchange.
filteringReasons.reasons[].filteringStatus integer The filtering status code as defined in creative-status-codes.txt.
height integer Ad height in pixels.
impressionTrackingUrl[] list The set of urls to be called to record an impression. writable
kind string Resource type. This is always "adexchangebuyer#creative".
languages[] list Detected languages for this creative. Read-only. This field should not be set in requests.
nativeAd object If nativeAd is set, HTMLSnippet, videoVastXML, and the videoURL outside of nativeAd should not be set. (The videoURL inside nativeAd can be set.) writable
nativeAd.advertiser string
nativeAd.appIcon object The app icon, for app download ads.
nativeAd.appIcon.height integer
nativeAd.appIcon.url string
nativeAd.appIcon.width integer
nativeAd.body string A long description of the ad.
nativeAd.callToAction string A label for the button that the user is supposed to click.
nativeAd.clickLinkUrl string The URL that the browser/SDK will load when the user clicks the ad.
nativeAd.clickTrackingUrl string The URL to use for click tracking.
nativeAd.headline string A short title for the ad.
nativeAd.image object A large image.
nativeAd.image.height integer
nativeAd.image.url string
nativeAd.image.width integer
nativeAd.impressionTrackingUrl[] list The URLs are called when the impression is rendered.
nativeAd.logo.height integer
nativeAd.logo.url string
nativeAd.logo.width integer
nativeAd.price string The price of the promoted app including the currency info.
nativeAd.starRating double The app rating in the app store. Must be in the range [0-5].
nativeAd.store string The URL to the app store to purchase/download the promoted app.
nativeAd.videoURL string The URL of the XML VAST for a native ad. Note this is a separate field from resource.video_url.
openAuctionStatus string Top-level open auction status. Read-only. This field should not be set in requests. If disapproved, an entry for auctionType=OPEN_AUCTION (or ALL) in servingRestrictions will also exist. Note that this may be nuanced with other contextual restrictions, in which case it may be preferable to read from ServingRestrictions directly.

Acceptable values are:
  • "APPROVED"
  • "CONDITIONALLY_APPROVED"
  • "DISAPPROVED"
  • "NOT_CHECKED"
  • "UNKNOWN"
productCategories[] list Detected product categories, if any. Each category is represented by an integer as defined in ad-product-categories.txt. Read-only. This field should not be set in requests.
restrictedCategories[] list All restricted categories for the ads that may be shown from this snippet. Each category is represented by an integer as defined in the ad-restricted-categories.txt. writable
sensitiveCategories[] list Detected sensitive categories, if any. Each category is represented by an integer as defined in ad-sensitive-categories.txt. Read-only. This field should not be set in requests.
servingRestrictions[] list The granular status of this ad in specific contexts. A context here relates to where something ultimately serves (for example, a physical location, a platform, an HTTPS vs HTTP request, or the type of auction). Read-only. This field should not be set in requests. See the examples in the Creatives guide for more details.
servingRestrictions[].contexts[] list All known contexts/restrictions.
servingRestrictions[].contexts[].auctionType[] list Only set when contextType=AUCTION_TYPE. Represents the auction types this restriction applies to.
servingRestrictions[].contexts[].contextType string The type of context (e.g., location, platform, auction type, SSL-ness).

Acceptable values are:
  • "ALL"
  • "AUCTION_TYPE"
  • "LOCATION"
  • "PLATFORM"
  • "SSL_REQUEST"
  • "UNKNOWN_TYPE"
servingRestrictions[].contexts[].geoCriteriaId[] list Only set when contextType=LOCATION. Represents the geo criterias this restriction applies to. Impressions are considered to match a context if either the user location or publisher location matches a given geoCriteriaId.
servingRestrictions[].contexts[].platform[] list Only set when contextType=PLATFORM. Represents the platforms this restriction applies to.
servingRestrictions[].disapprovalReasons[] list The reasons for disapproval within this restriction, if any. Note that not all disapproval reasons may be categorized, so it is possible for the creative to have a status of DISAPPROVED or CONDITIONALLY_APPROVED with an empty list for disapproval_reasons. In this case, please reach out to your TAM to help debug the issue.
servingRestrictions[].disapprovalReasons[].details[] list Additional details about the reason for disapproval.
servingRestrictions[].disapprovalReasons[].reason string The categorized reason for disapproval.

Acceptable values are:
  • "ABORTION"
  • "ADULT_IMAGE_OR_VIDEO"
  • "AD_SIZE_DOES_NOT_MATCH_AD_SLOT"
  • "AUTOMATED_AD_CLICKING"
  • "BAD_URL_LEGAL_DISAPPROVAL"
  • "BLANK_CREATIVE"
  • "BROKEN_URL"
  • "CLICK_TO_DOWNLOAD_NOT_AN_APP"
  • "CLINICAL_TRIAL_RECRUITMENT"
  • "CONTRACEPTIVES"
  • "COUNTERFEIT_DESIGNER_GOODS"
  • "DANGEROUS_PRODUCTS_DRUGS"
  • "DANGEROUS_PRODUCTS_EXPLOSIVES"
  • "DANGEROUS_PRODUCTS_GUNS"
  • "DANGEROUS_PRODUCTS_KNIVES"
  • "DANGEROUS_PRODUCTS_TOBACCO"
  • "DANGEROUS_PRODUCTS_WEAPONS"
  • "DESTINATION_EXPERIENCE"
  • "DESTINATION_SITE_DOES_NOT_ALLOW_GOING_BACK"
  • "DESTINATION_SITE_NOT_CRAWLABLE_ROBOTS_TXT"
  • "DESTINATION_URLS_UNDECLARED"
  • "DESTINATION_URL_SITE_NOT_CRAWLABLE"
  • "DIRECT_DOWNLOAD_IN_AD"
  • "DYNAMIC_DNS_AT_DESTINATION_URL"
  • "DYSFUNCTIONAL_PROMOTION"
  • "ENABLING_DISHONEST_BEHAVIOR"
  • "EXPANDABLE_DIRECTION_NOT_SUPPORTED"
  • "EXPANDABLE_FUNCTIONALITY"
  • "EXPANDABLE_INCORRECT_DIRECTION"
  • "EXPANDABLE_INVALID_VENDOR"
  • "FOURTH_PARTY_BROWSER_COOKIES"
  • "GAINING_AN_UNFAIR_ADVANTAGE"
  • "GAMING_THE_GOOGLE_NETWORK"
  • "INACCURATE_AD_TEXT"
  • "INACCURATE_REVIEW_EXTENSION"
  • "INAPPROPRIATE_CONTENT"
  • "INCORRECT_AD_TECHNOLOGY_DECLARATION"
  • "INCORRECT_DESTINATION_URL_DECLARATION"
  • "INCORRECT_IMAGE_LAYOUT"
  • "INCORRECT_REMARKETING_DECLARATION"
  • "INVALID_BIDDING_METHOD"
  • "INVALID_FOURTH_PARTY_CALL"
  • "INVALID_INTEREST_BASED_AD"
  • "INVALID_REMARKETING_LIST_USAGE"
  • "INVALID_RTB_PROTOCOL_USAGE"
  • "INVALID_SSL_DECLARATION"
  • "INVALID_URL_PROTOCOL"
  • "IRRELEVANT_IMAGE_OR_VIDEO"
  • "KCDSP_REGISTRATION"
  • "LANDING_PAGE_DISABLED"
  • "LANDING_PAGE_ERROR"
  • "LENGTH_OF_IMAGE_ANIMATION"
  • "LSO_OBJECTS"
  • "MALWARE_SUSPECTED"
  • "MAXIMUM_DOWNLOAD_SIZE_EXCEEDED"
  • "MAXIMUM_NUMBER_OF_COOKIES_EXCEEDED"
  • "MAXIMUM_NUMBER_OF_HTTP_CALLS_EXCEEDED"
  • "MEDIA_NOT_FUNCTIONAL"
  • "MISLEADING_CLAIMS_IN_AD"
  • "MISLEADING_PROMOTIONS"
  • "MISUSE_BY_OMID_SCRIPT"
  • "MISUSE_OF_PERSONAL_INFORMATION"
  • "NEED_CERTIFICATES_TO_ADVERTISE_IN_CHINA"
  • "NON_SSL_COMPLIANT"
  • "NON_WHITELISTED_OMID_VENDOR"
  • "NOT_FAMILY_SAFE"
  • "NO_BORDER"
  • "OMISSION_OF_RELEVANT_INFORMATION"
  • "PERSONAL_LOANS"
  • "PHARMA_GAMBLING_ALCOHOL_NOT_ALLOWED"
  • "POOR_IMAGE_OR_VIDEO_QUALITY"
  • "POP_UP"
  • "PROBLEM_WITH_CLICK_MACRO"
  • "PROFESSIONAL_STANDARDS"
  • "RAW_IP_ADDRESS_IN_SNIPPET"
  • "RESTRICTED_POLITICAL_CONTENT"
  • "RESTRICTED_PRODUCTS"
  • "SENSITIVE_EVENTS"
  • "SEXUALLY_EXPLICIT_CONTENT"
  • "SHOCKING_CONTENT"
  • "TECHNICAL_REQUIREMENTS"
  • "UNACCEPTABLE_CONTENT"
  • "UNACCEPTABLE_CONTENT_SOFTWARE"
  • "UNACCEPTABLE_IMAGE_CONTENT"
  • "UNACCREDITED_PET_PHARMACY"
  • "UNAUTHORIZED_COOKIE_ON_GOOGLE_DOMAIN"
  • "UNAVAILABLE_PROMOTIONS"
  • "UNCLEAR_OR_IRRELEVANT_AD"
  • "UNDECLARED_FLASH_OBJECTS"
  • "UNDECLARED_RESTRICTED_CONTENT"
  • "UNSUPPORTED_CONTENT"
  • "UNSUPPORTED_FLASH_CONTENT"
  • "UNSUPPORTED_LANGUAGE"
  • "VIDEO_FUNCTIONALITY"
  • "VIDEO_INVALID_VENDOR"
  • "VIDEO_TOO_LONG"
  • "VIDEO_UNSUPPORTED_FORMAT"
  • "VIDEO_UNSUPPORTED_LENGTH"
  • "VIOLATES_JAPANESE_PHARMACY_LAW"
servingRestrictions[].reason string Why the creative is ineligible to serve in this context (e.g., it has been explicitly disapproved or is pending review).

Acceptable values are:
  • "DISAPPROVAL"
  • "PENDING_REVIEW"
  • "UNKNOWN_REASON"
vendorType[] list List of vendor types for the ads that may be shown from this snippet. Each vendor type is represented by an integer as defined in vendors.txt. writable
version integer The version for this creative. Read-only. This field may not be set in requests, and is incremented automatically on every API upload. This field has a maximum limit of 20; subsequent attempts to update will result in an API error response. 
videoURL string The URL to fetch a video ad. If set, HTMLSnippet, videoVastXML, and nativeAd should not be set. Note, this is different from resource.native_ad.video_url above. writable
videoVastXML string The contents of a VAST document for a video ad. This document should conform to the VAST 2.0 or 3.0 standard. If set, HTMLSnippet, videoURL, and nativeAd and should not be set. writable
width integer Ad width in pixels.

Methods

addDeal
Add a deal id association for the creative.
get
Gets the status for a single creative. A creative will be available 30-40 minutes after submission.
insert
Inserts a new creative into Google's creative verification pipeline.
list
Retrieves a list of the authenticated user's active creatives. A creative will be available 30-40 minutes after submission.
listDeals
Lists the external deal ids associated with the creative.
removeDeal
Remove a deal id associated with the creative.