IP API

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. Lookups require the BASIC scope; see Authentication for keys and scopes. 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. Costs one lookup credit; failed lookups are not charged.

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",
    "org": "Mercury NZ Limited",
    "abuse_email": "abuse-alerts@as55850.net",
    "domain": "mercury.co.nz"
  },
  "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
      }
    ]
  }
}

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. The cap depends on your plan: 100 on Free, 500 on Starter, and 1,000 on Premium and Enterprise.

Invalid, private, and reserved addresses are skipped without a per-item error, and duplicates collapse to one result, so the response can hold fewer results than the request had entries. The batch is all or nothing: if your credits cannot cover it, nothing is looked up or charged. See Rate Limits for how a batch counts against the request rate.

Request body

  • Name
    ips
    Type
    array<string>
    Description

    Array of up to 1,000 IPv4 or IPv6 addresses, up to your plan's cap.

Response

  • Name
    results
    Type
    array<object>
    Description

    Per-IP enrichment results, in the same shape as the single-IP lookup. One result per distinct usable address, in the order each first appears in the request. Match results to inputs by ip, which is returned in canonical form.

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

Response

{
  "results": [
    {
      "ip": "8.8.8.8",
      "network": {
        "asn": 15169,
        "isp": "Google LLC",
        "type": "DATACENTER",
        "org": "Google LLC",
        "abuse_email": "network-abuse@google.com",
        "abuse_phone": "+1-650-253-0000",
        "domain": "google.com"
      },
      "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": []
      }
    },
    {
      "ip": "1.1.1.1",
      "network": {
        "asn": 13335,
        "isp": "Cloudflare, Inc.",
        "type": "DATACENTER",
        "org": "APNIC and Cloudflare DNS Resolver project",
        "abuse_email": "helpdesk@apnic.net",
        "abuse_phone": "+61-7-3858-3188",
        "domain": "cloudflare.com"
      },
      "intelligence": {
        "risk_score": 0,
        "behavior": [],
        "categories": [],
        "devices": [],
        "providers": []
      }
    }
  ]
}

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:

Operating system
Android
Chrome OS
FreeBSD
iOS
Linux
Mac OS X
Windows

Enriched Types

intelligence.providers[].type and intelligence.categories use these values. The same values appear as type in the proxy and anonymizer feeds.

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

The nine values from SEARCH_ENGINE through PAYMENT_PROCESSOR identify benign automation. Blocking them blocks traffic such as search crawlers and payment webhooks.


Network Types

network.type classifies the network that owns the address. It is not a proxy verdict.

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.

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.