# 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}) [Open in the API playground](https://api.synthient.com/playground?endpoint=ipLookup) Returns enrichment, intelligence, and provider attribution for a single IPv4 or IPv6 address. `network`, `location`, and `intelligence` can each be absent or `null` when no data is available. Check a section before reading its fields. Missing intelligence does not establish that an address is safe. ### Path parameters - `ip_address` `string` — IPv4 or IPv6 address to look up. ### Response - `ip` `string` — The IP address that was queried. - `network` `object | null` — Network ownership information for the IP. Absent or `null` when unknown. - `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` — Name of the organization that owns the IP, when distinct from the ISP. Omitted when unknown. - `network.domain` `string` — Primary domain associated with the network owner. Omitted when unknown. - `network.abuse_email` `string` — Email address for reporting abuse. Omitted when unknown. - `network.abuse_phone` `string` — Phone number for reporting abuse. Omitted when unknown. - `location` `object | null` — Geographical information for the IP. Absent or `null` when unknown. - `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 | null` — Risk signals, behavior, and provider attribution for the IP. Absent or `null` when unknown. - `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 display name, such as `Android`, `iOS`, or `Windows`. New names may be added. - `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" }, "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="422" { "type": "https://docs.synthient.com/errors/validation-failed", "title": "One or more validation errors occurred.", "status": 422, "errors": { "ip_address": ["Invalid IP address format."] }, "instance": "9a8b7c6d5e4f40312a1b2c3d4e5f6a7b" } ``` ```json title="401" { "type": "https://docs.synthient.com/errors/unauthorized", "title": "Unauthorized", "status": 401, "detail": "Invalid API Key", "instance": "4f1c2a9e7b3d4e5f8a6b9c0d1e2f3a4b" } ``` ```json title="402" { "type": "about:blank", "title": "Payment Required", "status": 402, "detail": "Quota exhausted", "instance": "4f1c2a9e7b3d4e5f8a6b9c0d1e2f3a4b" } ``` ```json title="500" { "title": "Internal Server Error", "status": 500, "instance": "4f1c2a9e7b3d4e5f8a6b9c0d1e2f3a4b" } ``` --- ## Look up multiple IPs (POST /api/v4/lookup/ips) [Open in the API playground](https://api.synthient.com/playground?endpoint=lookupIpBatch) 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}) [Open in the API playground](https://api.synthient.com/playground?endpoint=domainLookup) Returns honeypot intelligence collected for a domain: aggregate stats, a daily time series, unique source counts, top subdomains and ports, geographic and hourly activity, and recent events. Requires `BASIC` and costs one credit. The response fields are top level. A domain with events in the last 24 hours is `active`; otherwise it is `inactive`. A domain that has never been observed returns `200` with `status: "inactive"` and zeroed counts. ### Path parameters - `domain` `string` — Domain name to look up, such as `google.com`. Send internationalized names as Punycode. ### Query parameters - `limit` `integer` — Maximum number of recent events. Defaults to `50`; must be positive. Values above `1000` are clamped. ### Response - `domain` `string` — The domain that was queried. - `status` `string` — `active` when there were events in the last 24 hours; otherwise `inactive`. - `stats.events_24h` `integer` — Total honeypot events observed for the domain in the last 24 hours. - `stats.total_events_30d` `integer` — Total honeypot events observed in the last 30 days. - `unique_ips.value_24h` `integer` — Distinct source addresses observed in the last 24 hours. - `unique_ips.value_30d` `integer` — Distinct source addresses observed in the last 30 days. - `unique_ips.sparkline_24h` `array` — Hourly distinct-source counts for the last 24 hours. - `time_series` `array` — Per-day counts, ordered oldest to newest. - `time_series[].date` `integer` — Unix timestamp in **seconds** at the start of the UTC day. - `time_series[].events` `integer` — Number of honeypot events observed that day. - `time_series[].unique_ips` `integer` — Distinct source addresses observed that day. - `top_asn` `object` — `asn` and `events` of the network that sent the most events. Absent when there are no events. - `top_subdomains` `array` — Most frequently observed subdomains, most active first. - `top_subdomains[].subdomain` `string` — Subdomain targeted. - `top_subdomains[].count` `integer` — Number of events observed for this subdomain. - `top_ports` `array` — Most frequently observed destination ports. - `top_ports[].port` `integer` — Destination port. - `top_ports[].count` `integer` — Number of events observed on this port. - `geo_distribution` `array` — `country_code`, `events`, and `unique_ips` for each source country. Country codes use ISO 3166-1 alpha-2. - `hour_dow_heatmap` `array>` — Events over the last 30 days in 7 rows by 24 columns, indexed by UTC day of week and hour. Row `0` is Monday. - `activity_stats.peak_hour` `integer` — Busiest UTC hour of the day, `0`–`23`. - `activity_stats.quiet_hour` `integer` — Quietest UTC hour of the day, `0`–`23`. - `activity_stats.median_per_hour` `integer` — Median events per hour. - `activity_stats.p95_per_hour` `integer` — 95th percentile events per hour. - `activity_stats.cadence` `string` — Description of the activity pattern, such as `Activity follows a weekday business-hours pattern.` - `recent_events` `array` — Most recent honeypot events, capped by `limit`. Pull the Helios Parquet exports for full history. - `recent_events[].timestamp` `integer` — Unix timestamp in **seconds** when the event occurred. - `recent_events[].source_ip_masked` `string` — Full proxy exit IP address that carried the event, such as `203.0.113.42`. The address is unmasked despite the field name. - `recent_events[].target_subdomain` `string` — Subdomain the request targeted. - `recent_events[].port` `integer` — Destination port the event hit. - `recent_events[].country_code` `string` — ISO 3166-1 alpha-2 source country code. **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" \ --data-urlencode "limit=50" ``` ```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']}, params={'limit': 50}, ) res.raise_for_status() data = res.json() ``` **Response** ```json title="200" { "domain": "example.com", "status": "active", "stats": { "events_24h": 142, "total_events_30d": 8910 }, "unique_ips": { "value_24h": 37, "value_30d": 1204, "sparkline_24h": [2, 0, 5, 1] }, "time_series": [ { "date": 1777593600, "events": 312, "unique_ips": 81 }, { "date": 1777680000, "events": 287, "unique_ips": 74 }, { "date": 1777766400, "events": 142, "unique_ips": 37 } ], "top_asn": { "asn": 174, "events": 1830 }, "top_subdomains": [ { "subdomain": "login.example.com", "count": 4521 }, { "subdomain": "api.example.com", "count": 2890 } ], "top_ports": [ { "port": 443, "count": 6201 }, { "port": 80, "count": 2709 } ], "geo_distribution": [{ "country_code": "US", "events": 3120, "unique_ips": 410 }], "hour_dow_heatmap": [[3, 1, 0, 2]], "activity_stats": { "peak_hour": 14, "quiet_hour": 4, "median_per_hour": 11, "p95_per_hour": 52, "cadence": "Activity follows a weekday business-hours pattern." }, "recent_events": [ { "timestamp": 1777818121, "source_ip_masked": "203.0.113.42", "target_subdomain": "login.example.com", "port": 443, "country_code": "US" }, { "timestamp": 1777818108, "source_ip_masked": "198.51.100.17", "target_subdomain": "api.example.com", "port": 443, "country_code": "US" } ] } ``` > **Note**: Arrays are shortened for readability. `sparkline_24h` contains 24 hourly counts; `hour_dow_heatmap` contains 7 rows of 24 counts. --- ## Devices `intelligence.devices[].os` contains an operating system display name. Treat it as an open string so new values do not break parsing. Known names include: > **Note**: Device data is aggregated from various 3rd party data sources and may not be > available for all IP addresses. | Operating system | | ---------------- | | `Android` | | `Chrome OS` | | `FreeBSD` | | `iOS` | | `Linux` | | `Mac OS X` | | `Windows` | --- ## 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 | | INTERNET\_SCANNER | Internet-wide scanning 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. |