These docs cover two HTTPS APIs: VerifIP, an IP reputation and fraud-scoring API you call from your server, and DetectBT, browser bot detection whose tokens your server checks with POST /verify. VerifIP's GET /v1/check returns a 0–100 score, an allow / challenge / block verdict and the signals behind it. Every endpoint and field is in the OpenAPI spec.
How do I make my first API call?
Score an IP
One GET returns fraud_score (0–100), a verdict, ASN, geo, VPN/Tor/proxy flags, and a weighted signal breakdown.
curl -s "https://verifip.hextner.com/v1/check?ip=185.220.101.1" \ -H "Authorization: Bearer YOUR_API_KEY" # e.g. "verdict": "challenge", "is_tor": true (scores move as feeds refresh)Read VerifIP →• Client side
Verify the browser
Install DetectBT with one script tag and your publishable key. Send the token with sensitive requests; your server verifies it with POST /verify and a DetectBT secret key (sk_live_…, from the console).
<script src="https://detectbt-api.detectbt.workers.dev/detect-bt.js?key=vip_pub_…"></script>Read DetectBT →
1. Call the HTTPS API directly
There is nothing to install. Send your VerifIP API key (under API Keys → VerifIP) as a Bearer token from your server — never from browser code. Check the HTTP status before reading the body (see Integrating end to end). Query values must be URL-encoded: a + in an email address or phone number must be sent as %2B, or it arrives as a space. Every endpoint and field is in the OpenAPI spec.
curl -s "https://verifip.hextner.com/v1/check?ip=185.220.101.1" \ -H "Authorization: Bearer $VERIFIP_API_KEY" # Query values must be URL-encoded: a + in an email must be sent as %2B. # -G --data-urlencode does that for you: curl -sG "https://verifip.hextner.com/v1/email" \ --data-urlencode "email=user+tag@gmail.com" \ -H "Authorization: Bearer $VERIFIP_API_KEY"
import os, time, requests
# Retry only short, retryable refusals; never a degraded 503 (it has no verdict).
RETRYABLE = {"burst_limit_exceeded", "capacity_unavailable", "service_unavailable"}
def check_ip(ip, attempts=3):
for attempt in range(attempts):
r = requests.get(
"https://verifip.hextner.com/v1/check",
params={"ip": ip},
headers={"Authorization": f"Bearer {os.environ['VERIFIP_API_KEY']}"},
timeout=5,
)
if r.status_code == 200:
return r.json() # enforce on ["verdict"]
body = r.json()
if body.get("degraded"):
return None # 503 with no verdict: fail closed, do not retry
wait = int(r.headers.get("Retry-After", "0"))
if body.get("error") in RETRYABLE and 0 < wait <= 60 and attempt + 1 < attempts:
time.sleep(wait)
continue
raise RuntimeError(f"VerifIP {r.status_code}: {body.get('error')}")
raise RuntimeError("VerifIP: retries exhausted")// Retry only short, retryable refusals; never a degraded 503 (it has no verdict).
const RETRYABLE = new Set(["burst_limit_exceeded", "capacity_unavailable", "service_unavailable"]);
async function checkIp(ip: string, attempts = 3) {
for (let attempt = 0; attempt < attempts; attempt++) {
const res = await fetch(`https://verifip.hextner.com/v1/check?ip=${encodeURIComponent(ip)}`, {
headers: { Authorization: `Bearer ${process.env.VERIFIP_API_KEY}` },
signal: AbortSignal.timeout(5000),
});
if (res.ok) return res.json(); // enforce on .verdict
const body = await res.json();
if (body.degraded) return null; // 503 with no verdict: fail closed, do not retry
const wait = Number(res.headers.get("Retry-After") ?? 0);
if (RETRYABLE.has(body.error) && wait > 0 && wait <= 60 && attempt + 1 < attempts) {
await new Promise((resolve) => setTimeout(resolve, wait * 1000));
continue;
}
throw new Error(`VerifIP ${res.status}: ${body.error}`);
}
throw new Error("VerifIP: retries exhausted");
}package main
import (
"encoding/json"
"fmt"
"net/http"
"os"
"time"
)
func main() {
req, err := http.NewRequest("GET", "https://verifip.hextner.com/v1/check?ip=185.220.101.1", nil)
if err != nil {
panic(err)
}
req.Header.Set("Authorization", "Bearer "+os.Getenv("VERIFIP_API_KEY"))
client := &http.Client{Timeout: 5 * time.Second}
res, err := client.Do(req)
if err != nil {
fmt.Println("request failed:", err)
return
}
defer res.Body.Close()
if res.StatusCode != http.StatusOK {
// See Retries: a 503 whose body has degraded: true has no verdict (fail closed);
// burst 429 / capacity 503: wait Retry-After, a bounded number of times.
fmt.Println("status", res.StatusCode, "Retry-After", res.Header.Get("Retry-After"))
return
}
var result struct {
FraudScore int `json:"fraud_score"`
Verdict string `json:"verdict"`
}
if err := json.NewDecoder(res.Body).Decode(&result); err != nil {
fmt.Println("bad JSON:", err)
return
}
fmt.Println(result.Verdict, result.FraudScore) // enforce on Verdict
}2. Enforce on the verdict
An illustrative, abridged answer for a Tor exit that is also on blocklists. Live values for this address change as feeds refresh, so do not hard-code them in tests:
{
"ip": "185.220.101.1",
"ip_version": 4,
"fraud_score": 43,
"verdict": "challenge",
"threat_confidence": "low",
"threat_categories": ["tor", "proxy", "attacker"],
"is_tor": true,
"blocklist_count": 3,
"country_code": "DE",
"signal_breakdown": { "tor_exit": 25, "proxy_detected": 15, "datacenter_ip": 10, "blocklist_consensus": 12, "known_attacker": 15, "firehol_l2": 15 }
}Enforce on verdict; use fraud_score for ordering. The score is not the sum of the breakdown: correlated signals are combined, not stacked. A 503 whose body has degraded: true carries no verdict — fail closed. A 503 capacity_unavailable means nothing ran — retry after Retry-After.
How do I integrate VerifIP and DetectBT end to end?
- Get your keys. Create your VerifIP API key (under API Keys → VerifIP) for server calls. For browser checks, a DetectBT publishable key (
vip_pub_…) goes in your pages and a DetectBT secret key (sk_live_…) stays on your server. Keep both server keys in environment variables or a secrets manager. - Call from your server with
Authorization: Bearerand a timeout (a few seconds):GET /v1/check, or/v1/email,/v1/phone,/v1/url,/v1/assess. - Branch on the HTTP status before reading the body.
200: enforce onverdict(IP) or decide onrisk_score(email, phone, URL).400: fix the input; do not retry.401/403: a key or plan problem; do not retry.429and503 capacity_unavailable: wait theRetry-Afterheader.503withdegraded: true: no verdict; fail closed. Other5xx: back off and retry. - Know what a retry costs. A retry is a new request. A single call that returns a
5xx, including a degraded503, is billed 1 (not a503 service_unavailablewhere authentication or the quota counter was unreachable), so each retry of a degraded answer is billed again. Retrying aPOST /v1/reportthat was accepted stores a duplicate report and bills again.400,429andcapacity_unavailableare not billed. Details: When to retry. - Send the DetectBT token from the page to your server. In the page,
await DetectBT.getToken()(on a throw, send the request without a token; the first call reuses the script’s page-load evaluation if it is under 4.5 minutes old, so the usual flow costs one evaluation per page load) and put it in thex-detectbt-tokenheader, or the_detectbt_tokenfield of a form post. If your API is on another origin, the custom header makes the browser send a CORS preflight: allowx-detectbt-tokeninAccess-Control-Allow-Headers. - Verify it on your server with
POST /verify(your secret key, andexpected_origin), then apply the decision table. - Combine the two answers in your own code. VerifIP and DetectBT answer separately and do not share state; for example, refuse when either says block and step up when either is unsure.
There are no webhooks or callbacks: every answer comes back on the request that asked for it.
API references
Each product has its own reference page, with every endpoint, field and error code.
VerifIP API reference
Base URL https://verifip.hextner.com. Call it from your server with your VerifIP API key (under API Keys → VerifIP) as a Bearer token. Endpoints for IPs, emails, phones and URLs, every response field, signal weights, score bands, batch rules, IPv6, response headers, retries, rate limits and error codes.
DetectBT reference
Base URL https://detectbt-api.detectbt.workers.dev. The script tag takes your publishable key (vip_pub_…); your server calls POST /verify with a secret key (sk_live_…). The script’s methods, evaluate() error codes, the /verify request and response, the decision table and billing.
Where is the OpenAPI spec?
The official SDKs have been retired. Call the HTTPS API directly — examples above — or generate a client from the OpenAPI document the API serves itself: https://verifip.hextner.com/openapi.yaml.
These docs cover API 1.4.x. The info.version of that document identifies the API version. New fields are added to /v1 answers over time, so ignore fields you do not recognise rather than failing on them.
The data behind each answer, and the notices its licences require, are listed on Data sources & attribution.
This product includes GeoLite Data created by MaxMind, available from https://www.maxmind.com. IP blocklist data: The Spamhaus Project (DROP). Phishing data: PhishTank, CC BY-SA 2.5. Malware data: abuse.ch. Hextner uses the IP2Proxy LITE database for IP geolocation. Full notices: Data sources.
Guides and recipes
Protect checkout
End-to-end: DetectBT token + VerifIP score on the order endpoint.
Batch scanning
Score 1–100 IPs per request: one HTTP round trip for the whole batch instead of one per IP.
Caching verdicts
Complete answers are cached server-side for up to 15 minutes per Cloudflare location (IPv4 WHOIS: 24 hours); incomplete answers for at most 10 seconds; degraded answers never. Cache on your side too when the same IPs repeat.
Rate-limit headers
Reading X-RateLimit-* to pre-empt bursts across your fleet.
Retry tuning
Which 429s and 503s to retry, and how long to wait.
Environment variables
Loading keys from secrets managers -- Vault, AWS SM, Doppler, 1Password.
Best practices for production use
- Use environment variables for API keys -- never hardcode them.
- Reuse HTTP connections (keep-alive) rather than opening one per request.
- On a 429 or 503, wait the
Retry-Afterheader before retrying; never retry arate_limit_exceededbefore the window resets. - Use the batch endpoint when checking multiple IPs.
- Cache results on your side when checking the same IPs frequently. The server caches complete answers for up to 15 minutes (IPv4 WHOIS: 24 hours), incomplete ones for at most 10 seconds, and never caches a degraded answer.