The Requests API

Query Format

API calls to WQS should have the following format

GET :resource-name/:query-string

The components of the call are defined as follows:

  • resource-name is a required enumerated field that represents which blocklist should be queried. The possible values of this field are:

    • SBL

    • XBL

    • PBL

    • SBL-XBL

    • ZEN

    • AUTHBL

    • ZRD (domains only)

    • DBL (domains only)

  • query-string is a required parameter that must be either:

    • an IPv4 or IPv6 address when the resource-name is an IP-based blocklist

    • a domain name when the resource-name is a name-based blocklist (DBL and ZRD only)

HTTP Response Codes

The following HTTP status codes should be expected after a query:

  • 200 - OK - At least one record was FOUND

  • 400 - Bad request - there was a syntax error in the request

  • 401 - Authorization failed - please verify a valid DQS key was supplied

  • 403 - Forbidden - Authorization denied

  • 404 - Not found - The record is not listed

  • 406 - Not Acceptable - The requested Content-Type is not supported.

  • 429 - Too Many Requests - Rate limiting in effect, please decrease query rate

  • 504 - Gateway timeout - Query could not be successfully sent

Output Format

Supported Data Formats

The WQS API supports only the HTML or JSON data types. You can set the “accept” HTTP header in any API call sent:

  • accept: application/JSON

  • accept: text/HTML

The API response will match the “accept” header format and set the “content-type” HTTP header in the response as follows:

  • Content-Type: application/JSON - The body will be a JSON document

  • Content-Type: text/HTML - The body will be anH HTML document

If the “accept” header is not specified in the API call, then JSON is used as the default. Specifying a media type other than HTML or JSON will result in a 406 - Not Acceptable HTTP status code.

Output format - Found

A successfull JSON response body returns a JSON object with the following format:

{
 "resp": [
   1002,
   1010,
   1004
 ],
 "status": 200
}

The object contains a resp array where each element has a specific meaning outlined in detail below. The status field reflects the corresponding HTTP status code.

A successfull HTML response body returns a document containing a comma separated list of response codes with the following format:

<html><head><title></title></head><body>1002,1010,1004</body></html>

Output format - Error

If an error occurs the response body will include the encountered error code.

In case of an text/html data type, an error page will be returned in HTML with the HTTP status code.

In case of an application/json data type, a JSON object will be returned and it will contain a status field:

{
   "status":404
}

Please note that the difference in JSON response is the resp field missing from a failed call.

Array Return Codes

The content of the resp array may contain any of the following values:

For IP Queries

  • 1002 SBL Listed in the Spamhaus SBL

  • 1003 SBL Listed in CSS - a subset of the Spamhaus SBL

  • 1004 XBL Listed in the Spamhaus CBL

  • 1009 SBL Listed in the Spamhaus DROP Data

  • 1010 PBL Listed in the Spamhaus PBL

  • 1011 PBL Listed in the Spamhaus PBL

  • 1020 AUTHBL Listed in the Spamhaus AuthBL list

For Domain Queries

This applies to DBL and ZRD only

  • 2002 Domain used for spam

  • 2003 Spam domain used as a redirector / URL shortener

  • 2004 Phishing domain

  • 2005 Malware domain

  • 2006 Botnet C&C domain

  • 2102 Origin domain of abused-legit spam

  • 2103 Origin domain of abused redirector / URL shorteners used for spam

  • 2104 Abused-legit phishing domain

  • 2105 Abused-legit malware domain

  • 2106 Origin domain of abused-legit botnet C&C

  • 3002 Domain listed in Spamhaus ZRD first observed between 0 and 2 hours ago.

  • 3003 Domain listed in Spamhaus ZRD first observed between 2 and 3 hours ago.

  • 3004 Domain listed in Spamhaus ZRD first observed between 3 and 4 hours ago.

  • 3023 Domain listed in Spamhaus ZRD first observed between 22 and 23 hours ago.

  • 3024 Domain listed in Spamhaus ZRD first observed between 23 and 24 hours ago.