Creative Blocking API

The Creative Blocking API lets you submit Creative IDs which will be blocked within BidSwitch, this means that as a Supplier you will not receive bid responses that reference a blocked creative.

Process Overview

  1. Get your API Access Token. This requires creating an API user in the myBidSwitch UI, see the API Authorization section for details.
  2. Using this Token, make a HTTP POST request to the Creative Blocking endpoint. The post request should contain the required parameters outlined in the Blocking Creatives section.

Getting API Credentials

To get access credentials for the Creative Blocking API, you need to create an API User Account in the myBidSwitch UI, using the following instructions.

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"

Creative Blocking Endpoints

<!-- GET details of all blocked creatives -->
https://api.bidswitch.com/supply/ssps/<ssp_id>/blockings/creatives/

<!-- GET specifics of a single blocking action -->
https://api.bidswitch.com/supply/ssps/<ssp_id>/blockings/creatives/<id_of_blocking>

<!-- POST to block a single creative -->
https://api.bidswitch.com/supply/ssps/<ssp_id>/blockings/creatives/

<!-- POST a list of creative IDs to block in bulk -->
https://api.bidswitch.com/supply/ssps/<ssp_id>/blockings/creatives/bulk

<!-- PUT or PATCH to update a single blocked creative -->
https://api.bidswitch.com/supply/ssps/<ssp_id>/blockings/creatives/<id_of_blocking>

Where ssp_id is your BidSwitch Supplier ID, e.g. kargo

Blocking Creatives

To block a creative or a list of them, POST the details to the appropriate endpoint. The BidSwitch response object will contain a number of additional auto-generated fields which you can use to monitor the state of any blocking action.

Blocking object

Creative Blocking Request Fields
Field Type Description
creative object Required. Object containing the creative_id and dsp_id for which the Creative ID should be blocked, see the Creative object
reason str Required. The reason why the Creative was blocked, this field can take one of the following values: "Adult content", "Alcohol", "Auto-redirects", "Autoplay video", "Blank creative", "Gambling", "In-banner video", "Malware", "Malicious", "Offensive", "Phishing", "Pop-up/pop-under", "Unwanted", "Other"
comment str (Optional) A comment on the blocking which will be sent to the Buyer, with a maximum length of 256 chars

Creative object

Creative Object Fields
Field Type Description
creative_id str Required. The ID of the creative to be blocked.
dsp_id int Required. The BidSwitch ID for the Buyer to whom the blocking will apply.

Blocking Request

Single Blocking

{
   "creative":{
      "creative_id":"abc_123",
      "dsp_id":123
   },
   "reason":"alcohol",
   "comment":"3rd Malicious creative this month, you risk being blocking entirely"
}

Bulk Blocking

[
   {
      "creative":{
         "creative_id":"20",
         "dsp":"38"
      },
      "reason":"Alcohol"
   },
   {
      "creative":{
         "creative_id":"20",
         "dsp":"76"
      },
      "reason":"Alcohol"
   },
   {
      "creative":{
         "creative_id":"21",
         "dsp":"38"
      },
      "reason":"Alcohol"
   }
]

Blocking response object

Creative Blocking Response Fields
Field Type Description
id int Unique ID for the blocking action
ssp str The supplier name in BidSwitch
creative object Object containing the creative_id and dsp_id for which the Creative ID should be blocked
reason str The reason for the blocking, can be one of the following values: "Adult content", "Alcohol", "Auto-redirects", "Autoplay video", "Blank creative", "Gambling", "In-banner video", "Malware", "Malicious", "Offensive", "Phishing", "Pop-up/pop-under", "Unwanted", "Other"
comment str A comment on the blocking which will be sent to the Buyer, with a maximum length of 256 chars
dsp_notified str Date and time of notification sent to the Buyer (and BidSwitch Support), e.g. "2017-12-21T18:13:12.833942Z". null if is had not been sent yet. Note: Notifications are sent once daily with a list of creatives which have been blocked.
created str Date and time of the initial blocking, e.g. "2017-12-21T18:13:12.833942Z".
updated str Date and time of the the lastest update to the blocking, e.g. "2017-12-21T18:13:12.833942Z"
status str The status of the creative ID, this could be either "blocked" or "unblocked"
created_by str The username of the person who initiated the blocking
is_changed_by_client_api bool True if this blocking was changed through the client API, or False if the blocking was carried out by BidSwitch

Blocking Response

Single Blocking Response

