Discrepancy API for Buyer¶

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 Buyer can be monitored. Use the information in the following sections to set up your discrepancy monitoring with BidSwitch.

Process Overview¶

Get your API Access Token. This requires creating an API user in the myBidSwitch UI, see the API Authorization section for details.
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 upload several day’s worth of data this, use the Several Days Report format.
An Uploading Script is available.

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

<!-- Buyer Endpoint All Lowercase -->
https://api.bidswitch.com/discrepancy-check/v1.0/dsp/<dsp-id>/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/dsp/<'dsp-id'>/upload-report/

# Buyer Example
$ 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/dsp/123/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: dsp
platform_name: DSP ID
data.json: the JSON report

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

# Buyer Upload example
$ python upload.py -u dsp_dummy:123456 -p dsp:42 -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 Object¶

Reports Object¶
Field	Type	Description
reports	Array of objects	(Required) Array of reporting data. See the Reporting Data Object for more details.

Reporting Data Object¶

Report Object Parameters¶
Field	Type	Description
ssp	String	(Required) When a Buyer wants to check for discrepancies with a particular Supplier, they can specify the Supplier name using this field. It is essential that you send the BidSwitch internal Supplier name, otherwise the split won’t work; refer to this sample (first column - the internal name, second column - the reference) Note: This field is only used when uploading a Buyer report, see the Buyer 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	Descriptionp
imps	Integer	(Required) The total number of impressions.
cost	Float	(Required) The final cost for delivered impressions.

Report Examples¶

Buyer Reports¶

This is considered the best practice reporting format, which splits reports by the "ssp" field.

{
  "reports":[
     {
        "ssp":"xyz",
        "timezone":"UTC",
        "currency":"USD",
        "data":{
           "2022-11-26":[
              {
                 "imps":56789,
                 "cost":4321
              }
           ]
        }
     },
     {
        "ssp":"abc",
        "timezone":"UTC",
        "currency":"USD",
        "data":{
           "2022-11-26":[
              {
                 "imps":83922,
                 "cost":3234
              }
           ]
        }
     }
  ]
}

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

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 <dsp-id> is not found in our system.
500 Internal Server Error: If another unexpected error occurred.