REST API for Creative Status & Reporting

API Limitations & Best Practices

Check the Status of Creatives

The status of each individual creative is subject to change. We recommend checking the status of each of your creatives to ensure they follow these guidelines.

  • New or edited - 30 minutes after registration or after a change in content.
  • High delivery expected - if no content change, check status 3-4 times per day.
  • Regular or low delivery - check status once per day.

QPS (Queries per Second)

The QPS limit on Get-Status is 2 Requests per Second per DSP.

Each Request can accept up to 100 Creatives batched together at the Buyer level.

If checking the status of a single creative, QPS is 10-15 Requests per second.

REST API - Creatives

Use the REST API to retrieve a list of active creatives, check the status of each creative, and request a creative be re-reviewed. Below is the list of APIs available per seat.

Creative Handling Overview

All creatives go through a review process before serving for the first time and regularly thereafter. No pre-registration of creative is needed. Bidders should bid the creative in a bid response (with the bidder’s own creative id) which is automatically registered. Once the creative is approved it is eligible to be served. A bidder can fetch the status of creatives using the REST API using their creative id.

List All Since

Use this API to get creatives from a buyer that fall between a specified start date and end date.

Scheme: HTTP

Method: GET /API/V1/brxd/creatives

Content-Type: application/json

Request Parameter

Field Name

Type

Description

buyerid

String

buyer id from which status is pulled, must belong to the DSP that the user manages.

startdate

String

Format: YYYY-MM-DD, first bid date that is newer than the startdate. UTC-00:00 based.

enddate

String

Format: YYYY-MM-DD, first bid date that is older than the enddate. UTC-00:00 based.

 

Response Object

Field Name

Type

Description

 

String Array

creative ids up to 500,000

Response Status

Response Status

Reason

200

OK

401

Unauthorized. Authentication from OAuth is expired.

403

Forbidden. Can happen when buyer id is not in our system or buyer id requested is not under current user management.

Request/Response Example

GET​ https://api.yax.yahoo.com/API/V1/brxd/creatives?buyerid=111&startdate=2016-02-04

{

"adid": [

"16311-728x90",

"22145-728x90-HTML",

"13167-728x90",

"16623-728x90",

"12995-300x250",

"15902-300x250",

"22544-300x250",

"15902-728x90",

"5856-300x250-HTML",

"14691-300x100-HTML"

]

}

Trigger Creative Test

Used to trigger creative testing of a creative. The quota of this interface is 5 a day for a given user. The list of creative_ids is limited to 200 per call.

Scheme: HTTP

Method: PUT /API/V1/brxd/creatives/review

Content-Type: application/json

Request Parameter

Field Name

Type

Description

dspid*

String

dsp id that creatives are registered under.

buyerid*

String

buyer id from which status is pulled, must belong to the DSP that the user manages.

adid*

String Array

list of creative ids (separated by commas) that belong to the buyer above. If not provided, will trigger all creatives that belong to the buyer.

* = mandatory parameter (either buyer id or dsp id should be provided)

Response Object

Field Name

Type

Description

 

String Array

creative ids that have been triggered to be reviewed successfully. ID’s that could not be found won’t be returned.

Response Status

Response Status

Reason

200

OK

401

Unauthorized. Authentication from OAuth is expired.

403

Forbidden. Can happen when buyer id is not in our system, buyer id requested is not under current user management.

500

Internal server error. Possible cause - dspid not controlled by authenticated user.

503

DSP exceeded limit of 1000 creatives per day.

Request/Response Example

PUT​ ​https://api.yax.yahoo.com/API/V1/brxd/creatives/review?buyerid=111&adid=1166-728x90-HTML

{

"adid": [

"1166-728x90-HTML"

]

}

Curl example

curl -v -X PUT -H "Authorization: Bearer <token>" -H "X-Yahoo-Guid: <guid>" -H 'Content-Type: application/json' -H 'Content-Length: 0' 'https://api.yax.yahoo.com/API/V1/brxd/creatives/review?dspid=12345&adid=a-12345678’

Get Status by DSP or Buyer

All creatives are regularly reviewed. If a creative violates the exchange standard, it is permanently banned and not allowed to participate in any auction. The API allows buyers to retrieve the status of their creatives registered with the exchange and the associated tags.

Use this API to get the status information for specific buyers and creatives.

Scheme: HTTP

Method: GET /API/V1/brxd/creatives/review

Content-Type: application/json

Request Parameter

Field Name

Type

Description

dspid*

String

dsp id that creatives are registered under

buyerid*

String

buyer id from which status is pulled, must belong to the DSP that the user manages.

adid*

String Array

creative ids up to 100

* = mandatory parameter (either buyer id or dsp id should be provided)

Response Object: Array of object for each creative

Response Status

Response Status

Reason

200

OK

401

Unauthorized. Authentication from OAuth is expired.

403

Forbidden. Can happen when buyer id is not in our system, buyer id requested is not under current user management.

500

Internal server error. Possible cause - dspid not controlled by authenticated user.

503

DSP exceeded limit of 1000 creatives per day.

Object Array

Field Name

Type

Description

adid

string

creative id

Status

string

