Stopbot help and frequently asked questions

STOPBOT.NET is an API-driven visitor intelligence and traffic-decision platform for websites and applications. It analyzes request context and returns JSON signals that an application, SmartURLs client, or WordPress integration can use to allow, block, redirect, or otherwise handle a request.

Stopbot currently provides six focused services:

• Blocker for general visitor detection and access decisions.
• Blocker V2 for named configurations and page-response instructions.
• SmartURLs for detection-aware redirects.
• IP Lookup for IP, network, and location context.
• Email Validation for syntax and domain-level email signals.
• Phone Number Identify for international number validation and available metadata.

Any website, application, backend, redirect service, or server-side integration that can make HTTPS requests and process JSON can use the API. WordPress users can use the official plugin without writing the request-handling integration from scratch.

No. You must configure the required service in the panel and integrate the corresponding API response into your application. The WordPress plugin and SmartURLs clients provide ready-made enforcement for their specific use cases.

Blocker provides a general visitor decision with detection, threat, network, and access fields. Blocker V2 uses a named configuration, accepts additional request context such as JSON parameters and headers, and can return a configured page action through pageResponseType and pageResponseContents.

No detection system is perfect. Stopbot combines multiple signals to support a better access decision, but it cannot guarantee that every bot, threat, false positive, service interruption, or data-quality limitation will be eliminated. Integrations should use sensible fallback behavior and be tested against their own traffic.

Yes. Create and verify an account, then use panel.stopbot.net to manage the API key, services, configurations, lists, usage, and subscription information associated with that account.

Your API key is available from the Stopbot panel. The current API validates a 32-character alphanumeric key. Treat the full value as a secret; the Account endpoint masks it in successful responses.

Send it in the apikey query parameter on each /services/... request. Do not assume header authentication works unless the current documentation explicitly adds that capability.

A successful Account response includes the masked API key, package name, quota, current usage, expiration date, response timing, and success status. Use it to inspect account-level API access without exposing the complete key in the response.

The request can return HTTP 402 Payment Required with a failed status and a message asking you to increase the quota or extend the API-key duration. Review usage and expiration in the panel before retrying repeatedly.

Stopbot provides limited trial access after registration and email verification. Paid plans are prepaid subscriptions with a fixed duration and request quota. Under the current Terms of Service, payments are non-refundable except where applicable law requires otherwise, and unused requests do not carry over after expiration.

The panel provides account and subscription information, service configurations, SmartURLs, Blocker V2 configurations, Bot Redirect destinations, client allowlists and blocklists, visitor logs, statistics, settings, and related account features.

Open Blocker V2 in panel.stopbot.net, create a configuration, assign a unique configuration name, choose the required traffic rules and page response, then save it. Copy the exact name into the API request or WordPress plugin.

Bot Redirect is a reusable, named redirect destination consisting of a label and a valid URL. It can be selected where a Blocker V2 or SmartURLs configuration needs a custom redirect target, so the same destination does not have to be entered repeatedly.

The settings area supports IP and hostname allowlists, plus IP, hostname, and user-agent blocklists. Enter only the value type requested by the page, review broad patterns carefully, and verify the result with controlled traffic after saving.

Open the relevant service or configuration in the panel. Blocker, Blocker V2, and SmartURLs provide service-specific visitor data and statistics so you can inspect detection reasons, access results, visitor context, and traffic trends.

Some service operations are restricted when the account is on limited trial access or the subscription has expired. Review package, quota, and expiration information, then renew or update the account before attempting the restricted operation again.

The API key authenticates the account across services included by its active package. Service-specific resources such as a Blocker V2 configuration name or SmartURLs key name must still belong to that same account and be active.

The current public API is served from https://api.stopbot.net/services/. Service endpoints accept HTTPS GET requests and OPTIONS preflight requests. Other methods return HTTP 405. Responses use JSON and are marked as non-cacheable.

• /services/account
• /services/blocker
• /services/blockerv2
• /services/shorterlink
• /services/iplookup
• /services/email-validation
• /services/phonenumber

Use the current API documentation for endpoint-specific examples.

