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://my.bidswitch.com/api/blocking/ssps/<ssp_id>/creatives/

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

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

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

<!-- PUT or PATCH to update a single blocked creative -->
https://my.bidswitch.com/api/blocking/ssps/<ssp_id>/<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 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

int

Required. The BidSwitch ID for the Buyer to whom the blocking will apply.

Blocking Request

Single Blocking

{
   "creative":{
      "creative_id":"abc_123",
      "dsp":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 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":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://my.bidswitch.com/api/blocking/ssps/<ssp_id>/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 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://my.bidswitch.com/api/blocking/ssps/<ssp_id>/creatives/?reason=alcohol,created_after=2018-08-01,dsp=32

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

<!-- GET details about a single creative ID-->
https://my.bidswitch.com/api/blocking/ssps/<ssp_id>/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."
}