Supplier Discrepancy API

The Discrepancy Reporting API is used to upload a daily report about the previous day’s activity so that differences between the numbers reported by BidSwitch and the reporting Supplier can be monitored. Use the information in the following sections to set up your discrepancy monitoring with BidSwitch.

• Process Overview
• Getting API Credentials
• Uploading a Discrepancy Report
• Uploading Script
• Upload Report Format
• Example Reports
• Upload Response

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 POST request to the BidSwitch discrepancy endpoint. The post request should contain your platform type and partner ID in the URL, and be in JSON. See the Uploading a Discrepancy Report section for details.

Note

• If you upload several reports during one day, only the last one uploaded is going to be processed. So if you need to do this, use the Several Days report format.
• An Uploading Script is available.

Getting API Credentials

To get access credentials for the Discrepancy Reporting 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:

1. From the BidSwitch UI, select Users ‣ Add User
2. From the User Role dropdown menu, select API Account.

Getting an API Auth Token

To get your API token, make a HTTP POST request to the following URL. The response will contain your access token.

https://uauth.iponweb.com/oauth2/token/

The POST request must contain the following fields

grant_type=password
scope=service_id=api.bidswitch.com
username=<USERNAME> <!-- Your BidSwitch UI login -->
password=<PASSWORD> <!-- Your Bidswitch UI password -->

Authorization Response

{
  "token_type": "Bearer",
  "scope": "service_id=api.bidswitch.com",
  "access_token": "<your token>",
  "expires_in": 3600
}

Equivalent request via curl command:

$ curl https://uauth.iponweb.com/oauth2/token/ \
  --request POST \
  --data "grant_type=password" \
  --data "username=<username>" \
  --data "password=<password>" \
  --data "scope=service_id=api.bidswitch.com"

Note

API Authorization using https://api.bidswitch.com/discrepancy-check/v1.0/login is deprecated. Updated authorization steps are described in the API Authorization section. The Uploading Script is updated accordingly.

Uploading a Discrepancy Report

To upload your discrepancy report, use the following information.

• Make a HTTP POST request to the following appropriate link
• Specify the endpoint using only lowercase
• Ensure you include the HTTP headers with the required credentials and information

<!-- Supplier Endpoint All Lowercase -->
https://api.bidswitch.com/discrepancy-check/v1.0/ssp/<ssp-name>/upload-report/

Report Upload HTTP Headers

'Authorization':'Bearer <your-token>'
'Accept':'application/json'
'Content-Type':'application/json'

Example of uploading by curl:

# Syntax
$ curl -H "Accept:application/json" -H 'Authorization:Bearer <Your token here>' \
       -H 'Content-Type:application/json' -d @report.json \
       https://api.bidswitch.com/discrepancy-check/v1.0/ssp/<'ssp-name'>/upload-report/

# Supplier Example
$ curl -H "Accept:application/json" -H 'Authorization:Bearer CI6IkpXVCJ9.eyJhdWQiOiJwdWJsaWNfY2xpZW50IiwiaXNzIjoidWF1dGgiLCJqdGkiOiJORlhvblRRSyIsImtsc2RmYXNkZmthZG1mbDthc2RuZmFzaztkamZuYXN' \
       -H 'Content-Type:application/json' -d @report.json \
       https://api.bidswitch.com/discrepancy-check/v1.0/ssp/abc/upload-report/

Example Response:

{
    "status": "success",
    "handled": [["2016-08-06", "2016-08-14", "2016-08-07"]]
}

Uploading Script

Using the Uploading Script

Pass the following arguments when calling the script from the command-line. You can download the Uploading Script here.

• platform_type: ssp
• platform_name: SSP Name
• data.json: the JSON report

# Syntax Example
$ upload.py -u <username>:<password> -p <platform_type>:<platform_name> -d <data.json>

# Supplier Upload Example
$ python upload.py -u ssp_dummy:123456 -p ssp:adrtbdummy -d ./yesterday.json

Upload Report Format

The post request requires the following data in JSON. Usually you need to upload the full report from the previous day, which contains the complete data.

Reports

Reports Object

Field	Type	Validator	Description
reports	Array of objects	Required	Array of reports. The reports are created using the report object format, see the Report Object for more details.

Report Object

Report Object Parameters

