Phishing and Fraudulent Site Detection API

The Bolster Scan API can detect the following scams and threat categories in real-time:

• Zero-Day Phishing
• Tech Support Scams
• Gift Card Scams
• Survey Scams
• Adult Websites
• Drug Pharmacy (Drug Spam) Websites
• Illegal/Rogue Streaming Sites
• Gambling Websites
• Hacked Websites
• Cryptojacking / Cryptomining

Use the Scan API to submit the URLs you would like to have scanned. You can submit for a quick scan or full scan. Your Bolster enterprise license determines the limit on the number of scan requests you can submit.

Before You Start: Locate Your API Key

You will need to provide your Bolster API key to submit URLs for scan requests.

1. Click the user dropdown on the right.
2. Click Profile Information.
3. Copy the API key displayed in your profile screen.

How to Use the Scan API

To use the Scan API, you complete the following steps:

1. Submit the URL you want to scan.
2. Query the results of the scan when complete.

Submitting a URL for Scanning

Your scan request requires the following information:

Endpoint:

/neo/scan

API host:

https://developers.bolster.ai/api

Your Bolster API key

To request a scan, submit the following request:

curl -X POST --header 'Content-Type: application/json' \
     -d '{"apiKey": "<api_key>", "urlInfo": {"url": "<url_to_scan>"}}' \
     https://developers.bolster.ai/api/neo/scan

Note: If default scan settings are configured for your brand, those settings will be automatically applied to your API scans. This includes IP location, user agent, and timeout configurations, the same settings shown on your Bulk Scan page. This ensures consistency between API scans and bulk scans.

Optionally, one or multiple tags can be added to the scanned URL. See Using Tags to Annotate Detections or allowed tags.

curl -X POST --header 'Content-Type: application/json' \
     -d '{"apiKey": "<api_key>", "urlInfo": {"url": "<url_to_scan>"}, "tags": ["Watchlist"]}' \
     https://developers.bolster.ai/api/neo/scan

Examples

curl -X POST --header 'Content-Type: application/json' \
     -d '{"apiKey": "1f207653ec034ab9f04fbdd8e09fa7879205b4c85addeaa299da326167cc00a1", "urlInfo": {"url": "http://webidlogin101997.5gbfree.com/"}}' \
     https://developers.bolster.ai/api/neo/scan

Premium Scan

If Premium Scan is enabled for your brand, you can request a premium scan by passing premiumScan: true in the urlInfo object. It uses a premium proxy from a specific geographic location for more accurate results on geo-targeted pages.

You can optionally specify a scanLocation (country code, e.g., “US”, “GB”, “IN”) to scan from a specific country. If not provided, your brand’s default scan location is used, or “US” if no default is configured.

curl -X POST --header 'Content-Type: application/json' \
     -d '{"apiKey": "<api_key>", "urlInfo": {"url": "<url_to_scan>", "premiumScan": true, "scanLocation": "IN"}, "tags": ["Watchlist"]}' \
     https://developers.bolster.ai/api/neo/scan

Note: Premium Scan is limited to 20 scans per day across all users in your brand. Once the daily limit is reached, scans will automatically fall back to a normal scan. Premium Scan API may not immediately scan a URL; it sends scans into the FIFO queue, so it may take time for a URL to finish the scan.

Response

The scan request will return a job ID and timestamp in JSON format:

{
  "jobID": "ca1b827b-1f14-4e74-a242-ed17cc1808b0",
  "timestamp": 1538090611675
}

If premiumScan: true was sent in the request, the response includes two additional fields:

{
  "jobID": "ca1b827b-1f14-4e74-a242-ed17cc1808b0",
  "timestamp": 1538090611675,
  "premiumScan": true,
  "scansLeft": 18
}

Querying the Scan Results

Submit the following request to query your scan results:

