Blocker

The Blocker endpoint checks whether a visitor should be allowed or blocked based on IP, user agent, URL, user configuration, and Stopbot threat intelligence.

Endpoint

GET https://api.stopbot.net/services/blocker

Parameters

Parameter	Required	Description
apikey	Yes	Your Stopbot API key
ip	Yes	Visitor IP address
ua	No	Visitor user agent
url	No	Requested URL or page path

Example Request

curl "https://api.stopbot.net/services/blocker?apikey={API_KEY}&ip=1.1.1.1&ua={USER_AGENT}&url=https%3A%2F%2Fexample.com"

Example Response

{
  "ip": "1.1.1.1",
  "hostname": "one.one.one.one",
  "asn": 13335,
  "userType": "hosting",
  "connectionType": "Corporate",
  "company": "Cloudflare, Inc.",
  "isp": "Cloudflare, Inc.",
  "city": "Sydney",
  "district": "",
  "region": "New South Wales",
  "postcode": "1001",
  "country": "Australia",
  "countryCode": "AU",
  "latitude": -33.8688,
  "longitude": 151.209,
  "timezone": "Australia/Sydney",
  "isAnycast": true,
  "device": "Desktop",
  "ua": "{USER_AGENT}",
  "isBot": 1,
  "blockAccess": 1,
  "threatURL": 0,
  "detectActivity": "BLOCK BY HOSTNAME DATABASE.",
  "status": "success",
  "executionTime": "5.17ms",
  "timeResponse": "2026-07-07 12:00:00"
}

Invalid Input Example

If the ip parameter is missing or is not a valid IPv4/IPv6 address, the Blocker endpoint returns 400 Bad Request.

Example request with invalid IP:

curl "https://api.stopbot.net/services/blocker?apikey={API_KEY}&ip=not-an-ip&ua={USER_AGENT}&url=https%3A%2F%2Fexample.com"

Example response:

{
  "errorMessage": "IP format is invalid.",
  "status": "failed",
  "executionTime": "1.23ms",
  "timeResponse": "2026-07-07 12:00:00"
}

Response Fields

Successful Blocker responses may include the following fields:

Field	Description
ip	Visitor IP address from the ip request parameter
hostname	Hostname or PTR value resolved for the visitor IP. If no hostname is available, the IP itself may be returned
asn	Autonomous System Number from IP geolocation data
userType	Network user type from IP geolocation data. Current values are business, cellular, hosting, and residential. If unavailable, STOPBOT returns unknown
connectionType	Network connection type from IP geolocation data. Current values are Cable/DSL, Cellular, Corporate, and Dialup. If unavailable, STOPBOT returns unknown
company	Autonomous system organization or company name from IP geolocation data. If unavailable, STOPBOT returns unknown
isp	Internet service provider name from IP geolocation data. If unavailable, STOPBOT returns unknown
city	City name from IP geolocation data. If unavailable, STOPBOT may return unknown
district	District or second subdivision from IP geolocation data when available
region	Region or first subdivision from IP geolocation data. If unavailable, STOPBOT may return unknown
postcode	Postal code from IP geolocation data when available
country	Country name from IP geolocation data. If unavailable, STOPBOT returns unknown
countryCode	Country ISO code from IP geolocation data. If unavailable, STOPBOT returns NN
latitude	Latitude from IP geolocation data. If unavailable, the value may be 0
longitude	Longitude from IP geolocation data. If unavailable, the value may be 0
timezone	Timezone from IP geolocation data. If unavailable, STOPBOT returns UTC
isAnycast	true when the IP geolocation data marks the IP as anycast; otherwise false
device	Device classification derived from the ua request parameter
ua	User agent value from the request. This field is only included when the ua parameter is provided
isBot	Visitor classification signal: 0 visitor/non-bot, 1 detected bot/threat, 2 user list match
blockAccess	1 means the website should apply the block action; 0 means access can continue or be monitored
threatURL	1 when the URL is treated as a threat signal; otherwise 0
detectActivity	Detection reason returned by the Blocker decision flow
status	API result status. Successful Blocker responses return success
executionTime	Server-side execution time for the request
timeResponse	Response timestamp in YYYY-MM-DD HH:mm:ss format

Error Response Fields

Failed Blocker responses may include the following fields:

Field	Description
errorMessage	Human-readable error message
status	Failed requests return failed
executionTime	Server-side execution time for the request
timeResponse	Response timestamp in YYYY-MM-DD HH:mm:ss format

Decision Fields

Field	Description
isBot	Bot classification. 0 visitor, 1 detected bot/threat, 2 user list match
blockAccess	1 means block action should be applied, 0 means allow/monitor
threatURL	URL threat flag
detectActivity	Human-readable detection reason
device	Detected device type

Use blockAccess as the final allow/block decision field. The isBot field is a classification signal and should not be used as the final access decision.

For the Blocker endpoint, most blocked threat or policy matches also return isBot=1 or isBot=2, but the integration contract remains the same: apply your block action when blockAccess is 1.

Device Values

The device field is derived from the ua request parameter.

Value	Meaning
Mobile	The user agent contains a known mobile keyword, such as Android, iPhone, iPad, Windows Phone, BlackBerry, Nokia, Kindle, PlayBook, mobi, Silk, Opera Mini, Opera Mobile, UCBrowser, Symbian, Blazer, or WebOS
Desktop	The user agent does not match the mobile keyword list, or no user agent is provided

User Type

The userType field is copied from the IP geolocation data field traits.user_type.

The current STOPBOT IP geolocation database contains these userType values:

Value	Meaning
business	Business or organization network
cellular	Mobile carrier network
hosting	Hosting, cloud, or data center network
residential	Residential ISP network

If the IP geolocation data does not provide a value, STOPBOT returns:

unknown

Connection Type

The connectionType field is copied from the IP geolocation data field traits.connection_type.

The current STOPBOT IP geolocation database contains these connectionType values:

Value	Meaning
Cable/DSL	Fixed broadband connection
Cellular	Mobile network connection
Corporate	Corporate or organization network connection category
Dialup	Dial-up connection

If the IP geolocation data does not provide a value, STOPBOT returns:

unknown

Common Detection Reasons

Value	Meaning
Visitor	No block reason detected
BLOCK BY IP DATABASE.	IP matched Stopbot IP database
BLOCK BY MALICIOUS ACTIVITY.	IP matched malicious activity checks
BLOCK BY HOSTNAME DATABASE.	Hostname matched Stopbot hostname database
BLOCK BY PROXY/VPN/TOR.	Proxy, VPN, or Tor detection
BLOCK BY COUNTRY.	Country is not allowed by configuration
BLOCK BY IP NON-ISP.	Non-ISP network blocked by configuration
BLOCK BY SPIDER CRAWLER	User agent bot/crawler detection
BLOCK BY THREAT URL	URL threat or repeated failed traffic
BLOCK BY DEVICE DESKTOP	Blocked by configured desktop device rule
BLOCK BY DEVICE MOBILE	Blocked by configured mobile device rule
BLOCK BY BLACKLIST IP (USER)	Matched user IP blacklist
ALLOW BY WHITELIST IP (USER)	Matched user IP whitelist
BLOCK BY THREAT FEEDS	Matched Stopbot threat feeds
BLOCK BY HOSTNAME (USER)	Matched user hostname blacklist
ALLOW BY SETTING ( SEARCH ENGINE )	Allowed search engine bot by setting