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.

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.