Sign in

v1

latestOpenAPI 3.1.0Commercial License2026-07-132434129.1 KB
Risk Score API

Calculate risk score from client IP

Automatically detects and analyzes the client's IP address from the HTTP request.

IP Detection Order:

  1. X-Real-IP header (preferred for load balancers/proxies)
  2. RemoteAddr from servlet request

Use Cases:

  • Real-time fraud detection during user sessions
  • Account creation risk assessment
  • Transaction monitoring without explicit IP parameter

Returns: Complete risk score analysis with risk factors breakdown

get/api/v1/risk-score

Response

Risk score calculated successfully

scorenumber double required

Risk score on a scale of 0.0-1.0, where higher values indicate greater risk.

Score Ranges:

  • 0.8-1.0: Very High Risk (immediate manual review recommended)
  • 0.6-0.8: High Risk (enhanced verification required)
  • 0.4-0.6: Medium Risk (standard verification procedures)
  • 0.2-0.4: Low Risk (low fraud probability)
  • 0.0-0.2: Very Low Risk (trusted, minimal verification needed)

The score is calculated by averaging individual risk factor scores from IP and email analysis. Risk factors are weighted based on their threat level and combined into a normalized score.

risk_level'VERY_LOW' | 'LOW' | 'MEDIUM' | 'HIGH' | 'VERY_HIGH' required

Human-readable risk classification derived from the numerical risk score.

Risk Levels:

  • VERY_HIGH (0.8-1.0): Immediate attention required, high probability of fraud
  • HIGH (0.6-0.8): Enhanced verification recommended, elevated fraud risk
  • MEDIUM (0.4-0.6): Standard verification sufficient, moderate risk
  • LOW (0.2-0.4): Minimal verification needed, low fraud probability
  • VERY_LOW (0.0-0.2): Trusted, very low risk

This classification helps in automated decision-making and risk-based workflows.

ipstring nullable

The IP address that was analyzed for this risk score calculation.

Null when: Only email analysis was requested (using /email/{email} endpoint) Present when: IP analysis was performed (either from request headers or explicit IP parameter)

Format can be IPv4 (e.g., 203.0.113.195) or IPv6 (e.g., 2001:db8::1)

emailstring nullable

The email address that was analyzed for this risk score calculation.

Null when: Only IP analysis was requested (using root endpoint or /{ip} without email param) Present when: Email analysis was performed (either via /email/{email} or as query parameter)

Always returned in lowercase, normalized format regardless of input casing.

Example response

{
  "score": 0.675,
  "risk_level": "HIGH",
  "ip": "203.0.113.195",
  "email": "user@example.com",
  "factors": {
    "ip_factors": {
      "is_proxy": false,
      "is_tor_node": false,
      "is_spam": true,
      "is_vpn": false,
      "is_datacenter": true,
      "risk_contribution": 0.15
    },
    "email_factors": {
      "is_disposable": false,
      "is_valid_syntax": true,
      "risk_contribution": 0
    }
  }
}