IP Fraud Risk API

The Scamalytics IP Fraud Risk API provides real-time risk assessments for any IP address, combining Scamalytics' proprietary fraud intelligence with data from 10+ trusted external sources. Use it to detect VPNs, proxies, TOR exit nodes, and known fraud infrastructure before they reach your platform.

Base URLs

Choose the node closest to your infrastructure. Your account is tied to the node selected at sign-up.

UShttps://api11.scamalytics.com/v3/

EUhttps://api12.scamalytics.com/v3/

Response tiers

The fields returned depend on your subscription plan.

Tier	Included sources
Essential	Scamalytics score, ip2proxy_lite, MaxMind GeoLite2, IPInfo, FireHOL, IPsum, Spamhaus DROP, x4bnet, Google, Amazon AWS, Apple iCloud Private Relay
Premium	All Essential fields, plus populated values for DBIP (with the last 3 months of ISP/org history), the commercial ip2proxy feed, and `scamalytics_isp` / `scamalytics_org`. On Essential, these fields contain a placeholder string.

What you get on Premium

Both tiers return the identical response shape, with every key present on both, so your integration code doesn't change when you upgrade. On Essential, the Premium-gated fields below contain the placeholder string "PREMIUM FIELD - upgrade to view". On Premium, they hold real data. All other fields (the Scamalytics score, ip2proxy_lite, MaxMind, IPInfo, FireHOL, IPsum, Spamhaus, x4bnet, Google, AWS, Apple) are identical on both tiers.

The example values below are from a real lookup of 35.206.88.200 (a Google Cloud IP).

Field	Essential	Premium
scamalytics.scamalytics_isp	placeholder	`"Google Ireland Limited"`
scamalytics.scamalytics_org	placeholder	`"Google Cloud"`
external_datasources.dbip (all 11 fields)	placeholder	Full geolocation: country, state, district, city, postcode, lat/long, ISP and org names
dbip.connection_type	placeholder	One of `dialup`, `isdn`, `cable`, `dsl`, `fttx`, `wireless`, or `null`
dbip.history_monthly — ISP/org per month	placeholder	Last 3 months of ISP and org history
external_datasources.ip2proxy.proxy_type	placeholder	`"PUB"` with full taxonomy (VPN, TOR, DCH, PUB, WEB, SES), vs. `ip2proxy_lite` which only emits `PUB`

In Essential, every cell marked placeholder contains the literal string "PREMIUM FIELD - upgrade to view". See the right-hand panel for the full Essential and Premium responses side by side.

Quick start

Make a GET request with your key and an ip to look up:

# Replace {username} and {key} with your credentials curl "https://api12.scamalytics.com/v3/{username}?key={key}&ip=8.8.8.8"

The response is a JSON object. Check scamalytics.scamalytics_risk for a simple low / medium / high / very high classification, or use scamalytics_score (0–100) to fine-tune your own thresholds.

Example response Essential

