Creatives

The API provides methods to:

Submitted creatives can be used when placing a bid on a pretargeting match, but only when either the openAuctionStatus or dealsStatus is in an APPROVED or CONDITIONALLY_APPROVED state.

Submit creative for verification

All creatives must be approved by Google. You can submit a new creative to Google's verification pipeline by sending an HTTP POST request to the Creatives Resource URI. The URI has the following format:

https://www.googleapis.com/adexchangebuyer/v1.4/creatives/

Creative types

Depending on what is sent in the request body, a creative can be one of the three supported types identified below:

HTML snippet creative

You can submit an HTML snippet creative for review by providing an HTML string to the creative's HTMLSnippet property. If set, neither the videoUrl nor nativeAd property should be set.

Request

POST https://www.googleapis.com/adexchangebuyer/v1.4/creatives/
Authorization: Bearer /* auth token here */
Content-Type: application/json

{
  "accountId": 123456789,
  "buyerCreativeId": "test creative 1",
  "HTMLSnippet": "<html><body><a href='http://www.example.com'>Hi there!</a></body></html>",
  "clickThroughUrl": [ "http://www.example.com" ],
  "width": 300,
  "height": 250,
  "advertiserName": "google"
}

Response

In addition to the request fields, if we have seen the creative before, the response may contain product and sensitive categories, as well as any advertiser IDs that we have automatically detected.

{
  "productCategories": [-1],
  "kind": "adexchangebuyer#creative",
  "width": 300,
  "clickThroughUrl": ["http://www.example.com"],
  "height": 250,
  "HTMLSnippet": '<html><body><a href="http://www.example.com">Hi there!</a></body></html>',
  "buyerCreativeId": "test creative 1",
  "sensitiveCategories": [-1],
  "accountId": "123456789",
  "advertiserId": "5289"
}

Video creatives

You can submit a video creative for review by providing the URL as a string to the videoUrl property. If set, neither the HTMLSnippet nor nativeAd property should be set. The URL provided should respond with a VAST XML document. For more details on the requirements of video creatives, read how to serve video ad units.

Request

POST https://www.googleapis.com/adexchangebuyer/v1.4/creatives/
Authorization: Bearer /* auth token here */
Content-Type: application/json

{
  "accountId": 123456789,
  "buyerCreativeId": "test creative 2",
  "videoUrl": "https://some-ad-server.com/v/1",
  "clickThroughUrl": [ "http://www.example.com" ],
  "advertiserName": "google"
}

Response

{
  "kind": "adexchangebuyer#creative",
  "clickThroughUrl": ["http://www.example.com"],
  "height": 0,
  "videoUrl": "https://some-ad-server.com/v/1",
  "buyerCreativeId": "test creative 2",
  "sensitiveCategories": [-1],
  "accountId": "123456789",
  "advertiserId": "5289"
  "version": 1,
  "apiUploadTimestamp": "2015-12-22T20:45:57.911Z"
  "width": 0,
}

Native Ad Creatives

You can submit a native ad creative for review by setting the nativeAd property. If set, neither the HTMLSnippet nor videoUrl property should be set.

Request

POST https://www.googleapis.com/adexchangebuyer/v1.4/creatives/
Authorization: Bearer /* auth token here */
Content-Type: application/json

{
  "accountId": 53728410,
  "advertiserName": "Google",
  "buyerCreativeId": "test-native-1",
  "clickThroughUrl": [
    "https://www.google.com"
  ],
  "height": 250,
  "width": 300,
  "nativeAd": {
    "advertiser": "Google",
    "body": "This is a test.",
    "headline": "test-native-1",
    "callToAction": "Test Now!",
    "image": {
      "url": "http://www.test-server.com/i/1",
      "height": 250,
      "width": 300
    },
    "logo": {
      "url": "http://www.test-server.com/l/1",
      "height": 50,
      "width": 50
    },
    "appIcon": {
      "url": "http://www.test-server.com/a/1",
      "height": 128,
      "width": 128
    },
    "starRating": 5
  }
}

Response