Every current service requires apikey. Traffic services require an IP address; Blocker V2 additionally requires confname; SmartURLs requires keyname; Email Validation requires email; and Phone Number Identify requires number. Optional fields vary by endpoint.

Yes. Use the URL/query builder in your programming language so spaces, ampersands, user agents, URLs, and other reserved characters are percent-encoded correctly. For Blocker V2, encode the complete JSON value supplied in params or headers as one query-parameter value.

Common responses include 200 for a processed result, 400 for malformed or missing input, 401 for an unknown API key, 402 for quota or expiration restrictions, 405 for an unsupported method, and 503 when a required service dependency is unavailable. Always inspect both the HTTP code and JSON body.

The API supports browser CORS requests, but placing an API key in public frontend JavaScript exposes it to every visitor. Make normal service calls from your server, trusted worker, plugin, or backend integration instead.

Not without adapting it. Legacy integrations use https://stopbot.net/api/... and may return different field names, nesting, status behavior, and SmartURLs verification semantics. Current integrations use https://api.stopbot.net/services/.... Keep the client and documentation version aligned with the endpoint family.

Blocker combines available IP and network context, user-agent analysis, URL threat checks, search-engine handling, configured country and device rules, and applicable allowlists or blocklists. The resulting fields describe both the visitor context and the access decision.

isBot describes the bot classification result. blockAccess describes whether the configured policy denies access. They are intentionally separate: a visitor can have isBot: 0 and blockAccess: 1 when another rule, such as country, network type, threat URL, or a client list, requires blocking.

threatURL reports the URL-threat result for the URL supplied with the request. Treat it as a dedicated signal; do not replace the final access decision with this field alone.

detectActivity is the human-readable reason associated with the detection or policy result. It is useful in visitor logs and diagnostics. Use blockAccess for enforcement rather than matching application behavior to a single reason string.

The flat response can include IP, hostname, ASN, userType, connectionType, company, ISP, location fields, coordinates, timezone, anycast status, detected device, user agent, bot status, access status, threat status, and the detection reason. Availability depends on the submitted data and the IP record.

Apply the decision on the server before returning protected content. Continue normal processing when blockAccess is 0. When it is 1, apply the denial behavior chosen by your integration. Log detectActivity for diagnosis, but do not block solely because isBot is nonzero unless that is your explicit policy.

The confname parameter selects a Blocker V2 configuration owned by the authenticated account. Named configurations let one account apply different rules and page responses to different websites, applications, campaigns, or request flows.

apikey, ip, and confname are required for a normal check. ua, url, params, and headers provide additional context when available. The latter two are URL-encoded JSON values.

No. The current response is flat. Visitor, network, decision, and page-response values are top-level fields, including isBot, blockAccess, threatURL, detectActivity, pageResponseType, and pageResponseContents.

pageResponseType identifies the configured action and pageResponseContents contains its value. RedirectURL supplies a redirect target, HTTPStatusCode supplies the configured HTTP status, and None means the visitor should remain on the current page.

Yes. Bot classification and policy enforcement are separate. A country restriction, hosting or network rule, threat result, list match, or another configuration decision can block a visitor that is not classified as a bot.

The API rejects the request with a client error instead of silently choosing another policy. Copy the exact configuration name from the panel, preserve its spelling, and confirm that it belongs to the same account as the API key.

No. Send only the context your policy needs. Remove passwords, API keys, authorization values, session cookies, tokens, nonces, payment data, and other secrets before creating the params or headers JSON. Keep values within the documented input limits.

SmartURLs is a redirect service that combines visitor detection with a SmartURL configuration. Your client sends the visitor context and keyname, then follows the returned redirect behavior instead of hard-coding one destination for every visitor.

keyname identifies a SmartURL created in the Stopbot panel. It is tied to the owning account, so it must be active and belong to the same account as the API key used in the request.

redirectTo contains the destination selected by the SmartURLs configuration and detection result. A client should validate that the response is successful and the destination is usable before sending the browser there; otherwise it should display its local error response.