{ "scamalytics": { "status": "ok", "mode": "live", "ip": "35.206.88.200", "scamalytics_score": 0, "scamalytics_risk": "low", "scamalytics_url": "https://scamalytics.com/ip/35.206.88.200", "scamalytics_isp": "PREMIUM FIELD - upgrade to view", "scamalytics_org": "PREMIUM FIELD - upgrade to view", "scamalytics_isp_score": 0, "scamalytics_isp_risk": "low", "scamalytics_proxy": { "is_datacenter": false, "is_vpn": false, "is_apple_icloud_private_relay": false, "is_amazon_aws": false, "is_google": true }, "is_blacklisted_external": false, "credits": { "used": 9929, "remaining": 490071, "last_sync_timestamp_utc": "2026-05-21 16:36:45", "seconds_elapsed_since_last_sync": 164, "note": "Credits used and remaining are approximate values." }, "exec": "32.29 ms" }, "external_datasources": { "dbip": { "ip_country_code": "PREMIUM FIELD - upgrade to view", "ip_state_name": "PREMIUM FIELD - upgrade to view", "ip_district_name": "PREMIUM FIELD - upgrade to view", "ip_city": "PREMIUM FIELD - upgrade to view", "ip_postcode": "PREMIUM FIELD - upgrade to view", "ip_geolocation": "PREMIUM FIELD - upgrade to view", "ip_country_name": "PREMIUM FIELD - upgrade to view", "isp_name": "PREMIUM FIELD - upgrade to view", "org_name": "PREMIUM FIELD - upgrade to view", "connection_type": "PREMIUM FIELD - upgrade to view", "history_monthly": { "03-2026": { "isp_name": "PREMIUM FIELD - upgrade to view", "org_name": "PREMIUM FIELD - upgrade to view" }, "04-2026": { "isp_name": "PREMIUM FIELD - upgrade to view", "org_name": "PREMIUM FIELD - upgrade to view" }, "05-2026": { "isp_name": "PREMIUM FIELD - upgrade to view", "org_name": "PREMIUM FIELD - upgrade to view" } }, "datasource_name": "db-ip.com", "license_info": "[email protected]" }, "ip2proxy": { "proxy_type": "PREMIUM FIELD - upgrade to view", "datasource_name": "ip2proxy.com", "license_info": "[email protected]" }, "ip2proxy_lite": { "asn": "43515", "as_name": "Google Ireland Limited", "proxy_type": "PUB", "proxy_last_seen": "1", "usage_type": "DCH", "ip_blacklisted": false, "ip_blacklist_type": "", "ip_provider": "", "ip_country_code": "US", "ip_country_name": "United States of America", "ip_district_name": "Iowa", "ip_city": "Council Bluffs", "isp_name": "Google LLC", "domain": "google.com", "datasource_name": "https://lite.ip2location.com/ip2proxy-lite", "license_info": "https://creativecommons.org/licenses/by-sa/4.0", "last_updated_timestamp_utc": "2026-05-21 08:16:19" }, "maxmind_geolite2": { "asn": "15169", "as_name": "Google LLC", "ip_geoname_id": "4852832", "ip_location_accuracy_km": "20", "ip_country_code": "US", "ip_state_name": "Iowa", "ip_district_name": "", "ip_city": "Council Bluffs", "ip_metro_code": "652", "ip_postcode": "51502", "ip_geolocation": "41.2591,-95.8517", "ip_country_name": "United States", "ip_time_zone": "America/Chicago", "datasource_name": "maxmind.com and geonames.org", "license_info": "https://creativecommons.org/licenses/by-sa/4.0", "last_updated_timestamp_utc": "2026-05-21 06:21:40" }, "ipinfo": { "asn": "AS43515", "ip_range_from": "35.206.32.0", "ip_range_to": "35.206.127.255", "as_name": "Google Ireland Limited", "as_domain": "google.com", "ip_country_code": "US", "ip_country_name": "United States", "ip_continent_code": "NA", "ip_continent_name": "North America", "datasource_name": "ipinfo.io", "license_info": "https://creativecommons.org/licenses/by-sa/4.0", "last_updated_timestamp_utc": "2026-05-21 04:05:09" }, "firehol": { "ip_blacklisted_30": false, "ip_blacklisted_1day": false, "is_proxy": true, "datasource_name": "https://iplists.firehol.org/", "license_info": "GPL v2", "last_updated_timestamp_utc": "2026-05-21 02:05:35" }, "ipsum": { "ip_blacklisted": false, "num_blacklists": 0, "datasource_name": "https://github.com/stamparm/ipsum", "license_info": "https://unlicense.org/", "last_updated_timestamp_utc": "2026-05-21 05:00:21" }, "spamhaus_drop": { "ip_blacklisted": false, "datasource_name": "https://www.spamhaus.org/drop", "license_info": "https://www.spamhaus.org/drop/terms/", "last_updated_timestamp_utc": "2026-05-21 07:00:02" }, "x4bnet": { "is_vpn": false, "is_datacenter": true, "is_tor": false, "is_blacklisted_spambot": false, "is_bot_operamini": false, "is_bot_semrush": false, "datasource_name": "https://github.com/X4BNet/", "license_info": "https://www.gnu.org/licenses/agpl-3.0.en.html", "last_updated_timestamp_utc": "2026-05-21 11:00:23" }, "google": { "is_google_general": true, "is_googlebot": false, "is_special_crawler": false, "is_user_triggered_fetcher": false, "is_google_cloud": true, "datasource_name": "https://developers.google.com/", "last_updated_timestamp_utc": "2026-05-21 12:00:04" }, "amazon_aws": { "data": [], "datasource_name": "https://docs.aws.amazon.com/", "last_updated_timestamp_utc": "2026-05-21 13:00:04" }, "apple_icloud_private_relay": { "data": { "ip_prefix": "", "country_code": "", "state_code": "", "city": "", "postcode": "" }, "datasource_name": "https://developer.apple.com/", "last_updated_timestamp_utc": "2026-05-21 14:00:52" } } }