possible values returned - ‘ACTIVE, ‘INACTIVE’

Review status

string

current status of the creative - 'PENDING_REVIEW','IN_AUTO_REVIEW','CLEAN','BAN'

tags

object array

an array of tags that apply to the creative

Tag Object

Field Name

Type

Description

id

long

ID of the tag

name

string

name of the tag

banned

boolean

true if the tag is banned

Creative Status

Creative Status

Description

Pending Review

The creative is queued up to be reviewed or re-reviewed.

In Auto-Review

The creative is being reviewed or re-reviewed.

Clean

The creative has passed all required reviews and can participate in auctions.

Banned

The creative has been banned (reason stated) and is not allowed to participate in any auction.

Request/Response Example

GET https://api.yax.yahoo.com/API/V1/brxd/creatives/review?dspid=10110&adid=gk2wvslr

{

"result": [

{

"adid": "gk2wvslr",

"status": "ACTIVE",

"reviewstatus": "BAN",

"tags": [

{

"id": 159,

"name": "Loads 3rd-party content",

"banned": false

},

{

"id": 262,

"name": "Contains banned URL",

"banned": true

}

]

}

]

}

Curl Example

curl -v -H "Authorization: Bearer <auth token>" -H "X-Yahoo-Guid: <guid>" -H "Content-Type: application/json" "​https://api.yax.yahoo.com/API/V1/brxd/creatives/review?dspid=​<yahoo provided dspid>&adid=<DSP’s Creative ID>"

DSP Level Queries

Recommendation

  • Suggested maximum QPS across all APIs is 50 queries per second
  • DSP can query up to 100 creative IDs per call to the Get Status API (aka creative/review)
  • Suggested frequency to query for status
    • For new creatives, or creatives with content changes - 1 hour after initial bid
    • For all other creatives, up to 4 times per day
  • All “List” APIs have a maximum response size of 500K creatives. Please construct the query with appropriate date ranges to stay under this limit.
  • Querying with DSP ID vs. Buyer ID
    • In oRTB, creatives are registered at the DSP, so we recommend that all queries include DSP ID parameter instead of Buyer ID. Querying at Buyer ID will continue to work if the creative is unique to a buyer (i.e. not shared across buyers within the DSP).

List All Since by DSP or Buyer

Use this API returns all DSP-Creative-Ids (Active & Inactive) of a ​buyer ​or​ DSP ​registered between the specified Start-Time and End-Time.

Scheme: HTTP

Method: GET /API/V1/brxd/creatives

Content-Type: application/json

Request Parameter

Field Name

Type

Description

buyerid*

String

buyer id to get status from, must belong to the DSP that the user manages

dspid*

String

dsp id that creatives are registered under

startdate

String

format: YYYY-MM-DD, first bid date that is larger/newer than the startdate. UTC-00:00 based.

enddate

String

format: YYYY-MM-DD, first bid date that is smaller/older than the enddate. UTC-00:00 based.

* = mandatory, otherwise optional

Response Object

Field Name

Type

Description

 

String Array

creative ids up to 500,000

Request/Response Example

GET https://api.yax.yahoo.com/API/V1/brxd/creatives?dspid=10110&startdate=2017-03-01&enddate=2017-03-02

{

"adid": [

"171057140321",

"22145-728x90-HTML",

"13167-728x90",

"16623-728x90",

"12995-300x250",

"15902-300x250",

"22544-300x250",

"15902-728x90",

"5856-300x250-HTML",

"14691-300x100-HTML"

]

}

List All Active by DSP

Use this API to get creatives for a specific DSP Active between a specified start date and end date.

Scheme: HTTP

Method: GET /API/V1/brxd/creatives/active

Content-Type: application/json

Request Parameter

Field Name

Type

Description

dspid*

String

dsp id that creatives are registered under

startdate

String

format:YYYY-MM-DD, first bid date that is larger/newer than the startdate. UTC-00:00 based.

enddate

String

format:YYYY-MM-DD, first bid date that is smaller/older than the enddate. UTC-00:00 based.

* = mandatory, otherwise optional

Response Object

Field Name

Type

Description

 

String Array

creative ids up to 500,000

Request/Response Example

GET https://api.yax.yahoo.com/API/V1/brxd/creatives/active?dspid=10110&startdate=2017-03-01&enddate=2017-03-02

{

"adid": [

"171057140321",

"22145-728x90-HTML",

"13167-728x90",

"16623-728x90",

"12995-300x250",

"15902-300x250",

"22544-300x250",

"15902-728x90",

"5856-300x250-HTML",

"14691-300x100-HTML"

]

}

List All Banned by DSP

Use this API to get all ​Banned​ creatives for a specific DSP (may include inactive creatives).

Scheme: HTTP

Method: GET /API/V1/brxd/creatives/banned

Content-Type: application/json

Request Parameter

Field Name

Type

Description

dspid*

String

dsp id that creatives are registered under

* = mandatory, otherwise optional

Response Object

Field Name

Type

Description

 

String Array

creative ids up to 500,000

Request/Response Example

GET https://api.yax.yahoo.com/API/V1/brxd/creatives/banned?dspid=10007

{

"adid": [

"34982346293",

]

}