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. Click the button below to see response information for the version you're using.

v1.4

v1.2 - v1.3

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. Click the button below to see request information for the version you're using.

v1.4

v1.2 - v1.3

Response

If successful, this method returns a list of Creatives resources in the response body. Click the button below to see response information for the version you're using.

v1.4

v1.2 - v1.3

Send feedback about...

Buyer REST API
Buyer REST API