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:

1. 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.

2. BidSwitch then forms a list of creatives that are pending approval for each Supplier.

3. 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

1. Get your API Access Token. This requires creating an API user in the myBidSwitch UI, see the Getting API Credentials section for details.

2. 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:

1. From the BidSwitch UI, select Users ‣ Add User.

2. 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.

1. Log into the BidSwitch single sign-on management portal: https://uauth.bidswitch.com/uauth/settings/#sso

2. Select OAuth2 Access Token ‣ New Permanent Token

3. Set the scope to api.bidswitch.com, and Create

4. Save 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.

Auth Token POST Details

Endpoint Info	Description
endpoint	https://uauth.iponweb.com/oauth2/token/
Method	POST
headers	Content-Type and Accept {'Content-Type': 'application/x-www-form-urlencoded', 'accept': 'application/json'}
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. "scope=service_id=api.bidswitch.com"

Example Using Curl

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/'

Example Using Python Requests

#!/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)

Sample AUTH Response

{
  "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 the auth header, username, or password 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 than GET 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.

CA Response Format

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 next_page field value in each response. To receive the complete list, you need to make GET requests until you reach the page which does not have a next_page field.

{
   "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.

Creative Object Properties

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 {DSP_ID}_{Creative_ID}, for example 70_650029457 or 79_0RsSUxZety0O1.
ssps	object	An object where: The key value is the name of the Supplier where the creative has been registered, or has been submitted for approval. The value is the creative version object, which is a set of versions of this creative registered on the Supplier side. See the Creative Version Object.

{
    "id": "string",
    "ssps": {
        "<ssp1 name, string>": "<creative version object>",
        "<ssp2 name, string>": "<creative version object>"
    }
}

Creative Version Object

Creative Version Object Properties

Value	Type	Description
status	string	The status of the creative, which can take one of the following values: "approved" Verified by the Supplier and approved "banned" Verified and disapproved "not submitted" The creative is scheduled to be sent to the Supplier "not verified" Registered but hasn’t been verified by the Supplier service "partially approved" The creative has been approved with exceptions. Some sites or publishers will not display it. "submitted" The creative has been registered on the Supplier side but the status hasn’t been checked yet "unknown" - The status can’t be provided for some reason. (The creative was deactivated by the Supplier, or its status cannot be interpreted correctly)
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.

Params Object

Value	Type	Description
params	object	See following table.

Params Object Options

SSP	Parameters
Google AdX	None
OpenX	Site ID ("site")
YAX	None
YieldOne	Site ID ("site"), Publisher ID ("publisher")

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#resource

• next_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

• Python 3 Example Script

• Ruby Example Script

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