RiskScore API

Risk intelligence guide

How to interpret verdicts, scores, and flags in RiskScore responses.

RiskScore responses combine location context with an intelligence object. Use the fields below to decide whether to allow, challenge, or block a connection in your application.

Response structure

Every successful lookup includes:

Section	Purpose
`location`	Country, city, region, coordinates, and timezone
`network`	ISP, ASN, and connection type
`intelligence`	Verdict, scores, flags, tags, and categories
`is_eu`	Whether the country is in the European Union

The cached field indicates whether the result was served from Syndaq's local store (true) or freshly enriched (false).

Verdict

intelligence.verdict is a machine-readable summary of the overall assessment. Common values include:

Verdict	Meaning
`clean`	No significant anonymity or threat signals detected
`anonymous_traffic`	VPN, proxy, Tor, or relay activity detected
`hosting_provider`	Address belongs to a hosting or cloud network
`malicious_activity`	Known malicious or abusive behavior associated with the IP

intelligence.description provides a human-readable explanation when available. Treat the verdict as a starting point and combine it with scores and flags for your policy.

Risk and threat scores

Field	Range	Description
`intelligence.risk.score`	0-100	Overall risk associated with the IP
`intelligence.risk.level`	string	Bucket such as `low`, `medium`, or `high`
`intelligence.threat.score`	0-100	Security threat indicator
`intelligence.threat.level`	string	Threat severity bucket

Higher scores indicate stronger signals. There is no universal threshold: calibrate cutoffs using your own traffic and false-positive tolerance.

Suggested starting points

These are guidelines, not guarantees. Adjust based on your industry and user base.

Scenario	Starting policy
Consumer login	Challenge when `risk.level` is `medium` or higher, or when `is_vpn` is true
Payment checkout	Block when `is_malicious` is true or `threat.level` is `high`
B2B SaaS signup	Flag `is_hosting` and `is_network_service` for manual review
Admin panels	Block any `anonymous_traffic` verdict regardless of score

Log the full response when you challenge or block so your team can tune rules over time.

Boolean flags

intelligence.flags contains quick checks for automation:

Flag	When true
`is_anonymous`	General anonymity signal (VPN, proxy, Tor, or relay)
`is_vpn`	Commercial or consumer VPN exit node
`is_proxy`	Open or anonymizing proxy
`is_tor`	Tor exit node
`is_relay`	Relay or forwarding service
`is_malicious`	Known malicious activity
`is_hosting`	Datacenter or hosting provider
`is_network_service`	Network service or infrastructure range

intelligence.anonymous_confidence (0-100) indicates confidence when anonymity is detected.

Tags and categories

intelligence.tags and intelligence.categories are string arrays with additional provider classifications. Use them for fine-grained rules, dashboards, or SIEM enrichment.

Example decision flow

1. Reject private or invalid IPs before calling RiskScore.
2. Call /v1/riskscore/lookup from your server at login or checkout.
3. If is_malicious is true, block immediately.
4. Else if risk.level is high, require step-up verification.
5. Else if is_vpn and your policy disallows VPN, challenge or block.
6. Else allow and store request_id for audit.

Combining with GeoIP

RiskScore includes basic location fields. If you only need country or city for personalization, the GeoIP API is lighter and optimized for geolocation. Use RiskScore when security signals matter more than postal-level accuracy.

Data freshness

Results are cached locally after the first successful enrichment. The fetched_at timestamp shows when Syndaq last refreshed the record. For high-stakes decisions, consider re-checking critical IPs periodically rather than relying on very old cache entries.