> For the complete documentation index, see [llms.txt](https://docs.stopbot.net/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.stopbot.net/v2/api-v2-documentation/blocker-v2.md). # 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/blockerv2 ``` ### Parameters | Parameter | Required | Description | | ---------- | -------- | --------------------------------------------------------------------------------- | | `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 | Parameter | Rule | | ---------- | ----------------------------------------------------------------------------------------------------------- | | `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 ```bash curl "https://api.stopbot.net/services/blockerv2?apikey={API_KEY}&confname={CONFNAME}&ip=1.1.1.1&ua={USER_AGENT}&url=https%3A%2F%2Fexample.com¶ms=%7B%7D&headers=%7B%7D" ``` ### Example Response ```json { "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, "userAgent": "{USER_AGENT}", "isBot": 1, "blockAccess": 1, "threatURL": 0, "detectActivity": "[Disallow] - IP Non-ISP", "pageResponseType": "RedirectURL", "pageResponseContents": "https://example.com/blocked", "status": "success", "executionTime": "11.69ms", "timeResponse": "2026-07-07 12:00:00" } ``` ### Invalid Input Examples Invalid configuration name format: ```bash curl "https://api.stopbot.net/services/blockerv2?apikey={API_KEY}&confname=bad-conf&ip=1.1.1.1" ``` Response: ```json { "errorMessage": "Please enter a valid Configuration Name.", "status": "failed", "executionTime": "23.58us", "timeResponse": "2026-07-07 12:00:00" } ``` Invalid IP address: ```bash curl "https://api.stopbot.net/services/blockerv2?apikey={API_KEY}&confname={CONFNAME}&ip=not-an-ip" ``` Response: ```json { "errorMessage": "IP format is invalid.", "status": "failed", "executionTime": "1.23ms", "timeResponse": "2026-07-07 12:00:00" } ``` Configuration name is valid but not registered for the API key: ```json { "errorMessage": "Your Configuration Name is not registered in our database.", "status": "failed", "executionTime": "1.23ms", "timeResponse": "2026-07-07 12:00:00" } ``` ### Response 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 | | `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: ```json { "isBot": 0, "blockAccess": 1, "detectActivity": "[Disallow] - Country List" } ``` 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 | Type | Meaning | | ---------------- | -------------------------------------------------------------------------- | | `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. | 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 | 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: | 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 ``` ### Decision Descriptions The `detectActivity` value can include: | Value | Meaning | | ------------------------------------------ | -------------------------------------------------------------------- | | `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: | 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 |