Creative Approval Reporting API¶
BidSwitch acts as a mediator between the creative approval services of Buyers and Suppliers. To submit creatives to a Supplier, BidSwitch uses the following steps:
BidSwitch first ensures that the Buyer bid response contains all the data necessary for approval by each Supplier. It does this by gathering data from Buyer bid responses.
BidSwitch then forms a list of creatives that are pending approval for each Supplier.
It then pushes the data to the corresponding Supplier’s creative approval service.
BidSwitch also regularly pulls the creative status information from each Supplier’s content authorization (CA) service and stores this in a statuses database. This data is accessible any time using the Creative Approval Endpoint.
Process Overview¶
Get your API Access Token. This requires creating an API user in the myBidSwitch UI, see the Getting API Credentials section for details.
Using this Token, make a
HTTP GET
request to the Creative Approval Endpoint. The request should contain your ID.
Getting API Credentials¶
To get access credentials for the Creative Approval API, you need to create an API User Account in the myBidSwitch UI, using the following information.
Creating an API User¶
To create a user profile that can receive API Tokens, use the following steps. Once created you can get get a permanent token or request short lived temporary tokens:
From the BidSwitch UI, select
.From the User Role dropdown menu, select API Account.
Permanent Auth Tokens¶
To get a permanent auth token for your integration, use the following steps.
Log into the BidSwitch single sign-on management portal: https://uauth.bidswitch.com/uauth/settings/#sso
Select
Set the scope to
api.bidswitch.com
, and CreateSave the generated token for use with your API requests, this token must be passed in request headers
Temporary Auth Tokens¶
To get a temporary auth token for your integration, use the following steps. Make an
HTTP POST
request to the following URL. The response will contain your access token
and its expiration time. You can use this token to perform API requests until the token
expires.
Endpoint Info |
Description |
---|---|
endpoint |
|
Method |
|
headers |
Content-Type and Accept
|
username |
(Required) Your UI username |
password |
(Required) Your UI password |
scope |
(Required) The service to which your user token should grant you access,
e.g. |
curl -X POST -H 'Content-Type: application/x-www-form-urlencoded' -H 'accept: application/json' -d 'grant_type=password&username=${username}&password=${password}&scope=service_id=api.bidswitch.com' 'https://uauth.iponweb.com/oauth2/token/'
#!/usr/bin/env python3
# -*- coding: utf-8 -*-
import json
import requests
headers = {
"Content-Type": "application/x-www-form-urlencoded",
"accept": "application/json",
}
payload = {
"grant_type": "password",
"username": login, # Your UI Login
"password": password, # Your UI Password
"scope": "service_id=api.bidswitch.com",
}
token_post = requests.post(
"https://uauth.iponweb.com/oauth2/token/", params=payload, headers=headers
)
response_json = token_post.json()
token = response_json["access_token"]
print(token)
{
"token_type": "Bearer",
"scope": "api.bidswitch.com",
"access_token": "<access_token>",
"expires_in": 3600,
"last_chars": "<last chars of auth token>"
}
Making a Request
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/
Note
All URLs that used the previous CA API endpoint will continue to work:
https://ca-api.bidswitch.net/api/status/17/
Creative Approval Endpoint¶
Buyers can get a Creative Approval report using an HTTP GET request to the following endpoint.
page_size
- Using this GET parameter you can 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
HTTP Basic authentication is used for this endpoint, more information about it is available at the following link: https://tools.ietf.org/html/rfc2617#section-2
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.
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 |
object |
Contains the creative object, see the Creative 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=."
}
Creative 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 |
An object where:
|
{
"id": "string",
"ssps": {
"<ssp1 name, string>": "<creative version object>",
"<ssp2 name, string>": "<creative version object>"
}
}
Creative Version 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. |
{
"status":"string",
"reason":"string",
"params":"<object>"
}
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 Creative Version 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 |
---|---|
Google AdX |
None |
OpenX |
Site ID ( |
YAX |
None |
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'"
}
]
}
Google AdX Data API¶
This API allows Buyers to to get raw Google AdX creative statuses using a HTTP GET request to the following link.
The same authentication rules apply as described in the Creative Approval Endpoint section:
The same response criteria apply as described in the Response Format section
<!-- BidSwitch Endpoint -->
https://api.bidswitch.com/creativeapproval/v1.0/dsp/<dsp-id>/adx-status/
<!-- For Example -->
https://api.bidswitch.com/creativeapproval/v1.0/dsp/17/adx-status/?page_size=200
{
"items":[
{
"creative": "status",
"creative": "status"
}
],
"next_page":"URL"
}
page_size
Limits the total number of statuses returned with each request. The Buyer may vary the page size in a range from 1 to 1000.items
A list of raw Google AdX statuses. Each status is an object formatted according to the Google AdX spec: https://developers.google.com/ad-exchange/buyer-rest/v1.3/creatives#resourcenext_page
- The next page of creative statuses. To receive all available statuses you should recursively request all"next_page"
URLs. The last available page will not contain the"next_page"
field.
Note
The old Google AdX URL will still work with the old basic login/password
authentication
https://ca-api.bidswitch.net/api/adx-status/<dsp-id>/
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¶
The following shows the Ruby Example script.
require 'net/http'
require 'json'
# Requests an access token which is necessary for requesting any data from
# api.bidswitch.com
def get_auth_token(auth_url, username, password)
uri = URI(auth_url)
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true
req = Net::HTTP::Post.new(uri.request_uri)
req.set_form_data({
"grant_type" => "password",
"scope" => "service_id=api.bidswitch.com",
"username" => username,
"password" => password
})
res = http.request(req)
data = JSON.parse(res.body)
return data['access_token']
end
# Creates enumerator which is able to return any number of AdX statuses by
# fetching them page by page (this approach reduces memory consumption on
# large data sets).
def get_all_statuses(start_url, auth_token)
Enumerator.new do |enum|
next_page = start_url
while next_page
uri = URI(next_page)
req = Net::HTTP::Get.new(uri)
req['Authorization'] = 'Bearer ' + auth_token
res = Net::HTTP.start(uri.hostname, uri.port, :use_ssl => true) {|http|
http.request(req)
}
data = JSON.parse(res.body)
items = data['items']
for item in items
enum.yield item
end
next_page = data['next_page']
end
end
end
api_url = 'https://api.bidswitch.com/creativeapproval/v1.0/dsp/4/adx-status/'
auth_url = 'https://uauth.iponweb.com/oauth2/token/'
username = 'username'
password = 'password'
# Usage:
# example1: fetching only first 120 statuses
auth_token = get_auth_token(auth_url, username, password)
puts get_all_statuses(api_url, auth_token).take(120)
# example2: fetching and printing all statuses till the final page
i = 1
for status in get_all_statuses(api_url, auth_token)
puts i, status, ''
i += 1
end