Same lookup on Premium Premium

{ "scamalytics": { "status": "ok", "mode": "live", "ip": "35.206.88.200", "scamalytics_score": 0, "scamalytics_risk": "low", "scamalytics_url": "https://scamalytics.com/ip/35.206.88.200", "scamalytics_isp": "Google Ireland Limited", "scamalytics_org": "Google Cloud", "scamalytics_isp_score": 0, "scamalytics_isp_risk": "low", "scamalytics_proxy": { "is_datacenter": false, "is_vpn": false, "is_apple_icloud_private_relay": false, "is_amazon_aws": false, "is_google": true }, "is_blacklisted_external": false, "credits": { "used": 9928, "remaining": 490072, "last_sync_timestamp_utc": "2026-05-21 16:36:53", "seconds_elapsed_since_last_sync": 189, "note": "Credits used and remaining are approximate values." }, "exec": "26.52 ms" }, "external_datasources": { "dbip": { "ip_country_code": "US", "ip_state_name": "Iowa", "ip_district_name": "Pottawattamie", "ip_city": "Council Bluffs", "ip_postcode": "51502", "ip_geolocation": "41.2619,-95.8608", "ip_country_name": "United States", "isp_name": "Google Ireland Limited", "org_name": "Google Cloud", "connection_type": null, "history_monthly": { "03-2026": { "isp_name": "Google LLC", "org_name": "Google Cloud" }, "04-2026": { "isp_name": "Google LLC", "org_name": "Google Cloud" }, "05-2026": { "isp_name": "Google LLC", "org_name": "Google Cloud" } }, "datasource_name": "db-ip.com", "license_info": "[email protected]" }, "ip2proxy": { "proxy_type": "PUB", "datasource_name": "ip2proxy.com", "license_info": "[email protected]" }, "ip2proxy_lite": { "asn": "43515", "as_name": "Google Ireland Limited", "proxy_type": "PUB", "proxy_last_seen": "1", "usage_type": "DCH", "ip_blacklisted": false, "ip_blacklist_type": "", "ip_provider": "", "ip_country_code": "US", "ip_country_name": "United States of America", "ip_district_name": "Iowa", "ip_city": "Council Bluffs", "isp_name": "Google LLC", "domain": "google.com", "datasource_name": "https://lite.ip2location.com/ip2proxy-lite", "license_info": "https://creativecommons.org/licenses/by-sa/4.0", "last_updated_timestamp_utc": "2026-05-21 08:16:19" }, "maxmind_geolite2": { "asn": "15169", "as_name": "Google LLC", "ip_geoname_id": "4852832", "ip_location_accuracy_km": "20", "ip_country_code": "US", "ip_state_name": "Iowa", "ip_district_name": "", "ip_city": "Council Bluffs", "ip_metro_code": "652", "ip_postcode": "51502", "ip_geolocation": "41.2591,-95.8517", "ip_country_name": "United States", "ip_time_zone": "America/Chicago", "datasource_name": "maxmind.com and geonames.org", "license_info": "https://creativecommons.org/licenses/by-sa/4.0", "last_updated_timestamp_utc": "2026-05-21 06:21:38" }, "ipinfo": { "asn": "AS43515", "ip_range_from": "35.206.32.0", "ip_range_to": "35.206.127.255", "as_name": "Google Ireland Limited", "as_domain": "google.com", "ip_country_code": "US", "ip_country_name": "United States", "ip_continent_code": "NA", "ip_continent_name": "North America", "datasource_name": "ipinfo.io", "license_info": "https://creativecommons.org/licenses/by-sa/4.0", "last_updated_timestamp_utc": "2026-05-21 04:05:08" }, "firehol": { "ip_blacklisted_30": false, "ip_blacklisted_1day": false, "is_proxy": true, "datasource_name": "https://iplists.firehol.org/", "license_info": "GPL v2", "last_updated_timestamp_utc": "2026-05-21 02:05:36" }, "ipsum": { "ip_blacklisted": false, "num_blacklists": 0, "datasource_name": "https://github.com/stamparm/ipsum", "license_info": "https://unlicense.org/", "last_updated_timestamp_utc": "2026-05-21 05:00:21" }, "spamhaus_drop": { "ip_blacklisted": false, "datasource_name": "https://www.spamhaus.org/drop", "license_info": "https://www.spamhaus.org/drop/terms/", "last_updated_timestamp_utc": "2026-05-21 07:00:02" }, "x4bnet": { "is_vpn": false, "is_datacenter": true, "is_tor": false, "is_blacklisted_spambot": false, "is_bot_operamini": false, "is_bot_semrush": false, "datasource_name": "https://github.com/X4BNet/", "license_info": "https://www.gnu.org/licenses/agpl-3.0.en.html", "last_updated_timestamp_utc": "2026-05-21 11:00:23" }, "google": { "is_google_general": true, "is_googlebot": false, "is_special_crawler": false, "is_user_triggered_fetcher": false, "is_google_cloud": true, "datasource_name": "https://developers.google.com/", "last_updated_timestamp_utc": "2026-05-21 12:00:05" }, "amazon_aws": { "data": [], "datasource_name": "https://docs.aws.amazon.com/", "last_updated_timestamp_utc": "2026-05-21 13:00:04" }, "apple_icloud_private_relay": { "data": { "ip_prefix": "", "country_code": "", "state_code": "", "city": "", "postcode": "" }, "datasource_name": "https://developer.apple.com/", "last_updated_timestamp_utc": "2026-05-21 14:00:53" } } }

