Blocker v2
Use Blocker v2 to apply advanced visitor protection with named configurations, request parameter checks, header checks, search engine handling, ad bot detection, and configurable page responses.
Blocker v2 returns a flat JSON response with visitor IP information, decision fields, and page response fields at the top level.
Endpoint
GET https://api.stopbot.net/services/blockerv2Parameters
apikey
Yes
Your STOPBOT API key
confname
Yes
Blocker v2 configuration name from the STOPBOT panel
ip
Yes
Visitor IPv4 or IPv6 address
ua
No
Visitor user agent
url
No
Requested URL. The value is used only when it starts with http:// or https://
params
No
JSON object of request parameters, used when Params rules are enabled
headers
No
JSON object of request headers, used when HTTP Headers rules are enabled
Parameter Rules
confname
Must be 1-64 alphanumeric characters: A-Z, a-z, 0-9
ip
Must be a valid IPv4 or IPv6 address
ua
Accepted as optional input. Values longer than 1024 characters are truncated
url
Accepted only when it starts with http:// or https://. Values longer than 2048 characters are truncated
params
Must be a JSON object when used. Maximum accepted length is 64 KB and maximum accepted keys are 100
headers
Must be a JSON object when used. Maximum accepted length is 64 KB and maximum accepted keys are 100
If Params or HTTP Headers rules are enabled in the configuration and the submitted JSON does not match the configured rules, Blocker v2 returns a blocked decision instead of an invalid input error.
Example Request
Example Response
Invalid Input Examples
Invalid configuration name format:
Response:
Invalid IP address:
Response:
Configuration name is valid but not registered for the API key:
Response Fields
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
connectionType
Network connection type from IP geolocation data
company
Autonomous system organization or company name from IP geolocation data
isp
Internet service provider name from IP geolocation data
city
City name from IP geolocation data
district
District or second subdivision from IP geolocation data when available
region
Region or first subdivision from IP geolocation data
postcode
Postal code from IP geolocation data when available
country
Country name from IP geolocation data
countryCode
Country ISO code from IP geolocation data
latitude
Latitude from IP geolocation data
longitude
Longitude from IP geolocation data
timezone
Timezone from IP geolocation data
isAnycast
true when the IP geolocation data marks the IP as anycast; otherwise false
userAgent
User agent from the ua request parameter. This field is returned when ua is provided
isBot
Visitor classification signal: 0 visitor/non-bot, 1 detected bot/threat, 2 user list match
blockAccess
Page action flag. 1 means your website should apply the configured block response; 0 means do not apply the block response
threatURL
Threat-related flag returned by the decision flow. 1 means the request was marked as threat-related
detectActivity
Human-readable decision description
pageResponseType
Page response type configured in the STOPBOT panel
pageResponseContents
Response value for the selected page response type
status
API result status. Successful Blocker V2 responses return success
executionTime
Server-side execution time for the request
timeResponse
Response timestamp in YYYY-MM-DD HH:mm:ss format
Use blockAccess for the final allow/block action. The detectActivity field explains the reason, while isBot is only a classification signal.
isBot and blockAccess are intentionally separate. A visitor can be human/non-bot but still be blocked by your configuration. For example, a country restriction can return:
In this case, the visitor is not classified as a bot, but your website should still apply the configured page response because blockAccess is 1.
Page Response Types
None
Stay on the current page. pageResponseContents may return Stay On Page
RedirectURL
Redirect the visitor to the URL in pageResponseContents
HTTPStatusCode
Return the HTTP status code stored in pageResponseContents
When blockAccess is 1, your integration should apply the configured block response. When blockAccess is 0, your integration should allow the request to continue.
Device Values
The device value used by the Blocker V2 decision flow is derived from the ua request parameter.
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
Blocker V2 does not return device as a top-level response field, but it uses this value in the decision flow and activity logs.
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:
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:
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:
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:
Decision Descriptions
The detectActivity value can include:
Visitor
No block reason detected
[Disallow] - IP Blacklist
IP matched STOPBOT IP blacklist or IP range checks
[Disallow] - Bad IP (Malicious Activity)
IP matched malicious activity or DNS blacklist checks
[Disallow] - Hostname
Hostname matched STOPBOT hostname checks
[Disallow] - Proxy | VPN | Tor
Proxy, VPN, Tor, or spam-source detection
[Disallow] - Country List
Country is not allowed by configuration
[Disallow] - IP Non-ISP
Non-ISP network blocked by configuration
[Disallow] - Spider Crawler
User agent matched bot or crawler detection
[Disallow] - Threat URL
Request matched threat-related repeated failed traffic logic
[Disallow] - Ad Bot Preview ({name})
Advertising bot preview detected by configured ad bot rules
[Disallow] - Device
Device type does not match the configuration
[Disallow] - Params
Submitted params JSON did not match configured Params rules
[Disallow] - Headers
Submitted headers JSON did not match configured HTTP Headers rules
[Disallow] - Blacklist IP (USER)
IP matched the user's own IP blacklist
[Allow] - Whitelist IP (USER)
IP matched the user's own IP whitelist
[Allow] - SearchEngine ({name})
Verified search engine visitor matched search engine handling rules
Error Response Fields
Failed Blocker V2 responses may include:
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
Last updated