> 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 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 |