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:

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

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

  3. For disapproved creatives that have been fixed, BidSwitch recognised them by their unique/changed hash and resubmit them to be rechecked.

Process Overview

  1. Get your API Access Token. This may require creating an API user in the myBidSwitch UI, see the API Authorization section for details.

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

Getting Blocking Data
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.

CA Response Format

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 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=."
}

Creatives 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

Specifies the Suppliers to whom the creative has been submitted and the status of the creative at each.

SSPS Object

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

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.

Params Object

Value

Type

Description

params

object

See following table.

Params Object Options

SSP

Parameters

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'"
   }
]
}

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