Creative Approval Reporting API¶
BidSwitch acts as an integration layer between the creative approval services of certain Suppliers that require approval and Buyers buying from them. To submit creatives to a Supplier. BidSwitch also regularly pulls the creative status information from each Supplier’s content authorization (CA) service and stores this in a database of statuses. This data is accessible any time using the Creative Approval Endpoint. To get creatives approved, BidSwitch uses the following steps:
BidSwitch first ensures that the Buyer bid response contains all the details necessary for approval by each Supplier. It does this by gathering data from Buyer bid responses.
BidSwitch identifies new creatives that have not yet been approved using each creative’s unique hash. These are then pushed to the corresponding Supplier creative approval service.
For disapproved creatives that have been fixed, BidSwitch recognised them by their unique/changed hash and resubmit them to be rechecked.
Process Overview¶
Get your API Access Token. This may require creating an API user in the myBidSwitch UI, see the API Authorization section for details.
Once you have your authorization token, you can make a request to the CA endpoint using the following
curl
example. See the Get CA Status Example section for Python and Ruby example scripts.
curl -H "Accept:application/json" -H 'Authorization:Bearer <Your-token-here>' \
-H 'Content-Type:application/json' \
https://api.bidswitch.com/creativeapproval/v1.0/dsp/<your-DSP-ID-here>/creative-status/
Creative Approval Endpoint¶
Buyers can get a Creative Approval report using an HTTP GET request to the
following endpoint. You can use the page_size
parameter to vary the number of
creative objects you receive in a response. For more information, see the
Response Format description below.
<!-- BidSwitch Endpoint -->
https://api.bidswitch.com/creativeapproval/v1.0/dsp/<dsp-id>/creative-status/
<!-- Example request with page size -->
https://api.bidswitch.com/creativeapproval/v1.0/dsp/17/creative-status/?page_size=400
Response Format¶
Each response includes zero or more creative objects packed into one response as shown below in the below example.
Value |
Type |
Description |
---|---|---|
creatives |
array of objects |
Contains the details of each creative it an object, see the Creatives Object section. |
next_page |
string |
Contains the URL for the next set of status returns. The status
information is divided into pages of no more than 500 creative objects
each, and you have to request pages one at a time. To receive the next page, you
need to make a new HTTP GET request to the |
{
"creatives":[
"<creative object>",
"<creative object>"
],
"next_page":"https://api.bidswitch.com/api/status/<dsp_id>/?page_size=."
}
Creatives Object¶
Each creative object has the following format.
Value |
Type |
Description |
---|---|---|
id |
string |
This is the unique identifier for the creative. Note: BidSwitch prepends the
Buyer ID to the creative ID using the following syntax
|
ssps |
object |
Specifies the Suppliers to whom the creative has been submitted and the status of the creative at each. |
SSPS Object¶
Value |
Type |
Description |
---|---|---|
status |
string |
The status of the creative, which can take one of the following values:
|
reason |
string |
(optional) A human-readable note, usually describing the reasons for the creative being banned. |
params |
object |
(optional) Machine-readable information about the status. For example, it can list particular sites or publishers where the creative has been banned or approved. See the Parameters For Different Suppliers section. |
Each Supplier usually registers one version of a single creative. However some Suppliers can
also store older revisions of the same creative which may have a different status. For
instance, the response below references creative 640183
which has been stored by
Google twice, one version is approved and the other is not.
{
"creatives":[
{
"id":"640183",
"ssps":{
"google":[
{
"status":"approved"
},
{
"status":"banned",
"reason":"BROKEN_URL"
}
],
"yieldone":[
{
"status":"approved"
}
],
"openx":[
{
"status":"banned"
}
]
}
}
]
}
Parameters For Different Suppliers¶
Some Suppliers may provide additional parameters describing cases where a given
creative is approved or not. If there are parameters describing the
conditions where a creative is approved or banned by a Supplier, then the JSON
object contains the "params"
section.
In this scenario, the status in the root of the SSPS Object is the default one, and is overridden by the status of the relevant parameter.
Value |
Type |
Description |
---|---|---|
params |
object |
See following table. |
SSP |
Parameters |
---|---|
YieldOne |
Site ID ( |
Note
Any combination of parameters where at least one has the “banned” status leads to the creative being “banned” in this inventory.
In the example below the creative is banned at YieldOne by default, but it’s allowed at publishers “AAA” and “BBB” with the exception of sites “412” and “413”.
{
"yieldone": [
{
"status": "banned",
"params": {
"publisher": {
"status": "approved",
"values" : [ "AAA",
"BBB" ]
},
"site" : {
"status": "banned",
"values": ["412",
"413" ]
}
},
"reason": "Approved only at publishers 'AAA' and 'BBB', blocked at sites '412' and '413'"
}
]
}
Status of Individual Creatives¶
In addition to getting a report for all Creatives submitted, you can also query the status of an individual Creative using the following example:
<!-- URL Syntax -->
https://api.bidswitch.com/creativeapproval/v1.0/dsp/<dsp-id>/creative-status/?creative_id=<creative-id>
<!-- Individual Status Example -->
https://api.bidswitch.com/creativeapproval/v1.0/dsp/8/creative-status/?creative_id=8_16
Get CA Status Example¶
You can use the following scripts to help you get started building your own integration.
Creative Approval Responses¶
200
OK and the creative statuses are in response body.400
Bad request, indicates that a non numerical<dsp-id>
was used.401 Unauthorized
Returned if theauth header
,username
, orpassword
is wrong.403 Forbidden
Returned if the user does not have access permission.404 Not Found
Returned if the<dsp-id>
is a number, but unknown.405 Method Not Allowed
Returned if a method other thanGET
is used.500 Internal Server Error
Returned if another unexpected error occurs.