v4

IP API

View as markdown

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 for the full status code reference and retry guidance.

curl -G https://api.synthient.com/api/v4/lookup/ip/8.8.8.8 \
  -H "x-api-key: $SYNTHIENT_API_KEY"
GET/api/v4/lookup/ip/{ip_address}
Open in playground (opens in a new tab)

Look up an IP

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

  • 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 | null
    Description

    Network ownership information for the IP. Absent or null when unknown.

  • 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
    Description

    Name of the organization that owns the IP, when distinct from the ISP. Omitted when unknown.

  • Name
    network.domain
    Type
    string
    Description

    Primary domain associated with the network owner. Omitted when unknown.

  • Name
    network.abuse_email
    Type
    string
    Description

    Email address for reporting abuse. Omitted when unknown.

  • Name
    network.abuse_phone
    Type
    string
    Description

    Phone number for reporting abuse. Omitted when unknown.

  • Name
    location
    Type
    object | null
    Description

    Geographical information for the IP. Absent or null when unknown.

  • 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 | null
    Description

    Risk signals, behavior, and provider attribution for the IP. Absent or null when unknown.

  • 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 display name, such as Android, iOS, or Windows. New names may be added.

  • 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: $SYNTHIENT_API_KEY"

Response

{
  "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
      }
    ]
  }
}
POST/api/v4/lookup/ips
Open in playground (opens in a new tab)

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: $SYNTHIENT_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}
Open in playground (opens in a new tab)

Look up a domain

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

  • Name
    domain
    Type
    string
    Description

    Domain name to look up, such as google.com. Send internationalized names as Punycode.

Query parameters

  • Name
    limit
    Type
    integer
    Description

    Maximum number of recent events. Defaults to 50; must be positive. Values above 1000 are clamped.

Response

  • Name
    domain
    Type
    string
    Description

    The domain that was queried.

  • Name
    status
    Type
    string
    Description

    active when there were events in the last 24 hours; otherwise inactive.

  • Name
    stats.events_24h
    Type
    integer
    Description

    Total honeypot events observed for the domain in the last 24 hours.

  • Name
    stats.total_events_30d
    Type
    integer
    Description

    Total honeypot events observed in the last 30 days.

  • Name
    unique_ips.value_24h
    Type
    integer
    Description

    Distinct source addresses observed in the last 24 hours.

  • Name
    unique_ips.value_30d
    Type
    integer
    Description

    Distinct source addresses observed in the last 30 days.

  • Name
    unique_ips.sparkline_24h
    Type
    array<integer>
    Description

    Hourly distinct-source counts for the last 24 hours.

  • Name
    time_series
    Type
    array<object>
    Description

    Per-day counts, ordered oldest to newest.

  • Name
    time_series[].date
    Type
    integer
    Description

    Unix timestamp in seconds at the start of the UTC day.

  • Name
    time_series[].events
    Type
    integer
    Description

    Number of honeypot events observed that day.

  • Name
    time_series[].unique_ips
    Type
    integer
    Description

    Distinct source addresses observed that day.

  • Name
    top_asn
    Type
    object
    Description

    asn and events of the network that sent the most events. Absent when there are no events.

  • Name
    top_subdomains
    Type
    array<object>
    Description

    Most frequently observed subdomains, most active first.

  • Name
    top_subdomains[].subdomain
    Type
    string
    Description

    Subdomain targeted.

  • Name
    top_subdomains[].count
    Type
    integer
    Description

    Number of events observed for this subdomain.

  • Name
    top_ports
    Type
    array<object>
    Description

    Most frequently observed destination ports.

  • Name
    top_ports[].port
    Type
    integer
    Description

    Destination port.

  • Name
    top_ports[].count
    Type
    integer
    Description

    Number of events observed on this port.

  • Name
    geo_distribution
    Type
    array<object>
    Description

    country_code, events, and unique_ips for each source country. Country codes use ISO 3166-1 alpha-2.

  • Name
    hour_dow_heatmap
    Type
    array<array<integer>>
    Description

    Events over the last 30 days in 7 rows by 24 columns, indexed by UTC day of week and hour. Row 0 is Monday.

  • Name
    activity_stats.peak_hour
    Type
    integer
    Description

    Busiest UTC hour of the day, 0–23.

  • Name
    activity_stats.quiet_hour
    Type
    integer
    Description

    Quietest UTC hour of the day, 0–23.

  • Name
    activity_stats.median_per_hour
    Type
    integer
    Description

    Median events per hour.

  • Name
    activity_stats.p95_per_hour
    Type
    integer
    Description

    95th percentile events per hour.

  • Name
    activity_stats.cadence
    Type
    string
    Description

    Description of the activity pattern, such as Activity follows a weekday business-hours pattern.

  • Name
    recent_events
    Type
    array<object>
    Description

    Most recent honeypot events, capped by limit. Pull the Helios Parquet exports for full history.

  • Name
    recent_events[].timestamp
    Type
    integer
    Description

    Unix timestamp in seconds when the event occurred.

  • Name
    recent_events[].source_ip_masked
    Type
    string
    Description

    Full proxy exit IP address that carried the event, such as 203.0.113.42. The address is unmasked despite the field name.

  • Name
    recent_events[].target_subdomain
    Type
    string
    Description

    Subdomain the request targeted.

  • Name
    recent_events[].port
    Type
    integer
    Description

    Destination port the event hit.

  • Name
    recent_events[].country_code
    Type
    string
    Description

    ISO 3166-1 alpha-2 source country code.