Authentication

All API requests require two credentials: your username (included in the URL path) and your API key (passed as a query parameter). Both are provided when you sign up at scamalytics.com.

⚠

Keep your API key secret. Do not expose it in client-side JavaScript, mobile apps, or public repositories. Route API calls through your own backend to keep the key private.

Request format

Your credentials are passed in the URL as follows:

https://<node>.scamalytics.com/v3/{username}?key={key}&ip={ip}

Credential	Where	Description
username	URL path	Your account username, included in the path segment of the URL
key	Query parameter	Your secret API key. Treat this like a password and never expose it client-side

Obtaining credentials

Sign up at scamalytics.com to receive your username and API key. Free tier accounts include 5,000 credits per month. Contact [email protected] to upgrade to Essential or Premium.

Authentication errors

If your key is invalid or missing, the API returns an HTTP 401 status with a JSON error body:

{ "scamalytics": { "status": "error", "error": "Unauthorized: invalid API key" } }

Test mode

Append test=1 to any request to avoid consuming credits during development. See Rate Limiting for fair-use limits on test calls.

Authentication Examples

cURL

Python

Node.js

PHP

Rate Limiting & Credits

API usage is metered via a credit system. Each successful live API call consumes one credit. Credits reset at the start of each calendar month.

✓

Test mode is free. Add test=1 to any request to run it without consuming credits. Ideal for integration testing and development. Fair-use limit: test calls must not exceed 5% of your monthly credit allowance.

Credits object

Every response includes a credits object showing your current usage:

Field	Type	Description
used	integer	Credits consumed this month (approximate)
remaining	integer	Credits remaining this month (approximate)
last_sync_timestamp_utc	string	UTC timestamp of last credit sync
seconds_elapsed_since_last_sync	integer	Seconds since last sync
note	string	Any notes about credit accounting

Test mode limits

As a fair-use policy, test calls should not exceed 5% of your monthly credit allowance. Free accounts are limited to 250 test calls per month. Exceeding this may result in test calls being rejected.

Excess usage

Requests made after credits are exhausted will return an error response. Monitor credits.remaining in your responses to avoid interruption, or contact [email protected] to upgrade your plan.

Credits in Response

"credits": { "used": 95, "remaining": 11905, "last_sync_timestamp_utc": "2024-03-27 12:13:03", "seconds_elapsed_since_last_sync": 31, "note": "Credits used and remaining are approximate values." }

Test Mode Request

# Add test=1 — no credits consumed curl "https://api12.scamalytics.com/v3/{username} ?key={key}&ip=8.8.8.8&test=1" # Response will show mode: "test" { "scamalytics": { "mode": "test", ... } }

GET /{username}?key={key}&ip={ip}

Lookup IP Address

Returns a fraud risk score and network intelligence for any IPv4/IPv6 address. Combines Scamalytics' proprietary scoring with additional data from 10+ trusted external sources. Responds in under 50ms excluding network time.