{
  "kind": "adexchangebuyer#creative",
  "accountId": 53728410,
  "buyerCreativeId": "mts-test-native-1",
  "version": 2,
  "apiUploadTimestamp": "2015-12-29T21:15:33.089Z",
  "nativeAd": {
    "headline": "mts-test-native-1",
     "body": "This is a test.",
     "callToAction": "Test Now!",
     "advertiser": "Google",
     "image": {
       "url": "http://www.test-server.com/i/1",
       "width": 300,
       "height": 250
     },
     "logo": {
       "url": "http://www.test-server.com/l/1",
       "width": 50,
       "height": 50
       },
     "appIcon": {
       "url": "http://www.test-server.com/a/1",
       "width": 128,
       "height": 128
     },
   "starRating": 5
  },
  "clickThroughUrl": [
    "https://www.google.com"
  ],
  "width": 0,
  "height": 0,
  "advertiserName": "Google"
  }

See the following code samples that use client libraries to submit creatives for verification:

Detect and correct creative resource

Ad Exchange defines the Correction message and CorrectionType (see snippet-status-report-proto.txt) to detect and correct a creative that is disapproved because:

  • The creative's declared vendors do not match the detected vendors.
    Ad Exchange inserts the detected vendors to allow the creative to serve on inventory that opts in to these vendors.
  • The creative declares the SSL attribute but is not SSL-compliant.
    Ad Exchange removes the SSL declaration to allow the creative to serve on non-SSL inventory only.
  • The creative declares that it was Flash-free but contains Flash.
    Ad Exchange removes the Non-Flash declaration to allow the creative to serve on Flash-capable inventory only.

The creative resource will have a list of Correction messages, one for each correction to the creative. For example:

{
  "openAuctionStatus": "APPROVED",
  "dealsStatus": "APPROVED",
  "buyerCreativeId": "test creative 1",
  ...
  "correction": {
    "type": "SSL_ATTRIBUTE",
    "detail": "Removed attributes: 47"
  },
  "correction": {
    "type": "VENDOR_IDS",
    "detail": "Added vendors: 203, 358"
  }
}

Check status of submitted creative

You can check on the status of a creative that has been submitted to Google's verification pipeline by sending an HTTP GET request to the Creatives Resource URI. The URI has the following format:

https://www.googleapis.com/adexchangebuyer/v1.4/creatives/accountId/buyerCreativeId

Request

Here is an example:

GET https://www.googleapis.com/adexchangebuyer/v1.4/creatives/12345678/test%20creative%201
Authorization: Bearer /* auth token here */
Accept-Encoding: gzip, deflate
Accept: application/json

Response

If successful, this method returns a Creatives resource in the response body. If your creative is still being reviewed, you will see the NOT_CHECKED status. For possible creative statuses, see the openAuctionStatus field documentation.

v1.4

The status and disapprovalReasons fields have been replaced by openAuctionStatus and dealsStatus, and servingRestrictions. These provide a more granular view of the conditions in which your creative can be served.

{
  "productCategories": [
    10014,
    10015,
    10113,
    10121,
    10021
  ],
  "advertiserId": ["5289"],
  "kind": "adexchangebuyer#creative",
  "agencyId": "1",
  "width": 468,
  "clickThroughUrl": ["https://www.example.com"],
  "height": 60,
  "advertiserName": "google",
  "HTMLSnippet": "<html><body><a href=&quot;https://www.example.com&quot;>Hi there!</a></body></html>",
  "openAuctionStatus": "APPROVED",
  "buyerCreativeId": "test_ssl_mobile",
  "attribute": [
      47,
      50
  ],
  "dealsStatus": "APPROVED",
  "accountId": 123456789
}

Interpreting the servingRestrictions field

The servingRestrictions field is a list where each element identifies the contexts in which the creative will be filtered for a reason. For elements with multiple contexts, you can interpret the overall context as being the logical AND of each; for example, contextTypes of AUCTION_TYPE and LOCATION combine to indicate that the restriction applies to a specific auction type for users in a certain region. To interpret the overall set of restrictions, you should logically OR each element of servingRestrictions. In the example above, one of the restrictions indicates that the entire open auction is restricted because of a disapproval. As a result, the openAuctionStatus for this creative is DISAPPROVED. In contrast, the dealsStatus is CONDITIONALLY_APPROVED because the only restriction for the creative in deals is that it can’t be used in response to SSL bid requests. Note that for cases where a creative has been DISAPPROVED, the disapprovalReason has been moved to the servingRestrictions element.

The following are examples of the servingRestrictions field as you might see in a response:

Invalid SSL

Invalid SSL

"servingRestrictions": [{
  "contexts": [{
    "contextType": "SSL_REQUEST"
  }],
  "reason": "DISAPPROVAL",
  "disapprovalReasons": [{
    "reason": "INVALID_SSL_DECLARATION",
    "details": ["Not SSL compliant."]
  }]
}]

Disapproved