Request

GET/api/v4/lookup/domain/{domain}
curl -G https://api.synthient.com/api/v4/lookup/domain/example.com \
  -H "x-api-key: $SYNTHIENT_API_KEY" \
  --data-urlencode "limit=50"

Response

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

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:

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

TypeDescription
FREE_VPNFree VPN service detected
COMMERCIAL_VPNCommercial VPN service detected
ENTERPRISE_VPNEnterprise VPN service such as SonicWall
MOBILE_PROXYProxy provided by a mobile carrier
BLOCKCHAIN_PROXYDecentralized or blockchain-based proxy
RESIDENTIAL_PROXYProxy running on residential IP addresses
PUBLIC_PROXYOpen proxy accessible to anyone
DATACENTER_PROXYProxy hosted in a datacenter
TOR_NODETor exit node
PRIVATE_RELAYAnonymizing private relay such as iCloud Private Relay
BOTNETHost participating in a known botnet
SEARCH_ENGINEVerified search-engine crawler such as Googlebot
AI_CRAWLERAI training or retrieval crawler such as GPTBot
SOCIAL_MEDIASocial-media platform fetcher such as Twitterbot
UPTIME_MONITORUptime / synthetic monitoring service
LINK_PREVIEWLink-preview unfurler such as Slackbot or Discordbot
SEO_CRAWLERSEO / marketing-intelligence crawler
WEB_ARCHIVERWeb-archiving crawler such as the Internet Archive
WEBHOOK_PROVIDEROutbound webhook delivery service
PAYMENT_PROCESSORPayment-processor or fraud-platform infrastructure
INTERNET_SCANNERInternet-wide scanning infrastructure

Network Types

TypeDescription
MOBILEMobile-network or cellular
SATELLITESatellite Internet
IN_FLIGHT_WIFIIn-flight airplane Wi-Fi
RESIDENTIALResidential broadband ISP
CORPORATECorporate/enterprise network
ACADEMICAcademic/institutional network
DATACENTERDatacenter infrastructure
GOVERNMENTGovernment-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 updated frequently, so treating it as an enum is not advised.

BehaviorDescription
PROGRAMMATIC_TRAFFICAutomated requests from common HTTP clients or libraries such as curl or requests.
ACTIVE_CRAWLERHigh-volume automated requests consistent with crawling or scraping.
TORRENTINGParticipation in peer-to-peer file sharing such as BitTorrent.
TOR_USERConnections observed to Tor entry nodes, indicating Tor usage.
CREDENTIAL_STUFFINGRapid or repeated failed login attempts suggesting credential stuffing.
COMPROMISED_DEVICEActivity associated with devices compromised or infected with malware.
MALICIOUS_TRAFFICTraffic patterns indicative of abuse or malicious activity.
Previous
Next