Web Takedown and Post-Malicious URLs API

The Web Takedown and Post-Malicious URLs API returns your brand's phishing and scam URLs from the Bolster platform for a date range. It covers the same URLs you see in the Takedown Malicious and Post-Malicious tables of the Web module: URLs that are live and under takedown, and URLs that have already been taken down.

Important Notes

• A URL is returned when any one of these happened within your date range: it was first seen, it
• was detected as phish or scam (malicious detection time), or it was taken down.
• Results cover the brands your API key has access to, the same as what you see on the platform.
• A single request returns at most 10,000 URLs. The total field always shows how many URLs matched. If total is more than 10,000, narrow your date range and make several smaller requests.
• All dates and times are in UTC. Dates without a time zone offset are read as UTC, and dates with an offset are converted to UTC.
• Results are sorted by malicious detection time (when the URL was detected as phish or scam), newest first. URLs with no malicious detection time are listed last.
• Responses can be large. We recommend requesting a compressed response by sending the Accept-Encoding: gzip header (--compressed in curl).

Step 1: Locate Your API Key

Before using the Web Takedown and Post-Malicious URLs API, you need your Bolster API key. Follow these steps to find it:

1. Click on the user dropdown in the top-right corner of the page.
2. Select Profile Information from the dropdown menu.
3. Copy the API key displayed on your profile screen.

Step 2: Initiate Request Through API

Endpoint:

/api/web/v1/takedown-post-malicious-urls

API Host:

https://developers.bolster.ai

To make a request, use the following details.

Request Format

curl --compressed --location 'https://developers.bolster.ai/api/web/v1/takedown-post-malicious-urls' \
--header 'Content-Type: application/json' \
--data '{
  "apiKey": "<your_api_key>",
  "startDate": "1970-01-01T00:00:00Z",
  "endDate": "1970-01-31T23:59:59Z"
}'

To only get URLs with a specific current disposition, add the optional disposition field:

curl --compressed --location 'https://developers.bolster.ai/api/web/v1/takedown-post-malicious-urls' \
--header 'Content-Type: application/json' \
--data '{
  "apiKey": "<your_api_key>",
  "startDate": "1970-01-01T00:00:00Z",
  "endDate": "1970-01-31T23:59:59Z",
  "disposition": ["phish", "scam"]
}'

Request Parameters

• apiKey (required): Your user API key.
• startDate (required): Start of the date range, inclusive. ISO 8601 date and time, for example 1970-01-01T00:00:00Z.
• endDate (required): End of the date range, inclusive to the second. ISO 8601 date and time, for example 1970-01-31T23:59:59Z. Must not be earlier than startDate.
• disposition (optional): Only return URLs whose current disposition (currentDisposition in the response) is one of these values. An array with one or more of: phish, scam, suspicious, clean. When omitted, URLs of every disposition are returned.

Date Format

Both dates need a date and a time. A date on its own, such as 1970-01-01, is not accepted. Milliseconds and a time zone offset are optional:

Response

The API returns the matching URLs along with the total number of matches.

Response Fields

Per-URL Fields

Each object in the urls array contains the following fields. Every field is always present; fields with no value are returned as null.

Successful Response (Status Code: 200)

The following example shows one URL that is still live and one URL that has been taken down:

{
  "total": 2,
  "urls": [
    {
      "srcUrl": "http://example-login-secure.com/",
      "dstUrl": "https://example-login-secure.com/account/verify",
      "currentDisposition": "phish",
      "firstSeenTs": "1970-01-18T10:15:02.120Z",
      "maliciousDetectedTs": "1970-01-18T10:15:09.874Z",
      "takedownTs": null,
      "insightsUrl": "https://platform.bolster.ai/web/insights/1506000000/b25f69540b544f2e0bf790caf4c602548e7e642aef122f823be29294912afc36"
    },
    {
      "srcUrl": "http://example-support-help.net/",
      "dstUrl": "http://example-support-help.net/",
      "currentDisposition": "clean",
      "firstSeenTs": "1970-01-05T08:42:11.311Z",
      "maliciousDetectedTs": "1970-01-05T08:42:19.006Z",
      "takedownTs": "1970-01-12T16:05:47.530Z",
      "insightsUrl": "https://platform.bolster.ai/web/insights/2107800000/75788cea81bed557dd4d1b37eaa52c1060b72ed6935d629ef309c95945fcb862"
    }
  ]
}

Error Responses

If the request is invalid, the API returns an error response and no URLs.

Status Code: 401

{
  "error": {
    "statusCode": 401,
    "name": "Error",
    "message": "Invalid API key or API key not enabled."
  }
}

Status Code: 400

The following 400 errors may be returned:

Missing parameter:

{
  "error": {
    "statusCode": 400,
    "name": "Error",
    "message": "startDate is a required argument"
  }
}

Invalid date:

{
  "error": {
    "statusCode": 400,
    "name": "Error",
    "message": "startDate must be an ISO 8601 date-time such as 1970-01-01T00:00:00Z"
  }
}

Start date after end date:

{
  "error": {
    "statusCode": 400,
    "name": "Error",
    "message": "startDate must not be after endDate"
  }
}

Invalid disposition:

{
  "error": {
    "statusCode": 400,
    "name": "Error",
    "message": "disposition must be a non-empty array of: phish, scam, suspicious, clean"
  }
}

Support

If you have any questions or encounter any issues while using the Web Takedown and Post-Malicious
URLs API, please contact our support team at [email protected].