Disapproved + Invalid SSL

"servingRestrictions": [
  {
    "contexts": [{
      "contextType": "AUCTION_TYPE",
      "auctionType": ["OPEN_AUCTION"]
    }],
    "reason": "DISAPPROVAL",
    "disapprovalReasons": [{
      "reason": "DESTINATION_URL_SITE_NOT_CRAWLABLE",
      "details": [
        "The snippet's destination URL could not be crawled"
      ]
    }]
  },
  {
    "contexts": [{"contextType": "SSL_REQUEST"}],
    "reason": "DISAPPROVAL",
    "disapprovalReasons": [{
      "reason": "INVALID_SSL_DECLARATION",
      "details": ["Not SSL compliant."]
    }]
  }
]

Pending

Disapproved + pending region reviews

"servingRestrictions": [
  {
    "contexts": [{
      "contextType": "AUCTION_TYPE",
      "auctionType": ["OPEN_AUCTION"]
    }],
    "reason": "DISAPPROVAL",
    "disapprovalReasons": [{
      "reason":"BLANK_CREATIVE"
    }]
  },
  {
    "contexts": [
      {
        "contextType": "AUCTION_TYPE",
        "auctionType": ["OPEN_AUCTION"]
      },
      {
        "contextType": "LOCATION",
        "geoCriteriaId": [2156]
      }
    ],
    "reason": "PENDING_REVIEW"
  },
  {
    "contexts": [
      {
        "contextType": "AUCTION_TYPE",
        "auctionType": ["OPEN_AUCTION"]
      },
      {
        "contextType": "LOCATION",
        "geoCriteriaId": [2643]
      }
    ],
    "reason": "PENDING_REVIEW"
  }
]

Restricted in China

Restricted in China

"servingRestrictions": [
  {
    "contexts": [{"contextType": "SSL_REQUEST"}],
    "reason": "DISAPPROVAL",
    "disapprovalReasons": [{
      "reason": "INVALID_SSL_DECLARATION",
      "details": ["Not SSL compliant."]
    }]
  },
  {
    "contexts": [{
      "contextType": "LOCATION",
      "geoCriteriaId": [2156]
    }],
    "reason": "DISAPPROVAL"
  },
  {
    "contexts": [
      {
        "contextType": "AUCTION_TYPE",
        "auctionType": ["OPEN_AUCTION"]
      },
      {
        "contextType": "LOCATION",
        "geoCriteriaId": [2643]
      }
    ],
    "reason": "PENDING_REVIEW"
  }
]

Flash detected

Restricted for IOS + Android (flash detected)

"servingRestrictions": [
  {
    "contexts": [{
      "contextType": "PLATFORM",
      "platform": ["ANDROID"]
    }],
    "reason": "DISAPPROVAL",
    "disapprovalReasons": [{
      "reason": "UNDECLARED_FLASH_OBJECTS",
      "details": ["Detected Flash on Android."]
    }]
  },
  {
    "contexts": [{
      "contextType":  "PLATFORM",
      "platform": ["IOS"]
    }],
    "reason": "DISAPPROVAL",
    "disapprovalReasons": [{
      "reason": "UNDECLARED_FLASH_OBJECTS",
      "details": ["Detected Flash on iOS."]
    }]
  }
]

v1.2 - v1.3

{
  "status": "APPROVED",
  "productCategories": [
    10014,
    10015,
    10113,
    10121,
    10021
  ],
  "kind": "adexchangebuyer#creative",
  "agencyId": "1",
  "width": 468,
  "clickThroughUrl": ["https://www.example.com"],
  "height": 60,
  "HTMLSnippet": "<html><body><a href=&quot;https://www.example.com&quot;>Hi there!</a></body></html>",
  "buyerCreativeId": "test_ssl_mobile",
  "attribute": [
      47,
      50
  ],
  "accountId": "123456789",
  "advertiserId": ["5289"]
}

Retrieve list of active creatives

Use the list method to retrieve a list of the authenticated user's active creatives. Creatives will not appear in this list immediately after submission. It typically takes 30 to 40 minutes for newly submitted creatives to turn up on the list.

Optional parameters of the list method allow you to set the maximum number of Creatives resources to return each time you call the method. You can optionally filter the method by the status parameters in order to view only those ads that have been approved, those ads that have been disapproved, or those ads that have not yet been checked.

The list method defaults to returning information for a maximum of 100 creatives each time it is called. You can control the maximum number by passing a value in the maxResults parameter. The maxResults parameter can be set from 1 to 1,000 inclusive.