Field	Type	Validator	Description
seat	String	Optional (Suppliers Only)	When a Supplier wants to check for discrepancies with a particular Buyer, they can specify the Buyer name using this field. Note: This field is only used when uploading a Supplier report, see the Supplier Reports example.
timezone	String	Required	Sets the timezone of the report, the valid options being those in the pytz.all_timezones list.
currency	String	Required	Sets the currency used in the report, the valid options being one of the following: [ 'USD', 'EUR', 'JPY'].
data	Array of objects	Required	Specifies the date to which the report figures refer, and the report data values. See the Report Data Values Object for more details. Keys: date using the following format "%Y-%m-%d" Values: list of the Report Data Values Object

Report Data Values Object

Report Data Values Object

Field	Type	Validator	Description
hour	String	Optional	Value is from range 00-23. If this field is absent, it is assumed that the report is for the full day.
imps	Integer	Required	The total number of impressions.
cost	Float	Required	The final cost for delivered impressions.
bids	Integer	Optional.	Field for Supplier reports. The total number of bid requests sent by the Supplier to BidSwitch. This includes all bid types such as requests ending in an error or timeout, no bids, yes bids, and incorrect responses.
timeouts	Integer	Optional.	Field for Supplier reports. The number of bid requests ending in a timeout.

Example Reports

Zero Reports | Hourly Report | Supplier Reports | Minimal Report | Multi-Day Report

Zero Reports

Zero reports indicate that no trading occurred, and they must contain {"imps":0,"cost":0}.

{
   "reports":[
      {
         "data":{
            "2016-08-05":[
               {
                  "imps":0,
                  "cost":0
               }
            ]
         },
         "currency":"USD",
         "timezone":"UTC"
      }
   ]
}

Hourly Report

This is considered the best practice reporting format, which splits reports by hours and contains bids, timeouts, imps, and cost.

Note

"hour" is represented as a string and must contain 2 digits.

{
   "reports" : [
      {
         "timezone" : "UTC",
         "currency" : "USD",
         "data" : {
            "2016-08-05" : [
               {
                   "timeouts": 26887,
                   "imps": 895,
                   "bids": 419746,
                   "cost": 16.6,
                   "hour": "00"
               },
               {
                   "timeouts": 292712,
                   "imps": 1442,
                   "bids": 496269,
                   "cost": 32.59,
                   "hour": "01"
               },
               {
                   "timeouts": 523600,
                   "imps": 736,
                   "bids": 264686,
                   "cost": 8.74,
                   "hour": "02"
               },
               {
                   "timeouts": 431437,
                   "imps": 299,
                   "bids": 346682,
                   "cost": 16.93,
                   "hour": "03"
               },
               {
                   "timeouts": 207841,
                   "imps": 778,
                   "bids": 104816,
                   "cost": 10.71,
                   "hour": "04"
               },
               {
                   "timeouts": 510346,
                   "imps": 398,
                   "bids": 538113,
                   "cost": 41.47,
                   "hour": "05"
               },
               {
                   "timeouts": 475965,
                   "imps": 2320,
                   "bids": 259689,
                   "cost": 40.1,
                   "hour": "06"
               },
               {
                   "timeouts": 226502,
                   "imps": 2242,
                   "bids": 522407,
                   "cost": 8.9,
                   "hour": "07"
               },
               {
                   "timeouts": 117024,
                   "imps": 464,
                   "bids": 91400,
                   "cost": 28.71,
                   "hour": "08"
               },
               {
                   "timeouts": 434858,
                   "imps": 1142,
                   "bids": 179587,
                   "cost": 32.67,
                   "hour": "09"
               },
               {
                   "timeouts": 43211,
                   "imps": 2223,
                   "bids": 276447,
                   "cost": 16.61,
                   "hour": "10"
               },
               {
                   "timeouts": 310415,
                   "imps": 1649,
                   "bids": 51621,
                   "cost": 12.66,
                   "hour": "11"
               },
               {
                   "timeouts": 430663,
                   "imps": 249,
                   "bids": 474692,
                   "cost": 36.81,
                   "hour": "12"
               },
               {
                   "timeouts": 310470,
                   "imps": 774,
                   "bids": 222399,
                   "cost": 1.24,
                   "hour": "13"
               },
               {
                   "timeouts": 427396,
                   "imps": 1706,
                   "bids": 144780,
                   "cost": 4.2,
                   "hour": "14"
               },
               {
                   "timeouts": 290821,
                   "imps": 1492,
                   "bids": 121281,
                   "cost": 37.24,
                   "hour": "15"
               },
               {
                   "timeouts": 45520,
                   "imps": 1209,
                   "bids": 3909,
                   "cost": 16.51,
                   "hour": "16"
               },
               {
                   "timeouts": 232909,
                   "imps": 2184,
                   "bids": 55060,
                   "cost": 43.22,
                   "hour": "17"
               },
               {
                   "timeouts": 504859,
                   "imps": 1145,
                   "bids": 221379,
                   "cost": 41.09,
                   "hour": "18"
               },
               {
                   "timeouts": 327505,
                   "imps": 11,
                   "bids": 138869,
                   "cost": 37.56,
                   "hour": "19"
               },
               {
                   "timeouts": 512344,
                   "imps": 1360,
                   "bids": 492131,
                   "cost": 30.65,
                   "hour": "20"
               },
               {
                   "timeouts": 315876,
                   "imps": 552,
                   "bids": 461330,
                   "cost": 32.76,
                   "hour": "21"
               },
               {
                   "timeouts": 258491,
                   "imps": 722,
                   "bids": 341752,
                   "cost": 8.0,
                   "hour": "22"
               },
               {
                   "timeouts": 399477,
                   "imps": 2263,
                   "bids": 515451,
                   "cost": 32.97,
                   "hour": "23"
               }
            ]
         }
      }
   ]
}