When the current API returns jsResponse: 1, the current SmartURLs client uses the returned uniqueCode in its browser verification request, such as /rsc/rjs.json?uniqueCode=.... That verification endpoint returns the code to the API. Do not substitute the original keyname for the current verification token.

The API can return a processed response whose detection reason indicates an invalid key name and whose access decision blocks the request. Confirm key ownership, spelling, status, and API-key ownership before treating the problem as a network failure.

Use a client built for the same API generation. The legacy PHP client expects V1 response fields and a different JavaScript-tracking flow. The current PHP and Go clients handle the current flat response and uniqueCode verification behavior.

The PHP client can be served by a supported PHP web stack, including Apache or Nginx with PHP-FPM. The Go client builds into a standalone server and can run behind Nginx, Apache, Microsoft IIS, Caddy, or another trusted reverse proxy. Trust proxy headers only when direct origin access is prevented.

IP Lookup can return the normalized IP, hostname, ASN, user and connection classifications, company, ISP, city, district, region, postcode, country, coordinates, timezone, anycast status, and a success status. Some fields can be empty when the corresponding record has no value.

userType describes the classified type of IP user or network, connectionType describes the available connection classification, and isAnycast reports whether the IP record is identified as anycast. These are intelligence fields, not proof of a specific individual or physical device.

For a syntactically valid address, Email Validation separates the user and domain, checks disposable-domain status, and returns MX, SPF, and DMARC lookup results. The response exposes these as domain-level signals for your own acceptance policy.

No. It does not perform mailbox-level verification and does not guarantee that a specific inbox exists, belongs to the submitter, can receive a message, or will accept delivery.

The API request itself was processed successfully, so the response can have status: success while isEmail is false. Use isEmail for the email-format result rather than interpreting transport success as a valid address.

For a valid international number, the service can return a normalized phone number, line type, carrier, location, country code, validity result, and success status. Supply the number in an international format, including its country calling code.

Carrier and geocoding metadata depend on the numbering plan and available reference data. A valid number can therefore return an undetected carrier or an empty location. The result also does not prove current ownership, SIM activity, reachability, or identity.

The plugin checks public WordPress frontend page requests with the Blocker V2 API before WordPress renders the page. It applies the returned access and page-response decision to that request.

The plugin does not protect WordPress administration, login, AJAX, cron, REST, XML-RPC, or static asset requests. Images, CSS, JavaScript, fonts, media, favicon requests, and similar assets are skipped so they do not create visitor checks.

Install the plugin ZIP from the official download or the GitHub repository. Activate it, open Stopbot settings, enter the API key and exact Blocker V2 configuration name, run Save & Test Connection, then enable protection after the test succeeds.

The settings area is intended for WordPress administrators with the manage_options capability. Frontend visitors and ordinary user roles cannot manage the API key or protection settings.

The default bypass reduces the risk of locking an administrator out while configuring or testing protection. Test from an incognito or private window, log out first, or temporarily change the bypass setting when you intentionally need to test a logged-in role.

The plugin follows the API decision. A RedirectURL response redirects to the configured destination, an HTTPStatusCode response returns the configured status, and a non-blocking or None response allows WordPress to continue rendering the page.

The plugin provides a failure policy: allow the visitor or return HTTP 503. Choose the behavior that matches the availability and risk requirements of the site, then use the diagnostic log to investigate repeated connection failures.

The dedicated database table stores recent check details such as time, IP, country, ISP, hostname, device, OS, browser, detection description, accepted and threat results, and API connection status with the HTTP response code. It does not store API keys or full page URLs. The table is created on activation and removed on uninstall.

No. It calls the API for each eligible frontend page request so decisions do not become stale or cross between different URLs, user agents, query parameters, or headers. The settings screen refreshes the current visitor-log page every 60 seconds; that is a display refresh, not decision caching.

Enable them only when the site is always behind Cloudflare or another trusted reverse proxy or load balancer that controls the real-client-IP headers and direct origin access is prevented. Leave the option Off on normal hosting or when you are unsure, because untrusted forwarded headers can be spoofed.