Each call to the list method returns data for up to maxResults creatives (or 100 if no value was passed for the maxResults parameter). If there is data for more creatives, the pageToken parameter will be returned with the data. Pass pageToken on subsequent calls in order to retrieve subsequent pages of the list. If data has been returned for all creatives, then pageToken value will be null.

For example, if there were 30 creatives and you have set maxResults to 10, you would pass the token to the list method on the second and third calls to retrieve data for the remaining creatives.

Retrieve the list by sending an HTTP GET request to the Creatives Resource URI. The URI has the following format:

GET https://www.googleapis.com/adexchangebuyer/v1.4/creatives

Request

Here is an example that uses some of the optional parameters to filter the response. You can learn more about the available parameters in the Creatives reference documentation.

v1.4

GET https://www.googleapis.com/adexchangebuyer/v1.4/creatives?maxResults=10&openAuctionStatusFilter=approved&dealsStatusFilter=approved&key={YOUR_API_KEY}

Authorization:  Bearer /* auth token here */
X-JavaScript-User-Agent:  Google APIs Explorer

v1.2 - v1.3

GET https://www.googleapis.com/adexchangebuyer/v1.3/creatives?maxResults=10&statusFilter=approved&key={YOUR_API_KEY}

Authorization:  Bearer /* auth token here */
X-JavaScript-User-Agent:  Google APIs Explorer

Response

If successful, this method returns a list of Creatives resources in the response body:

v1.4

{
 "kind": "adexchangebuyer#creativesList",
 "items": [
  {
   "kind": "adexchangebuyer#creative",
   "accountId": 987654321,
   "buyerCreativeId": "test creative 1",
   "sensitiveCategories": [
     -1
   ],
   "productCategories": [
     -1
   ],
   "advertiserId": [
     "5289"
   ],
   "height": 250,
   "width": 300,
   "clickThroughUrl": [
     "http://www.example.com"
   ],
   "dealsStatus":"APPROVED",
   "openAuctionStatus": "APPROVED",
   "advertiserName":"google",
   "HTMLSnippet": "<html><body><a href=&quot;https://my.adserver.com/click?google_click_url=%%CLICK_URL_ESC%%&quot;>Hola mundo!</a></body></html>"
  },
  {
   "kind": "adexchangebuyer#creative",
   "accountId": 987654321,
   "buyerCreativeId": "test creative 2",
   "sensitiveCategories": [
     -1
   ],
   "productCategories": [
     -1
   ],
   "advertiserId": [
     "5289"
   ],
   "height": 300,
   "width": 250,
   "clickThroughUrl": [
     "http://www.example.com"
   ],
   "dealsStatus":"APPROVED",
   "openAuctionStatus": "APPROVED",
   "advertiserName":"google",
   "HTMLSnippet": "<html><body><a href=&quot;https://my.adserver.com/click?google_click_url=%%CLICK_URL_ESC%%&quot;>こんにちは世界!</a></body></html>"
  }
 ]
}

v1.2 - v1.3

{
 "kind": "adexchangebuyer#creativesList",
 "items": [
  {
   "kind": "adexchangebuyer#creative",
   "accountId": 123456789,
   "buyerCreativeId": "test creative 1",
   "sensitiveCategories": [
     -1
   ],
   "productCategories": [
     -1
   ],
   "advertiserId": [
     "5289"
   ],
   "height": 250,
   "width": 300,
   "clickThroughUrl": [
     "http://www.example.com"
   ],
   "status":"APPROVED",
   "advertiserName":"google",
   "HTMLSnippet": "<html><body><a href=&quot;https://my.adserver.com/click?google_click_url=%%CLICK_URL_ESC%%&quot;>Hola mundo!</a></body></html>"
  },
  {
   "kind": "adexchangebuyer#creative",
   "accountId": 123456789,
   "buyerCreativeId": "test creative 2",
   "sensitiveCategories": [
     -1
   ],
   "productCategories": [
     -1
   ],
   "advertiserId": [
     "5289"
   ],
   "height": 300,
   "width": 250,
   "clickThroughUrl": [
     "http://www.example.com"
   ],
   "status":"APPROVED",
   "advertiserName":"google",
   "HTMLSnippet": "<html><body><a href=&quot;https://my.adserver.com/click?google_click_url=%%CLICK_URL_ESC%%&quot;>Hello, World!</a></body></html>"
  }
 ]
}

Send feedback about...

Buyer REST API
Buyer REST API