IP Risk Intelligence

IP Risk Intelligence helps you understand whether a request is coming from a regular user or from traffic such as a proxy, VPN, Tor exit node, hosting provider, residential proxy, or known bot traffic.

Available for accounts starting with the Team plan. For CAPTCHA verification, Enterprise plans can also include additional details in the server API response through the insights field.

Common use cases

Protect signups and logins

Use IP Risk Intelligence before creating a new account or completing a login. For example, if a login comes from a high-risk IP, you can ask the user to confirm the login by email before giving access.

Apply stricter rules to VPN and proxy traffic

Treat traffic differently when it comes from VPNs, proxies, Tor, or datacenter IPs. For example, you can allow the login itself, but require an additional verification step before changing account settings or starting a high-value action.

Identify bots and crawlers

Recognize known crawlers and AI tools so you can decide how they should interact with your service. For example, you can allow search crawlers on public pages while blocking automated access to signup, checkout, or password reset flows.

Add friction only when needed

Use the classification, signals, and risk score to trigger extra checks only when an IP looks suspicious. For example, instead of showing every user a confirmation step, you can only show email confirmation, one-time codes, or CAPTCHA when the request looks risky.

Send a request

Send a POST request to the following endpoint:

/v1/intelligence/ip-risk/check

Example:

curl https://api.captchafox.com/v1/intelligence/ip-risk/check \
  -X POST \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"ip":"198.51.100.24"}'

Request body

{
  "ip": "198.51.100.24" // The IPv4 or IPv6 address to check
}

Response body

The response may evolve over time, for example by adding new fields, but it will remain backward compatible.

{
  "classification": "residential_proxy", // Main classification
  "risk_level": "critical", // Risk level
  "risk_score": 86, // Numeric score (0-100)
  "ip": "198.51.100.24", // The IP address that was checked
  "version": 4, // IP version: 4 or 6
  "network": { // Network details, or null if unavailable
    "asn": 14061, // Autonomous system number
    "organization": "DigitalOcean, LLC", // Network owner
    "type": "hosting", // Connection type or network class
    "mobile": false // Whether it looks like mobile traffic
  },
  "location": { // Location details, or null if unavailable
    "country_code": "DE", // ISO country code
    "continent_code": "EU", // ISO continent code
    "continent": "Europe", // Continent name
    "country": "Germany", // Country name
    "state": "Hesse", // State or region
    "city": "Frankfurt", // City name
    "zip": "60311", // Postal code
    "latitude": 50.1109, // Latitude coordinate
    "longitude": 8.6821, // Longitude coordinate
    "timezone": "Europe/Berlin", // IANA timezone
    "currency_code": "EUR" // Local currency code
  },
  "proxy": { // Proxy details, or null if not available
    "confidence": "high", // Confidence in the proxy finding
    "type": "residential", // Detected proxy type
    "provider": "Bright Data", // Provider name when known
    "last_seen_at": "2025-01-10", // Last observed date
    "percent_days_seen": 100 // Share of recent days seen
  },
  "bot": { // Known bot details, or null if there is no match
    "confidence": "high", // Confidence in the bot match
    "provider": "Googlebot", // Bot provider or product name
    "category": "search_crawler" // Bot category
  },
  "signals": { // Boolean summary of common checks
    "bogon": false, // Private, loopback, or bogon IP
    "proxy": true, // Proxy signal present
    "vpn": false, // VPN signal present
    "tor": false, // Tor signal present
    "hosting": true, // Hosting or datacenter signal present
    "residential_proxy": true, // Residential proxy signal present
    "blocklist_match": false // Matched a blocklist
  }
}

Field reference

classification

Value	Meaning
`bogon`	Private, loopback, or otherwise non-routable IP.
`clean`	No significant risk was detected.
`known_bot`	The IP matches a known crawler or AI tool.
`hosting`	The IP looks like hosting or datacenter traffic without stronger proxy evidence.
`proxy`	The IP shows general proxy signals.
`vpn`	The IP shows VPN signals.
`tor`	The IP belongs to a Tor exit node.
`residential_proxy`	The IP shows residential proxy signals.
`mixed`	Multiple conflicting high-risk signals were found.

proxy.type

Value	Meaning
`proxy`	General proxy traffic.
`vpn`	VPN traffic.
`tor`	Tor exit node traffic.
`data_center`	Traffic from a datacenter or hosting environment.
`residential`	Residential proxy traffic.

bot.category

Value	Meaning
`search_crawler`	Search engine crawlers and similar indexing bots.
`ai_tool`	AI tools or AI agents.

Errors

If something goes wrong, the API returns a simple error response with an HTTP status code and an error code.

Status	Error code	Meaning
`400`	`invalid_input`	The IP address is missing or invalid.
`401`	`invalid_api_key`	The API key is missing, malformed, or unknown.
`403`	`api_not_enabled_for_plan`	Your plan does not include access to this API.
`403`	`token_not_allowed_for_api`	The API key exists, but it is not allowed to use this API.
`429`	`rate_limit_exceeded`	Too many requests were sent in a short time.
`429`	`api_quota_exceeded`	Your API request quota has been exhausted.
`503`	`upstream_unavailable`	The service is temporarily unavailable.

Overview Language Codes