--- title: "Calculate risk score from client IP" method: GET path: "/api/v1/risk-score" tags: ["Risk Score API"] --- # Calculate risk score from client IP `GET /api/v1/risk-score` 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 ## Response `200` Risk score calculated successfully - RiskScoreV1Dto — Comprehensive risk score response with detailed fraud analysis results. This response provides a complete assessment of the trustworthiness of the provided IP address and/or email, including a numerical score, risk classification, and detailed breakdown of all contributing factors. - `score` number, 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. - `ip` string, 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) - `email` string, 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. - `factors` RiskScoreFactorsDto, required — Comprehensive breakdown of factors contributing to the risk score calculation. This object separates analysis results into IP-specific and email-specific factors, allowing for granular understanding of what influenced the final risk score. **Null Handling**: - ip_factors: null when no IP was analyzed - email_factors: null when no email was analyzed **Score Calculation**: The final risk score is calculated by averaging the individual IP and email risk scores. - `ip_factors` IpFactorsDto — Detailed IP address analysis results and risk factor indicators. Each boolean field represents a specific characteristic or threat classification of the IP address. The risk_contribution field shows the calculated risk score for this IP address based on the detected factors. **Detection Methods**: Advanced fingerprinting, BGP analysis, threat intelligence feeds, behavioral pattern recognition, and real-time data lookups. - `is_proxy` boolean, required — Indicates if the IP address is operating as a proxy server. **Detection includes**: - HTTP/HTTPS proxies - SOCKS proxies (versions 4/5) - Transparent proxies - Elite/anonymous proxies **Risk Level**: Medium - Often used to hide real identity - `is_tor_node` boolean, required — Indicates if the IP address is part of the Tor anonymity network. **Detection covers**: - Tor exit nodes - Tor relay nodes - Tor bridge nodes **Risk Level**: High - Strong anonymization, often blocked by services **Data Source**: Real-time Tor consensus data - `is_spam` boolean, required — Indicates if the IP address has been associated with spam or malicious email activity. **Detection based on**: - Email spam campaigns - Malware command & control - Phishing attacks - Botnet activity **Risk Level**: High - Strong indicator of malicious intent **Update Frequency**: Real-time threat intelligence feeds - `is_vpn` boolean, required — Indicates if the IP address belongs to a VPN (Virtual Private Network) service. **Detection includes**: - Commercial VPN providers - Corporate VPN endpoints - Self-hosted VPN servers - VPN detection via traffic patterns **Risk Level**: Medium - Legitimate privacy tool, but can hide true location **Database Size**: 50M+ known VPN IP ranges - `is_datacenter` boolean, required — Indicates if the IP address originates from a datacenter or cloud hosting provider. **Provider types detected**: - Cloud providers (AWS, GCP, Azure, etc.) - Dedicated server hosts - VPS providers - Colocation facilities **Risk Level**: Medium - Less likely to be residential users **Use Cases**: Bot detection, residential verification - `risk_contribution` number, double, required — Risk score calculated for this IP address based on detected factors. **Value Range**: 0.0 to 1.0 - **0.0**: No risk detected - **0.05-0.25**: Low to medium risk factors present - **0.25-0.6**: High risk factors detected - **0.6-1.0**: Multiple high-risk factors present **Calculation**: Weighted sum of detected risk factors: - Tor node: +0.25, Proxy: +0.25, Threat: +0.25 - VPN: +0.2, Suspicious activity: +0.15 - Datacenter: +0.1, Spam source: +0.05 - `email_factors` EmailFactorsDto — Email address analysis results and validation factors. Provides comprehensive validation and reputation analysis for the email address, including syntax verification, domain reputation, and disposable email detection. **Validation Standards**: RFC 5322 compliance, domain verification, reputation scoring - `is_disposable` boolean, required — Indicates if the email address uses a disposable or temporary email service. **Disposable Email Services Detected**: - Temporary email providers (10MinuteMail, TempMail, etc.) - One-time use email generators - Throwaway email services - Self-destructing email addresses **Risk Level**: High - Often used to bypass verification systems **Database Coverage**: 10,000+ known disposable email domains **Update Frequency**: Daily updates from multiple threat intelligence sources - `is_valid_syntax` boolean, required — Indicates if the email address has valid syntax according to RFC 5322 standards. **Validation Checks**: - Proper @ symbol placement - Valid local part (before @) - Valid domain part (after @) - Correct character usage - Length limitations compliance - Special character handling **Standards Compliance**: RFC 5322, RFC 6532 (internationalized email) **Note**: Syntax validation does not guarantee deliverability - `risk_contribution` number, double, required — Risk score calculated for this email address based on validation results. **Value Range**: 0.0 to 1.0 - **0.0**: No risk detected (valid email with good reputation) - **0.4**: Disposable email service detected - **0.6**: Invalid email syntax detected - **1.0**: Multiple risk factors present (invalid + disposable) **Risk Factors**: - Invalid syntax: +0.6 risk score - Disposable email service: +0.4 risk score - Scores are capped at 1.0 maximum ## Other responses - `400` — Bad Request - Unable to extract valid IP address from request headers - `429` — Too Many Requests - Rate limit exceeded (check X-RateLimit-* headers) - `500` — Internal Server Error - Risk score calculation failed --- [API](https://skmtc.dev/ip-api/apis/ip-api-io-ip-geolocation-security-api.md) · [All operations](https://skmtc.dev/ip-api/apis/ip-api-io-ip-geolocation-security-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/ip-api/ip-api-io-ip-geolocation-security-api/revisions/a6862f586bf3/schema)