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 the blocked creative.

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 Creative Blocking endpoint. The request payload should contain the required parameters outlined in the Blocking Creatives section.

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. You can find your ID in the sellers.txt file.

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, you can find all DSP IDs in the buyers.txt file

Example Blocking Object (Single)¶

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

Example Blocking Array (Bulk)¶

[
  {
     "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

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": 380
      },
      "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.
reason	str	(Required) The unblocked reason, taken from the reasons list in the Blocking Creatives section.
comment	str	(Optional) A comment why it was unblocked, e.g. “creative updated”

{
  "comment":"comment",
  "status":"unblocked",
  "reason":"malware"
}

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