> ## Documentation Index
> Fetch the complete documentation index at: https://docs.finowl.co/llms.txt
> Use this file to discover all available pages before exploring further.
# IP Intelligence
> Know whether an IP address can be trusted before you act: VPN, Tor, hosting and relay flags, network and ASN, geolocation and a risk score in one request.
**Moving from `ip/lookup`?** IP Intelligence is the IP lookup endpoint under a new name, with the same request and response. Change the path from `/v1/ip/lookup` to `/v1/ip/intelligence`. The old path now returns `410` with the code `endpoint_renamed`.
### Good to know
* **Only need the location?** [IP Geolocation](/api-reference/ip/geolocation) returns the same location fields without the network and privacy signals.
* **Country is reliable, city is approximate.** Country-level results are accurate for most addresses. The city is often the network operator's location, which can be far from the user, especially on mobile networks.
* **The data is refreshed daily.** Addresses that recently changed hands may show their previous owner for a day or two.
* **`hosting` means a server, not a person.** The address belongs to a cloud or hosting provider. Real users rarely browse from these, so it often points to a bot, VPN or proxy. Some company VPNs and privacy relays also run on cloud providers.
* **`tor` means the user is anonymous.** The address is a current Tor exit node. The location is the exit node's, not the user's.
* **`reserved: true` usually means the wrong address.** Private and loopback addresses such as `10.0.0.5` are not on the internet. Behind a load balancer, send the client address from `X-Forwarded-For` instead.
* **`data_unavailable` is free.** If the IP data is still loading, the request returns `503` and is not charged. Try again after a few seconds.
* **Credit DB-IP if you show locations.** The geolocation data is licensed under CC BY 4.0. If you display the city, region or country to users, include "IP geolocation by [DB-IP](https://db-ip.com)" near it.
* **`risk` is a starting point.** Tor exits, VPNs, hosting networks and iCloud Private Relay raise the score; verified search engine crawlers lower it. Combine it with your own signals before blocking anyone.
* **`network.type` is a heuristic.** It comes from the hosting flag and the network operator's name, and is often `unknown`.
* **`network.allocated` can be a re-registration date** rather than the first allocation, because the registries' files record the latest change.
IP geolocation by [DB-IP](https://db-ip.com) (CC BY 4.0). Time zones from [GeoNames](https://www.geonames.org) (CC BY 4.0). VPN ranges from [X4BNet lists\_vpn](https://github.com/X4BNet/lists_vpn) (MIT).
Combine IP Intelligence with email and phone checks when someone registers.
## OpenAPI
````yaml api-reference/openapi.yaml POST /v1/ip/intelligence
openapi: 3.1.0
info:
title: Finowl API
version: '1.0'
description: >
Check emails and passwords against known data breaches, predict gender from
names
and emails, validate email addresses and phone numbers, look up companies by
domain,
and geolocate and assess IP addresses. Every endpoint is a JSON
`POST` authenticated with a bearer API key.
servers:
- url: https://api.finowl.co
description: Production
security:
- bearerAuth: []
tags:
- name: Breaches
description: Check whether an email or password appears in known data breaches.
- name: Gender
description: Predict gender from a name or email, one at a time or in batches.
- name: Email validation
description: >-
Check whether an email address can receive mail, and catch typos,
disposable and role addresses.
- name: Company
description: Look up public company details from a domain or work email.
- name: IP
description: Geolocate an IP address, and flag VPN, Tor, hosting and relay traffic.
- name: Phone
description: Validate, format and classify a phone number.
paths:
/v1/ip/intelligence:
post:
tags:
- IP
summary: Get IP intelligence
description: >
Tells you whether an IPv4 or IPv6 address can be trusted before you act
on it. Returns the
geolocation, the network (ASN, operator, range and registry), flags for
VPNs, Tor exit nodes,
cloud and hosting providers, iCloud Private Relay and verified search
engine crawlers, and a
risk score that combines them.
The lookup runs in memory on Finowl's own infrastructure against data
refreshed daily:
IP geolocation by [DB-IP](https://db-ip.com) (CC BY 4.0), the
registries' delegation files,
the IP ranges that cloud providers and search engines publish, the
public Tor exit list and
VPN ranges from [X4BNet lists_vpn](https://github.com/X4BNet/lists_vpn)
(MIT). Only the
reverse DNS name is looked up per request.
Private, loopback and other reserved addresses return `reserved: true`
with empty
location and network fields.
Costs **1 credit**. A `503` where the lookup could not complete is not
charged.
operationId: ipIntelligence
requestBody:
required: true
content:
application/json:
schema:
type: object
additionalProperties: false
required:
- ip
properties:
ip:
type: string
maxLength: 64
description: >-
An IPv4 or IPv6 address, such as `8.8.8.8` or
`2001:4860:4860::8888`. Ranges (CIDR), hostnames, ports and
IPv6 zones such as `fe80::1%eth0` return `invalid_input`.
example: 8.8.8.8
examples:
hosting:
summary: Cloud address
value:
ip: 8.8.8.8
residential:
summary: Residential address
value:
ip: 81.2.69.160
ipv6:
summary: IPv6
value:
ip: 2a02:c7c:a0e3:7600::1
reserved:
summary: Private address
value:
ip: 192.168.1.20
responses:
'200':
description: The lookup completed. Unknown fields are empty or `null`.
content:
application/json:
schema:
$ref: '#/components/schemas/IpIntelligenceResult'
examples:
hosting:
summary: Cloud address
value:
ip: 8.8.8.8
version: 4
country_code: US
country: United States
region: California
city: Mountain View
asn: 15169
as_name: Google LLC
hosting: true
hosting_provider: google_cloud
tor: false
reserved: false
location:
latitude: 37.422
longitude: -122.085
timezone: America/Los_Angeles
local_time: '2026-10-15T10:27:05-07:00'
utc_offset: '-07:00'
country_info:
code: US
name: United States
flag: πΊπΈ
continent: North America
currency: USD
language: en
in_eu: false
calling_code: 1
network:
asn: 15169
as_name: Google LLC
cidr: 8.8.8.0/24
rir: ARIN
allocated: '2023-12-28'
registered_country: US
type: hosting
reverse_dns: dns.google
privacy:
hosting: true
hosting_provider: google_cloud
tor: false
vpn: false
icloud_private_relay: false
crawler: null
risk:
score: 40
level: medium
factors:
- hosting
residential:
summary: Residential address
value:
ip: 81.2.69.160
version: 4
country_code: GB
country: United Kingdom
region: England
city: London
asn: 20712
as_name: Andrews & Arnold Ltd
hosting: false
hosting_provider: null
tor: false
reserved: false
location:
latitude: 51.5143
longitude: -0.0912
timezone: Europe/London
local_time: '2026-10-15T18:27:05+01:00'
utc_offset: '+01:00'
country_info:
code: GB
name: United Kingdom
flag: π¬π§
continent: Europe
currency: GBP
language: en
in_eu: false
calling_code: 44
network:
asn: 20712
as_name: Andrews & Arnold Ltd
cidr: 81.2.64.0/18
rir: RIPE
allocated: '2002-04-03'
registered_country: GB
type: unknown
reverse_dns: null
privacy:
hosting: false
hosting_provider: null
tor: false
vpn: false
icloud_private_relay: false
crawler: null
risk:
score: 0
level: low
factors: []
tor:
summary: Tor exit node
value:
ip: 185.220.101.4
version: 4
country_code: DE
country: Germany
region: Hamburg
city: Hamburg (Hamburg-Nord)
asn: 60729
as_name: Stiftung Erneuerbare Freiheit
hosting: false
hosting_provider: null
tor: true
reserved: false
location:
latitude: 53.5735
longitude: 10.0548
timezone: Europe/Berlin
local_time: '2026-10-15T19:27:05+02:00'
utc_offset: '+02:00'
country_info:
code: DE
name: Germany
flag: π©πͺ
continent: Europe
currency: EUR
language: de
in_eu: true
calling_code: 49
network:
asn: 60729
as_name: Stiftung Erneuerbare Freiheit
cidr: 185.220.101.0/24
rir: RIPE
allocated: '2017-09-12'
registered_country: DE
type: unknown
reverse_dns: berlin01.tor-exit.artikel10.org
privacy:
hosting: false
hosting_provider: null
tor: true
vpn: true
icloud_private_relay: false
crawler: null
risk:
score: 100
level: high
factors:
- tor_exit
- vpn
reserved:
summary: Private address
value:
ip: 192.168.1.20
version: 4
country_code: ''
country: ''
region: null
city: null
asn: null
as_name: null
hosting: false
hosting_provider: null
tor: false
reserved: true
location:
latitude: null
longitude: null
timezone: null
local_time: null
utc_offset: null
country_info: null
network:
asn: null
as_name: null
cidr: null
rir: null
allocated: null
registered_country: null
type: null
reverse_dns: null
privacy:
hosting: false
hosting_provider: null
tor: false
vpn: false
icloud_private_relay: false
crawler: null
risk:
score: null
level: null
factors: []
'400':
$ref: '#/components/responses/InvalidInput'
'401':
$ref: '#/components/responses/Unauthorized'
'429':
$ref: '#/components/responses/TooManyRequests'
'503':
description: >-
`data_unavailable`: the IP data is still loading, for example just
after a restart. Not charged. Retry after a short delay.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
error:
code: data_unavailable
'504':
$ref: '#/components/responses/Unconfirmed'
components:
schemas:
IpIntelligenceResult:
type: object
required:
- ip
- version
- country_code
- country
- region
- city
- asn
- as_name
- hosting
- hosting_provider
- tor
- reserved
- location
- country_info
- network
- privacy
- risk
properties:
ip:
type: string
description: >-
The address in canonical form, for example IPv6 compressed and
lowercased.
version:
type: integer
enum:
- 4
- 6
description: The IP version.
country_code:
type: string
description: >-
ISO 3166-1 alpha-2 code of the country the address is registered to
or used in. Empty when unknown or `reserved`.
country:
type: string
description: The country name for `country_code`. Empty when unknown.
region:
type:
- string
- 'null'
description: >-
The state, province or region, such as `California`. `null` when
unknown.
city:
type:
- string
- 'null'
description: >-
The nearest city. Often the location of the network operator rather
than the user, especially for mobile networks. `null` when unknown.
asn:
type:
- integer
- 'null'
description: >-
The autonomous system number of the network that announces the
address. `null` when unknown.
as_name:
type:
- string
- 'null'
description: >-
The name of that network's operator, such as `Google LLC` or an
internet provider. `null` when unknown.
hosting:
type: boolean
description: >-
`true` when the address is in a range published by a cloud provider
or belongs to a known hosting network. Real users rarely browse from
these addresses, so it often indicates a server, VPN or proxy.
hosting_provider:
type:
- string
- 'null'
enum:
- aws
- google_cloud
- azure
- cloudflare
- oracle_cloud
- digitalocean
- linode
- vultr
- hetzner
- ovh
- other_hosting
- null
description: >-
The hosting provider when `hosting` is `true`, `other_hosting` for
any other hosting network, `null` otherwise. Treat values you don't
recognize like `other_hosting`.
tor:
type: boolean
description: >-
`true` when the address is a current Tor exit node, so the real user
is anonymous.
reserved:
type: boolean
description: >-
`true` for private, loopback, link-local, carrier-grade NAT,
documentation and other reserved addresses. These are not on the
public internet, so all location and network fields are empty,
`null` or `false`. Usually it means you sent your proxy's address
instead of the client's.
location:
type: object
description: >-
Where `city` is, and the local time there. Every field is `null` for
`reserved` addresses.
required:
- latitude
- longitude
- timezone
- local_time
- utc_offset
properties:
latitude:
type:
- number
- 'null'
description: >-
Latitude of `city` in decimal degrees, rounded to 4 decimals. It
is the city's centre, not the device: treat it as accurate to
tens of kilometres at best, and to the operator's location for
mobile networks. `null` when the city is unknown.
longitude:
type:
- number
- 'null'
description: >-
Longitude of `city` in decimal degrees, rounded to 4 decimals.
Same accuracy as `latitude`. `null` when the city is unknown.
timezone:
type:
- string
- 'null'
description: >-
IANA time zone, such as `America/Los_Angeles`: the zone of the
nearest city of more than 15,000 people in the same country.
When the city is unknown, the country's zone if the country has
only one. `null` otherwise.
local_time:
type:
- string
- 'null'
format: date-time
description: >-
The current time in `timezone` as RFC 3339 with its offset, such
as `2026-10-15T10:23:28-07:00`, at the moment of the lookup.
`null` when `timezone` is `null`.
utc_offset:
type:
- string
- 'null'
description: >-
The current offset of `timezone` from UTC as `Β±HH:MM`, such as
`-07:00`. It includes daylight saving time. `null` when
`timezone` is `null`.
country_info:
type:
- object
- 'null'
description: Details of `country_code`. `null` when `country_code` is empty.
required:
- code
- name
- flag
- continent
- currency
- language
- in_eu
- calling_code
properties:
code:
type: string
description: The ISO 3166-1 alpha-2 code
the same as `country_code`.: null
name:
type: string
description: The country name in English.
flag:
type: string
description: The emoji flag, such as `πΊπΈ`.
continent:
type: string
enum:
- Africa
- Antarctica
- Asia
- Europe
- North America
- Oceania
- South America
- ''
description: >-
The continent. North America includes Central America and the
Caribbean. Empty when unknown.
currency:
type: string
description: >-
ISO 4217 code of the main currency, such as `USD`. Empty when
unknown.
language:
type: string
description: >-
ISO 639 code of the main language, such as `en`. Empty when
unknown.
in_eu:
type: boolean
description: '`true` when the country is a member state of the European Union.'
calling_code:
type:
- integer
- 'null'
description: >-
The international calling code, such as `1` or `44`. `null` when
unknown.
network:
type: object
description: >-
The network that announces the address and how it was registered.
Every field is `null` for `reserved` addresses.
required:
- asn
- as_name
- cidr
- rir
- allocated
- registered_country
- type
- reverse_dns
properties:
asn:
type:
- integer
- 'null'
description: The same as the top-level `asn`.
as_name:
type:
- string
- 'null'
description: The same as the top-level `as_name`.
cidr:
type:
- string
- 'null'
description: >-
The largest CIDR block that holds the address and lies inside
one contiguous range of the same AS, such as `8.8.8.0/24`. It
describes how the AS's address space is laid out, not
necessarily a single announced BGP route. `null` when `asn` is
`null`.
rir:
type:
- string
- 'null'
enum:
- ARIN
- RIPE
- APNIC
- LACNIC
- AFRINIC
- null
description: >-
The regional internet registry the range was delegated by.
`null` when the range is not in the registries' published
statistics.
allocated:
type:
- string
- 'null'
format: date
description: >-
The date in the registry's statistics, as `YYYY-MM-DD`: usually
when the range was first allocated or assigned, but registries
update it when a range is transferred or re-registered. `null`
when unknown.
registered_country:
type:
- string
- 'null'
description: >-
ISO 3166-1 alpha-2 code of the country the range holder
registered with the RIR, such as `US`. It can differ from
`country_code`, which is where the address is used. Registries
occasionally use `EU` or `AP` for regional holders. `null` when
unknown.
type:
type:
- string
- 'null'
enum:
- hosting
- isp
- mobile
- business
- education
- government
- unknown
- null
description: >
A heuristic guess at the kind of network. `hosting` when
`hosting` is `true`; otherwise from a short list of known
networks and keywords in `as_name`, such as `university`
(`education`), `ministry` (`government`), `wireless`
(`mobile`), `telecom` or `cable` (`isp`) and `bank`
(`business`). `unknown` when nothing matches, which is common.
`null` only for `reserved` addresses. Treat values you don't
recognize like `unknown`.
reverse_dns:
type:
- string
- 'null'
description: >-
The address's reverse DNS (PTR) name, lowercased and without the
trailing dot, such as `dns.google`. It is set by the network
operator and not verified. `null` when there is none or it did
not answer within 800 ms.
privacy:
type: object
description: >-
Signals that the traffic is anonymized or automated. Every flag is
`false` and every name `null` for `reserved` addresses.
required:
- hosting
- hosting_provider
- tor
- vpn
- icloud_private_relay
- crawler
properties:
hosting:
type: boolean
description: The same as the top-level `hosting`.
hosting_provider:
type:
- string
- 'null'
enum:
- aws
- google_cloud
- azure
- cloudflare
- oracle_cloud
- digitalocean
- linode
- vultr
- hetzner
- ovh
- other_hosting
- null
description: The same as the top-level `hosting_provider`.
tor:
type: boolean
description: The same as the top-level `tor`.
vpn:
type: boolean
description: >-
`true` when the address is in a public list of known commercial
VPN networks. The list is incomplete, so `false` does not rule
out a VPN. Always `false` when `icloud_private_relay` is `true`.
icloud_private_relay:
type: boolean
description: >-
`true` when the address is an iCloud Private Relay egress
address published by Apple. The user is a real Apple customer
whose IP address and precise location are hidden.
crawler:
type:
- string
- 'null'
enum:
- googlebot
- bingbot
- applebot
- duckduckbot
- null
description: >-
The search engine crawler whose officially published ranges hold
the address, so a request claiming to be that crawler is
genuine. `null` otherwise. Treat values you don't recognize as
another verified crawler.
risk:
type: object
description: >
A simple score of how likely the address hides the real user, for
ranking and review rather than as a probability.
Weights are added for each factor present and the total is clamped
to 0β100: `tor_exit` 80, `vpn` 50, `hosting` 40,
`icloud_private_relay` 30, `unknown_network` 10, and
`verified_crawler` subtracts 40.
required:
- score
- level
- factors
properties:
score:
type:
- integer
- 'null'
minimum: 0
maximum: 100
description: >-
The risk score; higher is riskier. `null` for `reserved`
addresses.
level:
type:
- string
- 'null'
enum:
- low
- medium
- high
- null
description: >-
`low` below 30, `medium` from 30 to 69, `high` from 70. `null`
for `reserved` addresses.
factors:
type: array
items:
type: string
enum:
- tor_exit
- vpn
- hosting
- icloud_private_relay
- unknown_network
- verified_crawler
description: >
The factors that contributed, in the order above. Empty when
none applied or the address is `reserved`.
- `tor_exit`: `tor` is `true`.
- `vpn`: `privacy.vpn` is `true`.
- `hosting`: `hosting` is `true`.
- `icloud_private_relay`: `privacy.icloud_private_relay` is
`true`.
- `unknown_network`: no AS is known for the address.
- `verified_crawler`: `privacy.crawler` is set; lowers the
score.
Treat codes you don't recognize as informational.
Error:
type: object
required:
- error
properties:
error:
type: object
required:
- code
properties:
code:
type: string
description: >-
A stable, machine-readable error code. See the Errors page for
the full list.
example: invalid_input
responses:
InvalidInput:
description: The request body is not valid. Fix the request before trying again.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
error:
code: invalid_input
Unauthorized:
description: The API key is missing, malformed or revoked.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
error:
code: unauthorized
TooManyRequests:
description: >
`rate_limited` (too many requests this minute), `quota_exceeded` (not
enough credits) or
`provider_rate_limited` (Finowl intelligence is busy). Check the
`Retry-After` header.
headers:
Retry-After:
description: Seconds to wait before trying again.
schema:
type: integer
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
error:
code: rate_limited
Unconfirmed:
description: >-
The lookup did not finish in time. It may or may not have run, and the
request was charged.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
error:
code: provider_response_unconfirmed
securitySchemes:
bearerAuth:
type: http
scheme: bearer
description: >-
Your Finowl API key, for example `finowl_3f9a...`. Create keys in the
dashboard under **API Keys**.
````
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.