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.

curl -G https://api.synthient.com/api/v4/lookup/ip/8.8.8.8 \
  -H "x-api-key: $API_KEY"

GET/api/v4/lookup/ip/{ip_address}

Look up an IP

Returns enrichment, intelligence, and provider attribution for a single IPv4 or IPv6 address.

Path parameters

Name
ip_address
Type
string
Description
IPv4 or IPv6 address to look up.

Response

Name
ip
Type
string
Description
The IP address that was queried.
Name
network
Type
object
Description
Network ownership information for the IP.
Name
network.asn
Type
integer
Description
Autonomous System Number. 0 if the IP is not in BGP.
Name
network.isp
Type
string
Description
Internet service provider name.
Name
network.type
Type
string
Description
Network classification, such as RESIDENTIAL or DATACENTER.
Name
network.org
Type
string | null
Description
Name of the organization that owns the IP, when distinct from the ISP.
Name
network.domain
Type
string | null
Description
Primary domain associated with the network owner.
Name
network.abuse_email
Type
string | null
Description
Email address for reporting abuse.
Name
network.abuse_phone
Type
string | null
Description
Phone number for reporting abuse.
Name
location
Type
object
Description
Geographical information for the IP.
Name
location.country
Type
string
Description
ISO 3166-1 alpha-2 country code.
Name
location.state
Type
string
Description
Region or state code.
Name
location.city
Type
string
Description
City name.
Name
location.timezone
Type
string
Description
IANA time zone identifier.
Name
location.latitude
Type
number
Description
Latitude coordinate.
Name
location.longitude
Type
number
Description
Longitude coordinate.
Name
location.geo_hash
Type
string
Description
Geohash for coarse location grouping.
Name
intelligence
Type
object
Description
Risk signals, behavior, and provider attribution for the IP.
Name
intelligence.risk_score
Type
integer
Description
Risk score from 0–100 indicating the likelihood this IP is used for malicious activity.
Name
intelligence.behavior
Type
array<string>
Description
Observed behaviors, such as TOR_USER or ACTIVE_CRAWLER.
Name
intelligence.categories
Type
array<string>
Description
Top-level categories associated with the IP, such as RESIDENTIAL_PROXY.
Name
intelligence.devices
Type
array<object>
Description
Devices observed behind this IP.
Name
intelligence.devices[].os
Type
string
Description
Operating system, such as ANDROID, IOS, or WINDOWS.
Name
intelligence.devices[].version
Type
string
Description
OS version string when available.
Name
intelligence.devices[].last_seen
Type
integer
Description
Unix timestamp in seconds when this device signature was last observed.
Name
intelligence.providers
Type
array<object>
Description
Proxy, VPN, and anonymizer providers attributed to the IP.
Name
intelligence.providers[].provider
Type
string
Description
Name of the provider, such as BRIGHTDATA or NORDVPN.
Name
intelligence.providers[].type
Type
string
Description
Signal type returned by that provider, such as RESIDENTIAL_PROXY or COMMERCIAL_VPN.
Name
intelligence.providers[].last_seen
Type
integer
Description
Unix timestamp in seconds when this signal was last observed.

Request

GET/api/v4/lookup/ip/{ip_address}

curl -G https://api.synthient.com/api/v4/lookup/ip/101.53.218.152 \
  -H "x-api-key: $API_KEY"

Response

{
  "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
      }
    ]
  }
}

POST/api/v4/lookup/ips

Look up multiple 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

Name
ips
Type
array<string>
Description
Array of up to 1,000 IPv4 or IPv6 addresses.

Response

Name
results
Type
array<object>
Description
Per-IP enrichment results, in the same shape as the single-IP lookup.

Request

POST/api/v4/lookup/ips

curl https://api.synthient.com/api/v4/lookup/ips \
  -H "x-api-key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"ips": ["8.8.8.8", "1.1.1.1", "101.53.218.152"]}'

Response

{
  "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
  ]
}

GET/api/v4/lookup/domain/{domain}

Look up a 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

Name
domain
Type
string
Description
Domain name to look up, such as google.com.

Response

Name
type
Type
string
Description
Always "domain".
Name
data.domain
Type
string
Description
The domain that was queried.
Name
data.status
Type
string
Description
Lookup status. One of ok, dormant, or unknown.
Name
data.stats.events_24h
Type
integer
Description
Total honeypot events observed for the domain in the last 24 hours.
Name
data.stats.total_events_30d
Type
integer
Description
Total honeypot events observed in the last 30 days.
Name
data.time_series
Type
array<object>
Description
Per-day event counts, ordered oldest to newest.
Name
data.time_series[].date
Type
string
Description
UTC date formatted as YYYY-MM-DD.
Name
data.time_series[].events
Type
integer
Description
Number of honeypot events observed on this date.
Name
data.top_subdomains
Type
array<object>
Description
Most frequently observed subdomains, most active first.
Name
data.top_subdomains[].subdomain
Type
string
Description
Fully-qualified subdomain.
Name
data.top_subdomains[].count
Type
integer
Description
Number of events observed for this subdomain.
Name
data.top_ports
Type
array<object>
Description
Most frequently observed destination ports.
Name
data.top_ports[].port
Type
integer
Description
Destination port.
Name
data.top_ports[].count
Type
integer
Description
Number of events observed on this port.
Name
data.recent_events
Type
array<object>
Description
Sample of the most recent honeypot events. Capped server-side; pull bulk data from the parquet feed if you need full history.
Name
data.recent_events[].timestamp
Type
integer
Description
Unix timestamp in seconds when the event occurred.
Name
data.recent_events[].source_ip_masked
Type
string
Description
Source IP with the host portion masked, such as 203.0.113.x.
Name
data.recent_events[].target_subdomain
Type
string
Description
Subdomain the request targeted.
Name
data.recent_events[].port
Type
integer
Description
Destination port the event hit.

Request

GET/api/v4/lookup/domain/{domain}

curl -G https://api.synthient.com/api/v4/lookup/domain/example.com \
  -H "x-api-key: $API_KEY"

Response

{
  "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.

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.

The behavior field should be treated as an array of strings. It is frequent to updates 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.

Response Codes

Status Code	Description
200 - Success	The request was completed successfully and the server returned the expected data.
400 - Bad Request	Invalid input parameters such as a malformed IP address.
401 - Unauthorized	No API key was provided or the key is invalid; access to the resource is denied.
402 - Payment Required	You’ve run out of creditsplease add funds or upgrade your plan to continue making requests.
403 - Forbidden	Your API key is valid but lacks the required scope for this resource, such as `BASIC`.
429 - Too Many Requests	You exceeded the per-endpoint rate limit. Honour `Retry-After` and back off before retrying.
500 - Internal Server Error	An unexpected error occurred on our side; reach out to support if the issue persists.