Parameters

Parameter	Type		Description
username	string	required	Your account username, included in the URL path (e.g. `/v3/your_username`). Provided at sign-up.
key	string	required	Your API authentication key
ip	string	required	IPv4 or IPv6 address to query (e.g. `66.220.149.25`)
test	integer	optional	Omit or set to `0` for live mode. Set to `1` for test mode with fair use policy.

Response: Scamalytics object

Field	Type	Tier	Description
status	string	Essential	`ok` or `error`. If error, an `error` field contains the message.
mode	string	Essential	`live` or `test`
ip	string	Essential	The IP address that was queried
scamalytics_score	integer	Essential	Fraud risk score from 0 (safe) to 100 (high risk). Represents approximate fraud probability.
scamalytics_risk	string	Essential	`low` / `medium` / `high` / `very high`
scamalytics_url	string	Essential	URL to the full IP report on scamalytics.com, useful for linking in moderation dashboards
scamalytics_isp	string	Premium	ISP name associated with the IP. On Essential, contains the placeholder `"PREMIUM FIELD - upgrade to view"`.
scamalytics_org	string	Premium	Organisation name associated with the IP. On Essential, contains the placeholder `"PREMIUM FIELD - upgrade to view"`.
scamalytics_isp_score	integer	Essential	Risk score for the IP's ISP network as a whole
scamalytics_isp_risk	string	Essential	Risk classification for the ISP
scamalytics_proxy.is_datacenter	boolean	Essential	IP is from a data centre or cloud provider
scamalytics_proxy.is_vpn	boolean	Essential	IP is detected as a VPN exit node
scamalytics_proxy.is_apple_icloud_private_relay	boolean	Essential	IP is Apple iCloud Private Relay
scamalytics_proxy.is_amazon_aws	boolean	Essential	IP is part of Amazon AWS infrastructure
scamalytics_proxy.is_google	boolean	Essential	IP is associated with Google services
is_blacklisted_external	boolean	Essential	IP appears on at least one external blacklist
credits	object	Essential	Credit usage info. See Rate Limiting for the full schema.
exec	string	Essential	Server-side execution time in milliseconds

Code examples

Look up an IP in your language of choice. Replace {username} and {key} with your credentials.

cURL

Python

Node.js

PHP

Risk Scores

The scamalytics_score is an integer from 0 to 100 representing the fraud risk associated with an IP address. It is a proprietary signal produced by Scamalytics, not a passthrough from a third-party feed, and is the most differentiated value the API returns.

ℹ

A score of 70 means that roughly 7 in 10 users seen from that IP have been associated with fraudulent behaviour. A score of 0 means no known risk. This is an approximation, so always model and fine-tune thresholds against your own data.

Score to risk mapping

0–19 · low 20–59 · medium 60–89 · high 90–100 · very high

Score range	Risk level	Suggested action
0–19	low	Allow with no additional friction required
20–59	medium	Display CAPTCHA or apply additional checks
60–89	high	Require SMS verification or step-up authentication
90–100	very high	Block or flag for manual review

⚠

The suggested actions above are a starting point. Scamalytics recommends modelling thresholds against your own fraud data to find the balance between fraud prevention and customer friction that fits your business.

ISP score

In addition to the per-IP score, scamalytics_isp_score provides a risk score for the ISP as a whole. This is useful when the specific IP has limited history but the ISP is known to be high-risk (e.g. a datacenter or anonymising service provider).

Handling Risk in Code

# Python: act on risk level result = check_ip("66.220.149.25") risk = result["scamalytics"]["scamalytics_risk"] score = result["scamalytics"]["scamalytics_score"] if risk == "very high": block_request() elif risk == "high": require_sms_verification() elif risk == "medium": show_captcha() else: allow_request() # Or use raw score for fine-grained control if score >= 85: flag_for_review()

Score in Response

{ "scamalytics_score": 87, "scamalytics_risk": "high", "scamalytics_isp_score": 72, "scamalytics_isp_risk": "high" }

Proxy Types

The proxy_type field (returned by ip2proxy and ip2proxy_lite) classifies the type of proxy or anonymising service detected at the IP address. A value of 0 means no proxy was detected.

Type reference