Supplier Reports

You may use the "seat" field to split your report by Buyer.

{
   "reports":[
      {
         "data":{
            "2015-11-27":[
               {
                  "timeouts":24450,
                  "bids":1943830,
                  "hour":"00",
                  "imps":83922,
                  "cost":3234
               },
               {
                  "hour":"23",
                  "imps":83922,
                  "cost":3234,
                  "timeouts":24450,
                  "bids":1943830
               }
            ]
         },
         "currency":"JPY",
         "timezone":"US/Pacific",
         "seat":"123"
      },
      {
         "currency":"JPY",
         "data":{
            "2015-11-27":[
               {
                  "cost":3234,
                  "imps":83922,
                  "hour":"00",
                  "bids":1943830,
                  "timeouts":24450
               },
               {
                  "timeouts":24450,
                  "bids":1943830,
                  "hour":"23",
                  "imps":83922,
                  "cost":3234
               }
            ]
         },
         "timezone":"EST",
         "seat":"456"
      }
   ]
}

Minimal Report

{
   "reports":[
      {
         "timezone":"UTC",
         "currency":"USD",
         "data":{
            "2015-11-26":[
               {
                  "imps":83922,
                  "cost":3234
               }
            ]
         }
      }
   ]
}

Multi-Day Report

If you missed uploading reports for a few days days, you can upload several days worth of reports at once using the following format. Each day’s data should be uploaded as a separate Array of Objects in the data object:

{
   "reports":[
      {
         "timezone":"UTC",
         "currency":"USD",
         "data":{
            "2015-11-26":[
               {
                  "imps":83922,
                  "cost":3234.22
               }
            ],
            "2015-11-27":[
               {
                  "imps":93922,
                  "cost":823.42
               }
            ],
            "2015-11-28":[
               {
                  "imps":92,
                  "cost":6.223
               }
            ]
         }
      }
   ]
}

Upload Response

If you uploaded successfully, you will receive a 200 OK response with a dated results list as shown in the following example. If your upload is in the wrong format, you will get an error status.

Successful Response

{
   "handled":[
      [
         "123 2015-11-27",
         "123 2015-11-26"
      ],
      [
         "456 2015-11-26"
      ]
   ],
   "status":"success"
}

Error Response

{
   "errors":[
      [
         "<index of report>",
         "<error text>"
      ]
   ],
   "status":"error"
}

Other Possible Responses

You may also receive one of the following HTTP status codes:

• 401 Unauthorized: If you don’t have access to the Buyer or Supplier details, or you don’t have the permission to upload, ensure that you have configured your account to use an API Token. You need an API account to upload reports.
• 404 Not Found: If the <ssp-name> is not found in our system.
• 500 Internal Server Error: If another unexpected error occurred.