Yes. Path mode supports multiple normalized paths. Exclude mode checks all eligible public pages except the listed paths; include mode checks only the listed paths. The plugin normalizes slashes so equivalent path forms are handled consistently.

Before redirecting, the plugin normalizes the current URL and configured destination, ignores the query string for the equality check, normalizes duplicate slashes, and compares HTTP and HTTPS consistently. It skips the redirect when the destination resolves to the current page. Path exclusions provide an additional safeguard for dedicated redirect destinations.

Keep it in a server-side secret store, environment variable, protected configuration file, or the WordPress settings storage. Do not commit it to a public repository, expose it in frontend JavaScript, paste it into public logs, screenshots, support messages, or publish complete request URLs containing the key.

A normal traffic check sends the API key, visitor IP, and endpoint-specific context such as user agent, current URL, configuration name, or SmartURLs key name. Blocker V2 can additionally receive selected query parameters and request headers. Send only what the policy needs and consult the Privacy Policy for public data-handling information.

The panel provides client-managed IP and hostname allowlists, IP and hostname blocklists, and a user-agent blocklist. Apply entries carefully, test changes with representative traffic, and remember that an allowlist can intentionally permit a matching visitor before later deny checks.

Headers such as CF-Connecting-IP, X-Real-IP, and X-Forwarded-For are trustworthy only when a controlled proxy overwrites them and the origin rejects direct public traffic. Otherwise a visitor can submit a forged header and influence IP-based decisions.

Do not broadly cache or reuse a traffic decision. The public API marks responses as non-cacheable, and a decision can depend on IP, URL, user agent, configuration, parameters, and headers. If an integration adds caching for a specialized use case, its key must include every decision input and its lifetime must match the accepted risk.

Use the dedicated Abuse Report for misuse of Stopbot services, or open the Support Center for technical assistance. Redact API keys, passwords, cookies, payment credentials, and personal secrets before submitting evidence.

HTTP 400 indicates malformed, missing, or unacceptable input. Check the 32-character API-key format, required endpoint parameters, IP or phone-number format, JSON syntax, URL encoding, input length, and the exact Blocker V2 configuration name.

HTTP 401 means the supplied API key was not found or could not authenticate the request. Confirm that the full value was copied without spaces, belongs to the intended account, and was not replaced by a masked key from an Account response or screenshot.

HTTP 402 indicates that the request quota is exhausted or the API-key duration has expired. Check quota, usage, package, and expiration in the panel or Account endpoint, then renew or increase access before retrying.

HTTP 503 means the endpoint could not use a required dependency or complete the service operation at that time. Check the public Service Status, apply the integration's configured fallback, and retry with backoff instead of creating a tight retry loop.

Confirm that protection is enabled, the connection test succeeds, the API key and configuration name are correct, and the page matches the include or exclude rules. Test while logged out or in an incognito window. Purge WordPress, server, LiteSpeed, and CDN full-page caches so the request reaches WordPress instead of a cached response.

The integration is probably reading the direct peer address while a reverse proxy sits in front of it. Configure the proxy to overwrite the real-IP header, prevent direct origin access, and then enable trusted proxy headers in the integration. Do not enable trust merely to make a test value appear correct.

Check whether the configured redirect target resolves back to the currently protected page, including equivalent HTTP/HTTPS forms, duplicate slashes, and query-string variants. Use a dedicated destination outside the protected include set or add it to the excluded paths. Purge page and CDN caches after changing the rule.

Inspect blockAccess and detectActivity together. The cause may be a country, hosting or network rule, threat URL, blacklist, invalid SmartURLs key name, or another configuration decision rather than bot classification. Verify the submitted IP, user agent, URL, configuration, and client lists before changing detection policy.

Confirm that the key name belongs to the API-key account, is active, and is copied exactly. Inspect redirectTo, jsResponse, uniqueCode, and detectActivity. For current clients, the browser verification request must return the supplied uniqueCode, not the original key name.

Check the current documentation and Service Status, then use the Support Center. Include the affected service, approximate request time and time zone, HTTP status, a redacted response, and the integration environment. Never include the full API key or session credentials.