Code	Name	Description
0	No proxy	No proxy detected or unknown.
VPN	VPN	Anonymising VPN service. Public VPN offering designed to hide the user's real IP address (e.g. NordVPN, ExpressVPN).
TOR	Tor Exit Node	The Tor network exit node. Tor routes traffic through multiple relays, and exit nodes are where traffic leaves the network. Strongly associated with anonymisation.
DCH	Datacenter / CDN	Hosting provider, data centre, or content delivery network. These can be used to provide anonymity or run automated bots.
PUB	Public Proxy	Open proxy server making connection requests on a user's behalf. Differs from VPNs in that they typically only handle web traffic on specific ports.
WEB	Web Proxy	Web-based proxy service that makes HTTP requests on a user's behalf. Operates at the application layer, not at the IP level.
SES	Search Engine Bot	Search engine spider or bot (e.g. Googlebot, Bingbot, Semrush). May indicate automated scraping rather than a human user.

ℹ

Proxy type is available via ip2proxy_lite (Essential tier) and ip2proxy (Premium tier). The lite version only identifies public proxies, so proxy_type will be either PUB or 0. The full Premium ip2proxy feed returns the complete set of types (VPN, TOR, DCH, PUB, WEB, SES) with higher detection accuracy. For VPN, Tor, and datacenter detection on the Essential tier, use the top-level scamalytics_proxy booleans and the x4bnet data source.

Proxy Fields in Response

// Top-level boolean flags (all tiers) "scamalytics_proxy": { "is_datacenter": true, "is_vpn": true, "is_apple_icloud_private_relay": false, "is_amazon_aws": false, "is_google": false }, // Detailed proxy type from ip2proxy_lite (PUB or 0 only) "ip2proxy_lite": { "proxy_type": "PUB", "ip_provider": "-", "proxy_last_seen": "30" }, // x4bnet for TOR / datacenter detection "x4bnet": { "is_vpn": true, "is_datacenter": true, "is_tor": false }

Data Sources

The external_datasources object contains enrichment data from multiple third-party and open-source feeds, each providing different intelligence about the IP address.

Essential tier sources

ip2proxy_lite

Public proxy detection (PUB only) plus ASN, usage type, and IP blacklist data. CC BY-SA 4.0.

Essential

MaxMind GeoLite2

ASN, geolocation (country, state, city, postcode, coordinates), timezone, and accuracy radius. CC BY-SA 4.0.

Essential

IPInfo

ASN, IP range, country, and continent data. CC BY-SA 4.0.

Essential

FireHOL

Blacklist status over the last 30 days and 1 day, plus a basic proxy flag. GPL v2.

Essential

IPsum

Aggregate blacklist showing the number of blacklists the IP appears on across the IPsum feed. Unlicense.

Essential

Spamhaus DROP

Spamhaus Don't Route Or Peer list of IPs controlled by spam or cybercrime operations.

Essential

x4bnet

VPN, datacenter, TOR, spambot, and bot detection (Opera Mini, Semrush). AGPL 3.0.

Essential

Google

Identifies Google services, Googlebot, special crawlers, and user-triggered fetchers.

Essential

Amazon AWS

Detects whether the IP belongs to Amazon AWS. Returns a data array that is empty when there is no match, and populated with AWS network metadata when the IP is in an AWS range.

Essential

Apple iCloud Private Relay

Identifies Apple Private Relay exit nodes. Returns a data object with ip_prefix, country_code, state_code, city, and postcode (empty strings when not a relay IP).

Essential

Premium tier sources

Premium is additive: a Premium subscription includes everything in the Essential tier above, plus the two commercial sources below. Upgrading never removes or replaces Essential data; it unlocks these extra feeds (and the Premium-gated fields described in the Introduction). On Essential, these sources are still present in the response but their values read "PREMIUM FIELD - upgrade to view".

DBIP (commercial)

Full geolocation with ISP, organisation, connection type, and the last 3 months of historical ISP/org data. Commercial feed, licensed via Scamalytics.

Premium

ip2proxy (commercial)

Full proxy type detection covering VPN, Tor, datacenter, public proxy, web proxy, and search engine bots, with higher accuracy and coverage than the free lite tier (which is limited to PUB).

Premium

External datasources structure

