# IP API Residential proxies and other forms of anonymization services provide a challenge for fraud prevention and risk teams. The Synthient IP API provides detailed intelligence on IP addresses, including risk scoring, device insights, and network information to help identify and mitigate potential threats. ## Base URL & Authentication All HTTP endpoints are versioned under `/api/v4` on `https://api.synthient.com`. Every request must include your API key in the `x-api-key` header. See [Errors](https://docs.synthient.com/errors) for the full status code reference and retry guidance. ```bash title="cURL" curl -G https://api.synthient.com/api/v4/lookup/ip/8.8.8.8 \ -H "x-api-key: $SYNTHIENT_API_KEY" ``` ```bash title="CLI" synthient lookup "8.8.8.8" ``` --- ## Look up an IP (GET /api/v4/lookup/ip/\{ip\_address}) Returns enrichment, intelligence, and provider attribution for a single IPv4 or IPv6 address. ### Path parameters - `ip_address` `string` — IPv4 or IPv6 address to look up. ### Response - `ip` `string` — The IP address that was queried. - `network` `object` — Network ownership information for the IP. - `network.asn` `integer` — Autonomous System Number. `0` if the IP is not in BGP. - `network.isp` `string` — Internet service provider name. - `network.type` `string` — Network classification, such as `RESIDENTIAL` or `DATACENTER`. - `network.org` `string | null` — Name of the organization that owns the IP, when distinct from the ISP. - `network.domain` `string | null` — Primary domain associated with the network owner. - `network.abuse_email` `string | null` — Email address for reporting abuse. - `network.abuse_phone` `string | null` — Phone number for reporting abuse. - `location` `object` — Geographical information for the IP. - `location.country` `string` — ISO 3166-1 alpha-2 country code. - `location.state` `string` — Region or state code. - `location.city` `string` — City name. - `location.timezone` `string` — IANA time zone identifier. - `location.latitude` `number` — Latitude coordinate. - `location.longitude` `number` — Longitude coordinate. - `location.geo_hash` `string` — Geohash for coarse location grouping. - `intelligence` `object` — Risk signals, behavior, and provider attribution for the IP. - `intelligence.risk_score` `integer` — Risk score from 0–100 indicating the likelihood this IP is used for malicious activity. - `intelligence.behavior` `array` — Observed behaviors, such as `TOR_USER` or `ACTIVE_CRAWLER`. - `intelligence.categories` `array` — Top-level categories associated with the IP, such as `RESIDENTIAL_PROXY`. - `intelligence.devices` `array` — Devices observed behind this IP. - `intelligence.devices[].os` `string` — Operating system, such as `ANDROID`, `IOS`, or `WINDOWS`. - `intelligence.devices[].version` `string` — OS version string when available. - `intelligence.devices[].last_seen` `integer` — Unix timestamp in **seconds** when this device signature was last observed. - `intelligence.providers` `array` — Proxy, VPN, and anonymizer providers attributed to the IP. - `intelligence.providers[].provider` `string` — Name of the provider, such as `BRIGHTDATA` or `NORDVPN`. - `intelligence.providers[].type` `string` — Signal type returned by that provider, such as `RESIDENTIAL_PROXY` or `COMMERCIAL_VPN`. - `intelligence.providers[].last_seen` `integer` — Unix timestamp in **seconds** when this signal was last observed. **Request** `GET /api/v4/lookup/ip/{ip_address}` ```bash title="cURL" curl -G https://api.synthient.com/api/v4/lookup/ip/101.53.218.152 \ -H "x-api-key: $SYNTHIENT_API_KEY" ``` ```bash title="CLI" synthient lookup "101.53.218.152" ``` ```python title="Python" import os, requests res = requests.get( 'https://api.synthient.com/api/v4/lookup/ip/101.53.218.152', headers={'x-api-key': os.environ['SYNTHIENT_API_KEY']}, ) data = res.json() ``` **Response** ```json title="200" { "ip": "101.53.218.152", "network": { "asn": 55850, "isp": "TrustPower Ltd", "type": "RESIDENTIAL", "org": null, "domain": null, "abuse_email": null, "abuse_phone": null }, "location": { "country": "NZ", "state": "CAN", "city": "New Brighton", "timezone": "Pacific/Auckland", "latitude": -43.532, "longitude": 172.341, "geo_hash": "rb6" }, "intelligence": { "risk_score": 96, "behavior": ["PROGRAMMATIC_TRAFFIC"], "categories": ["RESIDENTIAL_PROXY"], "devices": [], "providers": [ { "provider": "LUNAPROXY", "type": "RESIDENTIAL_PROXY", "last_seen": 1776729600 }, { "provider": "BRIGHTDATA", "type": "RESIDENTIAL_PROXY", "last_seen": 1777248000 } ] } } ``` ```json title="400" { "title": "Validation error", "errors": { "ip_address": ["must be a valid IP address"] } } ``` ```json title="401" { "detail": "Invalid API Key" } ``` ```json title="402" { "detail": "Quota exhausted" } ``` ```json title="500" { "detail": "Internal Server Error" } ``` --- ## Look up multiple IPs (POST /api/v4/lookup/ips) Enrich up to **1,000 IP addresses** in a single request. Batch requests are billed at a 10% discount (`ceil(n × 0.9)` credits), and duplicates and invalid IPs are excluded before charging. For example, 100 IPs cost `ceil(100 × 0.9) = 90` credits versus 100 credits as individual lookups. ### Request body - `ips` `array` — Array of up to 1,000 IPv4 or IPv6 addresses. ### Response - `results` `array` — Per-IP enrichment results, in the same shape as the single-IP lookup. **Request** `POST /api/v4/lookup/ips` ```bash title="cURL" curl https://api.synthient.com/api/v4/lookup/ips \ -H "x-api-key: $SYNTHIENT_API_KEY" \ -H "Content-Type: application/json" \ -d '{"ips": ["8.8.8.8", "1.1.1.1", "101.53.218.152"]}' ``` ```bash title="CLI" synthient lookup "8.8.8.8" "1.1.1.1" "101.53.218.152" --format json ``` ```python title="Python" import os, requests res = requests.post( 'https://api.synthient.com/api/v4/lookup/ips', headers={'x-api-key': os.environ['SYNTHIENT_API_KEY']}, json={'ips': ['8.8.8.8', '1.1.1.1', '101.53.218.152']}, ) data = res.json() ``` **Response** ```json title="200" { "results": [ { "ip": "8.8.8.8", "network": { "asn": 15169, "isp": "Google LLC", "type": "DATACENTER" }, "location": { "country": "US", "state": "CA", "city": "Mountain View", "timezone": "America/Los_Angeles", "latitude": 37.386, "longitude": -122.084, "geo_hash": "9q9" }, "intelligence": { "risk_score": 0, "behavior": [], "categories": [], "devices": [], "providers": [] } } // ... rest of the per-IP results ] } ``` --- ## Look up a domain (GET /api/v4/lookup/domain/\{domain}) Returns honeypot intelligence collected for a domain: aggregate stats, a time series, top subdomains and ports, and the most recent events seen by Synthient sensors. ### Path parameters - `domain` `string` — Domain name to look up, such as `google.com`. ### Response - `type` `string` — Always `"domain"`. - `data.domain` `string` — The domain that was queried. - `data.status` `string` — Lookup status. One of `ok`, `dormant`, or `unknown`. - `data.stats.events_24h` `integer` — Total honeypot events observed for the domain in the last 24 hours. - `data.stats.total_events_30d` `integer` — Total honeypot events observed in the last 30 days. - `data.time_series` `array` — Per-day event counts, ordered oldest to newest. - `data.time_series[].date` `string` — UTC date formatted as `YYYY-MM-DD`. - `data.time_series[].events` `integer` — Number of honeypot events observed on this date. - `data.top_subdomains` `array` — Most frequently observed subdomains, most active first. - `data.top_subdomains[].subdomain` `string` — Fully-qualified subdomain. - `data.top_subdomains[].count` `integer` — Number of events observed for this subdomain. - `data.top_ports` `array` — Most frequently observed destination ports. - `data.top_ports[].port` `integer` — Destination port. - `data.top_ports[].count` `integer` — Number of events observed on this port. - `data.recent_events` `array` — Sample of the most recent honeypot events. Capped server-side; pull bulk data from the parquet feed if you need full history. - `data.recent_events[].timestamp` `integer` — Unix timestamp in **seconds** when the event occurred. - `data.recent_events[].source_ip_masked` `string` — Source IP with the host portion masked, such as `203.0.113.x`. - `data.recent_events[].target_subdomain` `string` — Subdomain the request targeted. - `data.recent_events[].port` `integer` — Destination port the event hit. **Request** `GET /api/v4/lookup/domain/{domain}` ```bash title="cURL" curl -G https://api.synthient.com/api/v4/lookup/domain/example.com \ -H "x-api-key: $SYNTHIENT_API_KEY" ``` ```bash title="CLI" synthient lookup domain "example.com" ``` ```python title="Python" import os, requests res = requests.get( 'https://api.synthient.com/api/v4/lookup/domain/example.com', headers={'x-api-key': os.environ['SYNTHIENT_API_KEY']}, ) data = res.json() ``` **Response** ```json title="200" { "type": "domain", "data": { "domain": "example.com", "status": "ok", "stats": { "events_24h": 142, "total_events_30d": 8910 }, "time_series": [ { "date": "2026-04-30", "events": 312 }, { "date": "2026-05-01", "events": 287 }, { "date": "2026-05-02", "events": 142 } // ... rest of the 30-day series ], "top_subdomains": [ { "subdomain": "login.example.com", "count": 4521 }, { "subdomain": "api.example.com", "count": 2890 } ], "top_ports": [ { "port": 443, "count": 6201 }, { "port": 80, "count": 2709 } ], "recent_events": [ { "timestamp": 1777818121, "source_ip_masked": "203.0.113.x", "target_subdomain": "login.example.com", "port": 443 }, { "timestamp": 1777818108, "source_ip_masked": "198.51.100.x", "target_subdomain": "api.example.com", "port": 443 } ] } } ``` --- ## Devices The device field indicates the type of device associated with the IP address. It is used to identify patterns of abuse or suspicious behavior. > **Note**: Device data is aggregated from various 3rd party data sources and may not be > available for all IP addresses. | Type | | ------------- | | ANDROID | | IOS | | WINDOWS | | MACOS | | LINUX | | CHROME\_OS | | SMART\_TV | | GAME\_CONSOLE | | OTHER | --- ## Enriched Types | Type | Description | | ------------------ | ------------------------------------------------------ | | FREE\_VPN | Free VPN service detected | | COMMERCIAL\_VPN | Commercial VPN service detected | | ENTERPRISE\_VPN | Enterprise VPN service such as SonicWall | | MOBILE\_PROXY | Proxy provided by a mobile carrier | | BLOCKCHAIN\_PROXY | Decentralized or blockchain-based proxy | | RESIDENTIAL\_PROXY | Proxy running on residential IP addresses | | PUBLIC\_PROXY | Open proxy accessible to anyone | | DATACENTER\_PROXY | Proxy hosted in a datacenter | | TOR\_NODE | Tor exit node | | PRIVATE\_RELAY | Anonymizing private relay such as iCloud Private Relay | | BOTNET | Host participating in a known botnet | | SEARCH\_ENGINE | Verified search-engine crawler such as Googlebot | | AI\_CRAWLER | AI training or retrieval crawler such as GPTBot | | SOCIAL\_MEDIA | Social-media platform fetcher such as Twitterbot | | UPTIME\_MONITOR | Uptime / synthetic monitoring service | | LINK\_PREVIEW | Link-preview unfurler such as Slackbot or Discordbot | | SEO\_CRAWLER | SEO / marketing-intelligence crawler | | WEB\_ARCHIVER | Web-archiving crawler such as the Internet Archive | | WEBHOOK\_PROVIDER | Outbound webhook delivery service | | PAYMENT\_PROCESSOR | Payment-processor or fraud-platform infrastructure | --- ## Network Types | Type | Description | | ---------------- | ------------------------------ | | MOBILE | Mobile-network or cellular | | SATELLITE | Satellite Internet | | IN\_FLIGHT\_WIFI | In-flight airplane Wi-Fi | | RESIDENTIAL | Residential broadband ISP | | CORPORATE | Corporate/enterprise network | | ACADEMIC | Academic/institutional network | | DATACENTER | Datacenter infrastructure | | GOVERNMENT | Government-owned network | ### Behavior The behavior field is an array of strings that indicates the type of activity associated with the IP address within a 90 day window. It is used to identify patterns of abuse or suspicious behavior. > **Note**: The behavior field should be treated as an array of strings. It is updated > frequently, so treating it as an enum is not advised. | Behavior | Description | | --------------------- | ---------------------------------------------------------------------------------- | | PROGRAMMATIC\_TRAFFIC | Automated requests from common HTTP clients or libraries such as curl or requests. | | ACTIVE\_CRAWLER | High-volume automated requests consistent with crawling or scraping. | | TORRENTING | Participation in peer-to-peer file sharing such as BitTorrent. | | TOR\_USER | Connections observed to Tor entry nodes, indicating Tor usage. | | CREDENTIAL\_STUFFING | Rapid or repeated failed login attempts suggesting credential stuffing. | | COMPROMISED\_DEVICE | Activity associated with devices compromised or infected with malware. | | MALICIOUS\_TRAFFIC | Traffic patterns indicative of abuse or malicious activity. |