{
   "id":409,
   "ssp":"ssp-name",
   "creative":{
      "creative_id":"abc_123",
      "dsp_id":123
   },
   "reason":"alcohol",
   "comment":"comment",
   "dsp_notified":null,
   "created":"2017-12-21T18:13:12.833942Z",
   "updated":"2017-12-21T18:13:12.834010Z",
   "ticket_id":"RT:1337",
   "status":"blocked",
   "created_by":"username",
   "is_changed_by_client_api": true
}

Bulk Blocking Response

[
   {
      "id":11,
      "creative":{
         "creative_id":"11",
         "dsp":"38"
      },
      "ssp":"ssp-name",
      "reason":"Alcohol",
      "comment":null,
      "dsp_notified":null,
      "created":"2018-07-12T08:41:59.269266Z",
      "updated":"2018-07-12T08:41:59.269294Z",
      "status":"blocked",
      "created_by":"username",
      "updated_by":"username",
      "is_changed_by_client_api": true
   },
   {
      "id":12,
      "creative":{
         "creative_id":"11",
         "dsp":"38"
      },
      "ssp":"adasia",
      "reason":"Alcohol",
      "comment":null,
      "dsp_notified":null,
      "created":"2018-07-12T08:41:59.474128Z",
      "updated":"2018-07-12T08:41:59.474173Z",
      "status":"blocked",
      "created_by":"username",
      "updated_by":"username",
      "is_changed_by_client_api": true
   }
]

Unblocking Creatives

<!-- Patch or Put to update a Creative's blocking status -->
https://api.bidswitch.com/supply/ssps/<ssp_id>/blockings/creatives/<id_of_blocking>

Where id_of_blocking is taken from the response id field, not the creative.creative_id value.

Unblocking Request Fields
Field Type Description
status str The status of the creative ID, this can be either "blocked" or "unblocked". To change the status, pass the opposite value to the current one.
comment str (Optional) Object containing the creative_id and dsp_id for which the Creative ID should be blocked
{
    "comment": "comment",
    "status": "unblocked"
}

Creative Blocking URL Parameters

Creative Blocking URL parameters
Field Type Description
status str The status of the creative, can be either blocked or unblocked
creative_id str The Creative ID which was blocked
dsp int The BidSwitch Buyer ID
reason str The reason for the blocking, can be one of the following values: "Adult content", "Alcohol", "Auto-redirects", "Autoplay video", "Blank creative", "Gambling", "In-banner video", "Malware", "Malicious", "Offensive", "Phishing", "Pop-up/pop-under", "Unwanted", "Other"
created_by str The username of the person who created the blocking.
update_by str The username of the person who last updated the blocking.
created_after str Return blockings created after the given date, uses ISO 8601 formatted dates, e.g. 2017-12-21 or 2018-07-12T08:41:59.474173Z
created_before int Return blockings created before the given date, uses ISO 8601 formatted dates, e.g. 2017-12-21 or 2018-07-12T08:41:59.474173Z
updated_after int Return blockings updated after the given date, uses ISO 8601 formatted dates, e.g. 2017-12-21 or 2018-07-12T08:41:59.474173Z
updated_before int Return blockings created after the given date, uses ISO 8601 formatted dates, e.g. 2017-12-21 or 2018-07-12T08:41:59.474173Z

Using URL Parameters

<!-- GET all creatives blocked due to alcohol since a particular date for a DSP -->
https://api.bidswitch.com/supply/ssps/<ssp_id>/blockings/creatives?reason=alcohol,created_after=2018-08-01,dsp=32

<!-- GET All creatives blocked since a date -->
https://api.bidswitch.com/supply/ssps/<ssp_id>/blockings/creatives?status=blocked,created_after=2018-08-01

<!-- GET details about a single creative ID-->
https://api.bidswitch.com/supply/ssps/<ssp_id>/blockings/creatives?creative_id=3873-jgjgge-982

Error Codes

400 Bad Request

{
    "type": "",
    "title": "Invalid request data",
    "details": "Some of the parameters in your request are invalid. Please check your request, API reference and error type documentation.",
    "invalid-params": {"example":"dict with invalid params"}
}

404 Not Found

{
    "type": "",
    "title": "Not found",
    "details": "Unable to find item by unknown reason. Please check your request, API reference and error type documentation."
}

405 Method Not Allowed

{
    "type": "",
    "title": "Method not allowed",
    "details": "Method \"{method_name}\" not allowed."
}

406 Not Acceptable

{
    "type": "",
    "title": "Method not allowed",
    "details": "Could not satisfy the request Accept header."
}