curl -X POST --header 'Content-Type: application/json' \
     -d '{"apiKey": "<apiKey>", "jobID": "<jobID>", "insights": "basic"}' \
     https://developers.bolster.ai/api/neo/scan/status

where <jobID > is the job ID returned by your scan request.

Example

curl -X POST --header 'Content-Type: application/json' \
     -d '{"apiKey": "1f207653ec034ab9f04fbdd8e09fa7879205b4c85addeaa299da326167cc00a1", "jobID": "ca1b827b-1f14-4e74-a242-ed17cc1808b0", "insights": "basic"}'
     https://developers.bolster.ai/api/neo/scan/status

Response

Results will be returned in JSON format.

Before the scan is completed, the response will return with “PENDING” status.

{
  "job_id": "ca1b827b-1f14-4e74-a242-ed17cc1808b0",
  "url": "http://webidlogin101997.5gbfree.com/",
  "status": "PENDING",
  "scan_start_ts": 1654129884891
}

Basic insights information are returned when “insights” is set to “basic” or “verbose” in the query.

{
  "job_id": "ca1b827b-1f14-4e74-a242-ed17cc1808b0",
  "status": "DONE",
  "url": "http://webidlogin101997.5gbfree.com/",
  "url_sha256": "a395e2130500750d34703f66c62c50ce99be0c7272b6763f6508c6bd473f1d74",
  "disposition": "phish",
  "brand": "paypal",
  "scan_start_ts": 1654129884891,
  "scan_end_ts": 1654129887641,
  "error": false,
  "tags": [
    "Watchlist"
  ],
  "insights": {
    "insights_path": "https://checkphish.ai/insights/url/1654129884891/a395e2130500750d34703f66c62c50ce99be0c7272b6763f6508c6bd473f1d74",
    "resolved": true,
    "screenshot_path": "https://xxxx.xxxx.amazonaws.com/20220602/a395e2130500750d34703f66c62c50ce99be0c7272b6763f6508c6bd473f1d74_1654129884891.png",    "dom_source_path": "https://xxxx.xxxx.amazonaws.com/20220602/a395e2130500750d34703f66c62c50ce99be0c7272b6763f6508c6bd473f1d74_1654129884891.txt",
    "image_objects": [
      {
        "brand": "paypal",
        "product": "paypal",
        "object_type": "logo",
        "prob": 0.78,
        "image_height": 1080,
        "image_width": 1920,
        "width": 134.4,
        "height": 32.4,
        "x": 9.6,
        "y": 5.4
      }
    ]
  }
}

The response includes the following information in JSON format:

• job_id: job ID of the scan
• status:  Status of whether the job has completed. Returns DONE when completed, PENDING when in progress.
• url: URL submitted for scanning
• url_sha256: SHA256 of the url submitted for scanning
• brand: Brand being targeted by the URL
• disposition: the list of dispositions can be found below
• scan_start_ts: Unix Timestamp of when the scan the triggered
• scan_end_ts: Unix Timestamp of when the scan ended
• categories: List of categories from our webpage category detection model
• tags: List of tags added
• insights: List of scan insights data, see below.

Basic insights data:

• insights_path: insights link
• screenshot_path: storage location of the screenshot for the scan
• dom_source_path: storage location of the DOM source for the scan
• resolved: true if the URL resolved. Else false

Verbose insights data:

• cert: SSL certification information
• parked: if the domain is parked domain.
• redirection_chain: a list of urls of the redirection chain if there’s any.
• last_scan_ts: last time the URL was scanned.
• past_phish: number of past phish count of IP address and hostname.
• passive_dns_list: a list of passive DNS entries of the IP address.

List of Dispositions

List of Categories

See Intent Detection – Categories.

API Rate Limiting

Scan API requests are restricted to the rate specified by your Bolster enterprise license. If requests exceed this rate, the caller will receive the following error:

{
  "error": {
    "status_code": 429,
    "status": "Request rate limit exceeded. Please try again later"
  }
}