{ "external_datasources": { // Essential: ip2proxy_lite (proxy_type is PUB or 0 on lite) "ip2proxy_lite": { "asn": "32934", "proxy_type": "PUB", "ip_blacklisted": true, "ip_blacklist_type": "BOTNET" }, // Essential: FireHOL (30-day and 1-day blacklist signals) "firehol": { "ip_blacklisted_30": false, "ip_blacklisted_1day": false, "is_proxy": false }, // Essential: IPsum "ipsum": { "ip_blacklisted": true, "num_blacklists": 7 }, // Premium tier: populated; on Essential each value is "PREMIUM FIELD - upgrade to view" "dbip": { "isp_name": "Facebook, Inc.", "history_monthly": { "03-2026": { "isp_name": "Facebook, Inc." }, "04-2026": { "isp_name": "Facebook, Inc." }, "05-2026": { "isp_name": "Facebook, Inc." } } } } }

Field Reference

Complete reference for all fields returned by each data source in the external_datasources object.

ℹ

Tier placeholder. The response shape is identical on Essential and Premium. Fields marked Premium below, including everything under dbip and the ip2proxy.proxy_type field, exist on Essential responses too, but their values are replaced with the string "PREMIUM FIELD - upgrade to view". This means you can build against the Premium schema today and the data will light up on upgrade without code changes.

ip2proxy_lite

Field	Type	Description
asn	string	Autonomous System Number
as_name	string	Organisation that owns the ASN
proxy_type	string	Only `PUB` (public proxy) or `0` (no proxy) on the Essential lite feed. The full set (VPN, TOR, DCH, PUB, WEB, SES) is only emitted by the Premium `ip2proxy` source.
proxy_last_seen	string	Hours since the proxy was last observed
usage_type	string	Connection usage type (e.g. `COM` for commercial)
ip_blacklisted	boolean	IP appears on a blacklist
ip_blacklist_type	string	Category of blacklist (e.g. `BOTNET`)
ip_provider	string	VPN or proxy provider name
ip_country_code	string	ISO 2-letter country code
ip_country_name	string	Country name
ip_district_name	string	District / sub-region name
ip_city	string	City name
isp_name	string	ISP name
domain	string	Primary domain associated with the IP

ip2proxy Premium

Field	Type	Description
proxy_type	string	Full proxy type classification: `0` (no proxy), `VPN`, `TOR`, `DCH`, `PUB`, `WEB`, or `SES`. See Proxy Types for descriptions.

maxmind_geolite2

Field	Type	Description
asn	string	ASN number
as_name	string	Organisation that owns the ASN
ip_geoname_id	string	GeoNames location ID
ip_location_accuracy_km	string	Geolocation accuracy radius in kilometres
ip_country_code	string	ISO 2-letter country code
ip_country_name	string	Country name
ip_state_name	string	State or region name
ip_district_name	string	District / sub-region name
ip_city	string	City name
ip_metro_code	string	Metro / DMA code (US only)
ip_postcode	string	Postal code
ip_geolocation	string	Latitude and longitude as `"lat,lon"`
ip_time_zone	string	IANA timezone (e.g. `America/Los_Angeles`)

dbip Premium

Field	Type	Description
isp_name	string	ISP name
org_name	string	Organisation name
connection_type	string	One of `dialup`, `isdn`, `cable`, `dsl`, `fttx`, `wireless`, or `null`
ip_country_code	string	ISO 2-letter country code
ip_country_name	string	Country name
ip_state_name	string	State or region name
ip_district_name	string	District / sub-region name
ip_city	string	City name
ip_postcode	string	Postal code
ip_geolocation	string	Latitude and longitude as `"lat,lon"`
history_monthly	object	Per-month ISP and org history, keyed by `MM-YYYY`

x4bnet

Field	Type	Description
is_vpn	boolean	VPN detected
is_datacenter	boolean	Datacenter IP
is_tor	boolean	TOR exit node
is_blacklisted_spambot	boolean	Listed as a spambot
is_bot_operamini	boolean	Opera Mini browser bot
is_bot_semrush	boolean	Semrush crawler bot

ipinfo

Field	Type	Description
asn	string	ASN, prefixed with `AS` (e.g. `AS4760`)
as_name	string	Organisation that owns the ASN
as_domain	string	Primary domain of the AS operator
ip_range_from	string	First IP in the matched range
ip_range_to	string	Last IP in the matched range
ip_country_code	string	ISO 2-letter country code
ip_country_name	string	Country name
ip_continent_code	string	Continent code (e.g. `AS`, `EU`)
ip_continent_name	string	Continent name

firehol

Field	Type	Description
ip_blacklisted_30	boolean	IP appears on a FireHOL blacklist within the last 30 days
ip_blacklisted_1day	boolean	IP appears on a FireHOL blacklist within the last 1 day
is_proxy	boolean	IP is listed as a proxy by FireHOL

ipsum

Field	Type	Description
ip_blacklisted	boolean	IP appears on at least one IPsum blacklist
num_blacklists	integer	Number of IPsum blacklists the IP appears on (higher = stronger signal)

spamhaus_drop

Field	Type	Description
ip_blacklisted	boolean	IP is on the Spamhaus Don't Route Or Peer list

google

Field	Type	Description
is_google_general	boolean	IP belongs to Google's general IP ranges
is_googlebot	boolean	Verified Googlebot crawler
is_special_crawler	boolean	Google special-purpose crawler (e.g. AdsBot, Mediapartners)
is_user_triggered_fetcher	boolean	Google service fetching on behalf of a user action (e.g. link preview)
is_google_cloud	boolean	IP is part of Google Cloud Platform

amazon_aws

Field	Type	Description
data	array	Empty array when the IP is not in any AWS range, populated with matching AWS network entries when it is.

apple_icloud_private_relay

Field	Type	Description
data.ip_prefix	string	CIDR prefix of the Private Relay range (empty if not a relay IP)
data.country_code	string	Country code declared by Apple for the exit node
data.state_code	string	State or region code declared by Apple
data.city	string	City declared by Apple
data.postcode	string	Postal code declared by Apple

ℹ

Every external_datasources entry also includes datasource_name (source URL or identifier), license_info, and (for most sources) last_updated_timestamp_utc. These metadata fields aren't listed in the per-source tables above.

Full Essential Response

"external_datasources": { "ip2proxy_lite": { "asn": "32934", "as_name": "FACEBOOK", "proxy_type": "PUB", "proxy_last_seen": "30", "ip_blacklisted": true, "ip_blacklist_type": "BOTNET", "ip_provider": "-" }, "maxmind_geolite2": { "asn": "32934", "ip_country_code": "US", "ip_state_name": "Oregon", "ip_city": "Prineville", "ip_geolocation": "44.3041,-120.8364", "ip_time_zone": "America/Los_Angeles" }, "firehol": { "ip_blacklisted_30": false, "ip_blacklisted_1day": false, "is_proxy": false }, "ipsum": { "ip_blacklisted": true, "num_blacklists": 7 }, "spamhaus_drop": { "ip_blacklisted": true }, "x4bnet": { "is_vpn": true, "is_datacenter": true, "is_tor": false, "is_bot_semrush": true } }

Error Codes

The API uses standard HTTP status codes. For all errors, the response body is a JSON object with status: "error" and an error field describing what went wrong.

HTTP status codes

Code	Meaning	Common cause
200	OK	Request was successful. Check the `status` field in the body, as it can still be `error` for application-level issues even with a 200.
400	Bad Request	Invalid or missing parameters. Check that `ip` is a valid IPv4 or IPv6 address and `key` is present.
401	Unauthorized	API key is missing, invalid, or does not match the username in the URL path.
404	Not Found	The URL path is incorrect. Check that your username is included in the path.
500	Server Error	An unexpected error on the Scamalytics server. If persistent, contact [email protected].

Error response body

All errors return a consistent JSON structure:

{ "scamalytics": { "status": "error", "error": "Unauthorized: invalid API key" } }

Credits exhausted

If your monthly credits are fully exhausted, requests will be rejected with an excess limit error. Monitor the credits.remaining field in your responses to manage this proactively.

✓

Contact [email protected] to increase your credit limit or upgrade your plan before you run out.

Handling errors in code

# Python error handling example import requests response = requests.get(url, params=params) if response.status_code != 200: raise Exception(f"HTTP {response.status_code}: {response.text}") data = response.json() if data["scamalytics"]["status"] == "error": raise Exception(data["scamalytics"]["error"])

Error Responses

// 401 Unauthorized { "scamalytics": { "status": "error", "error": "Unauthorized: invalid API key" } } // 400 Bad Request — invalid IP { "scamalytics": { "status": "error", "error": "Bad Request: invalid IP address" } } // Credits exhausted { "scamalytics": { "status": "error", "error": "Excess limit: credits exhausted", "credits": { "used": 12000, "remaining": 0 } } }