api documentation / proxycheck.io

Introduction Service Limits Code Libraries Querying The API Query Flags Test Console Risk Score Status Codes Geography Data Type Responses

Introduction

Whether you're running a big enterprise or a craft hobby website using our API to protect your property is easy. Be it from spam comments, automated registration or login attempts, site scraping, click fraud or other types of bad behaviour, we can help mitigate it.

If the service you intend to protect is a Wordpress Blog, Minecraft server or Source Engine server you may want to look at some of the available plugins from third party authors that we showcase on our plugins page.

If you intend to code your own implementation we have listed libraries for PHP, Node.js, Java and C#. You can read more about those in the code libraries section below and on our code examples page.

Service Limits

We believe every service should be able to benefit from our proxy protection. That is why we offer 100 queries to all unregistered users and 1,000 queries to registered users per day and for free. Each IP or Email address you send us to be checked counts as one query.

We also made the decision at the very beginning not to differentiate features or service quality by if you pay or by how much you pay. That means every customer free or paid enjoys the same level of reliable service and access to our features.

Plan Level	Daily Allowance	Queries Per Request	All API Features	Burst Tokens	Dashboard	Stats
Unregistered users	100	100	Yes	No	No	No
Registered; Free plan	1,000	1,000	Yes	Yes	Yes	Yes
Registered; Paid plan	10,000+	10,000	Yes	Yes	Yes	Yes

To keep the service quality high for all customers we do have per-second customer request limits. These are expressed as soft and hard limits. The difference being if you go over the soft limit your request to our servers will still be answered (with a warning status code) where as if you go over the hard limit the request will be denied.

The request limits you're subjected to depend on where your requests originate from as we have dedicated infrastructure for certain geographical regions.

Request Origin	Limiter Resolution	Soft Limit	Hard Limit
North & South America	10 seconds	525 Requests Per Second	600 Requests Per Second
Europe & Africa	10 seconds	700 Requests Per Second	800 Requests Per Second
Asia & Oceania	10 seconds	350 Requests Per Second	400 Requests Per Second

These per-second limits are the same for all customers whether you're unregistered or registered with a free or paid plan. The per-second request limits of each region will rise as more servers are deployed.

Also please note we are caching queries at our edge CDN (Content Delivery Network). This means if you check the same IP address more than once within the specified time period the first check will come from our servers but subsequent checks will be delivered from our CDN cache. Below are the different cache times for different account types.

Plan Level	CDN Cache Time	Cache Type
Unregistered users	10 Minutes	Shared
Registered; Free plan	10 Seconds to 10 Minutes	Unique
Registered; Paid plan	10 Seconds to 10 Minutes	Unique

Also please note when providing your API Key the CDN caching becomes customer unique, this means you will not receive another customers cached data at any time. Registered users have our Adaptive Cache feature enabled at all times which alters your CDN cache time between 10 seconds and 10 minutes dependant on how many queries you're sending per second (more queries, longer cache time).

Code Libraries

Below you'll find libraries and functions written by both us and third parties to help you integrate our API into your own custom solution as quickly as possible. These are also featured on our code examples page.

Language	Type	v2 API	IP Checks	Email Checks	Dashboard API	Author	Links
PHP	Function	Partial	Yes	No	No	proxycheck.io	GitHub
PHP	Library	Full	Yes	Yes	Full	proxycheck.io	Packagist • GitHub
Node.js	Library	Full	Yes	No	Partial	neo773	npm • GitHub
Python	Wrapper	Full	Yes	No	No	WardPearce	readthedocs.io • GitHub
C#	Library	Full	Yes	No	No	hollow87	Nuget • GitHub
Java	Library	Full	Yes	No	Full	DefianceCoding	Java Docs • GitHub
Ruby	Gem	v2	Yes	Untested	No	Jonathan De Jong	RubyGems

If you have created a function, class or library for our API that you would like us to feature in our documentation please contact us!

Querying The API

Querying the API can be done in two ways, using a client based request or a server based request. In general we recommend using a server based implementation whenever possible because your users won't be able to defeat a server-side implementation by altering code on their device. Below we've created a table showing the pros and cons of each approach.

Request Type	Resistance to Tampering	Implementation Difficulty	Server Code	Compatibility	IP Checks	Email Checks
Client Based	Low	Low	None	High	Yes	No
Server Based	High	Moderate	Required	Moderate	Yes	Yes

The main reason you would want to use the client based querying method is compatibility. There are many hosting platforms that do not grant access to any kind of server-side code execution which would otherwise rule out the ability for you to implement our API on those platforms. Often though these hosted services allow custom HTML and our client-side implementation can then easily be implemented.

Similarly there are many content management systems (CMS) that are difficult to modify, especially for those who are not software developers and in these cases the client-side implementation may be appropriate. Before choosing to implement the client-side method we recommend checking our plugins page as there may already be a server-side plugin available for your CMS.

Please note when performing a client-side request only the address performing the request to our servers is checked and you cannot perform disposable email checks using the client-based method. These are only availble through server-based requests.

Client Based Requests

The first step in implementing the client-based requesting method is to head over to the customer dashboard and become familiar with the CORS tab. CORS stands for Cross-Origin Resource Sharing and it's simply a method for the visitor of one website to request resources from another website. In this case your website visitors making requests directly to our API through their own web browser using Javascript.

On the CORS tab within the dashboard you'll need to enter your website URL[s] so that we know requests originating from your webpages are for your account, this will enable all the normal features we offer like query flags, whitelist, blacklist, statistics and custom rules to become available on your website. This step isn't necessary when using the server-side implementation as your API Key is automatically sent with those requests and your key is always kept a secret.

On the CORS tab you'll note there is a view javascript button to the top right of the main interface. This will present you with some pre-made example code that already contains your public API Key. This key is safe to be viewed by others and it can only be utilised on the websites you specify. In addition all queries made using a public API key will only check the IP of the originator of the API request.

<!-- JQuery is required, you can use Google's CDN for it or self-host it. -->
<script src="//ajax.googleapis.com/ajax/libs/jquery/3.4.1/jquery.min.js"></script>

<!-- You can modify the URL used below to include our different query flags like how we included &vpn=1. -->
<script>
  $.getJSON("https://proxycheck.io/v2/?key=public-######-######-######&vpn=1", function( json ) {
    if ( json.status == "warning" || json.status == "ok" && json[json.ip].proxy == "yes" ) {
      window.location.href = "https://www.example.com";
    }
 });
</script>

Above we've included one code example from the CORS tab which detects both Proxies & VPN's and then redirects those visitors to another webpage of your choosing. This is useful for sending visitors to a page where they can be told to deactivate their anonymising service to regain access to your website or some other customised message.

This code example will work on both unencrypted and encrypted websites and it will automatically use the same security level as the site you're implementing it on. Including JQuery as we have in the example above is necessary but you can self-host it or use a CDN (like the one by Google we included).

Server Based Requests

Like client-side requests querying the API via your own server is still done over the HyperText Transfer Protocol (HTTP). Our API endpoints support both unencrypted and encrypted requests. Below is an example URL structure for checking a single IP address and the method used for inputting your API Key with that request.

http://proxycheck.io/v2/37.60.48.2?key=111111-222222-333333-444444

When querying the API you can supply extra query flags to customise the way the API handles your request. For example below we've added &risk=1 and &vpn=1 to the request and by doing so we receive a percentage score for how risky the IP address is based on the attacks we've seen it performing and if the IP belongs to a Virtual Private Network or not.

http://proxycheck.io/v2/37.60.48.2?key=111111-222222-333333-444444&risk=1&vpn=1

When querying the API you can supply a single IP address in the URL like shown in the two examples above. But you can also supply multiple IP addresses to be checked by supplying the addresses in a POST request called ips= below is an example of such a query. Also please note the separator used between the addresses in a multi-check request is a comma.

http://proxycheck.io/v2/[email protected]?key=111111-222222-333333-444444

In the above example we've placed an email address instead of an IP address. This will engage our disposable email checking as opposed to our proxy or vpn checking.

While above we have included an email address in the check we highly recommend only sending emails using the POST method like in the example shown below because certain characters in email addresses may cause the URL method to fail.

http://proxycheck.io/v2/?key=111111-222222-333333-444444
POST DATA: ips=8.8.8.8,1.1.1.1,37.60.48.2,[email protected]

You can see example responses from the API for these and many other requests in the test console section.

Query Flags

As noted above when making queries to our API you can supply query flags in the request URL to retrieve extra information or to perform different kinds of checks. Below we have detailed each query flag and what they do.

http://proxycheck.io/v2/37.60.48.2?key=111111-222222-333333-444444&vpn=1&asn=1&risk=1&port=1&seen=1&days=7&tag=msg

Hover your mouse over the query flags above to view more information about them.

Endpoint URL
This is the URL of our API. By default we offer both HTTP and HTTPS endpoints for both our v1 and v2 API's. In this example the v2 API is used which is our latest API version. If you need TLS encrypted security you can connect to this API using HTTPS instead of HTTP.

IP address or Email Address
This is the address you're performing a query on, you can supply an IPv4, IPv6 or Email address here.

You can also supply multiple addresses by seperating them with a comma or you can supply them in POST data with the name ips. We allow 10,000 addresses to be checked per query or 90 seconds processing time, whichever is met first and each individual address sent to us for checking will accure against your daily query allowance.

Multiple Address checking in a single query examples

GET Example:

[email protected]

POST Example:

[email protected]

API Key
This is where you provide your API key, it's not required but without it you'll be limited to 100 free queries per day based on your querying IP address. Supplying a valid API key (they're free!) increases this limit to 1,000 daily free queries, larger daily query amounts can be purchased from the dashboard.

Key Format

?key=111111-222222-333333-444444

VPN Check Flag
When providing the VPN flag we will check if the IP belongs to a virtual private network or datacenter. When detecting a VPN we will still deliver proxy: yes as an answer from our API but we'll also state type: VPN so that you know this IP is from a VPN service.

VPN checks are always performed after our proxy checks so if we've seen a VPN IP that is operating as a kind of proxy (SOCKS, WEB, TOR etc) it will be listed as that instead.

Flag Options

&vpn=3

&vpn=2

&vpn=1

&vpn=0

ASN Flag
When using the ASN flag it enables you to view the ASN (Autonomous System Number) of the network for the IP address you're checking. We also display the ASN provider name, Continent Name, country name, country iso code, region name, region iso code, city and lang/longitude if known.

This flag includes GeoLite2 Continent, Country, Region, City and ASN data created by MaxMind, available from https://www.maxmind.com.

Flag Options

&asn=1

&asn=0

Node Flag
When using the Node flag it enables you to view which of our servers answered your query within our cluster for diagnosing specific node issues such as high latency or malformed responses. The node your query is directed to is based on load conditions and so you should only need to supply this flag for diagnostic reasons.

Flag Options

&node=1

&node=0

Risk Assessment Score Flag
When supplying the risk=1 flag you can activate a risk assessment score detailing how risky we feel the IP address is based on what we've seen the IP doing (performing attacks etc) aswell as combined with what we've seen the IP running (proxy and VPN servers for example). By default this flag is turned off. It should not impact query times by more than 0.2ms.

When the risk flag is set to 1 we will provide you with a risk score for this IP address ranging from 0 to 100. Scores below 33 can be considered low risk while scores between 34 and 66 can be considered high risk. Addresses with scores above 66 are considered very dangerous.

When the risk flag is set to 2 we will provide you with the same risk score noted above but you'll also receive counts of the different types of attacks we've witnessed from this IP within the days you specified by the &days= flag. By default this flag is turned off. It should not impact query times by more than 0.4ms.

Flag Options

&risk=1

&risk=2

&risk=0

Port Number Flag
When using the Port Number Flag if an IP address you've sent us to check is a positive detection (meaning it is operating as a proxy server) we may have the port number the proxy server is operating as stored, when you supply the port flag we will display these port numbers alongside your query results.

Flag Options

&port=1

&port=0

Last Seen Flag
When using the Last Seen flag we will display back to you the most recent time we saw this IP address operating as a Proxy Server. We display this in both a human readable format and as a UNIX time stamp.

Flag Options

&seen=1

&seen=0

Day Restrictor
When using the Day Restrictor flag we will only search for proxies within the time in days from now that you specify. For example if you supplied &days=3 we would only search within our data for Proxies that we saw operating with the past 72 hours (three full days). We support a day range between 0.01 days (24 minutes) and 60 days.

Flag Option Examples

&days=0.01

&days=1

&days=7

Tag Flag
The tag flag allows you to specify a descriptive term which will be stored with any positive detections by the API and made viewable to you within your dashboard stats tab. In the example we have written "forum signup page" so you would know the positive detections within your stats page came from people accessing your forum signup page.

It is recommended that you send your tag in a POST request instead of a GET request. However we will accept tags in the GET request as shown in the example above. Just be warned that some characters within the tag may be stripped if they're sent in the GET request. Our PHP function on GitHub uses the POST method for sending tags in a more reliable way.

Flag Usage Examples

GET Example:

POST Example:

Disabling tagging and positive detection saving entirely

If you do not need to save your positive queries you can supply &tag=0 as a GET flag which will completely disable not only tagging for this specific query but saving of it to your dashboards positive detection log.

Storage limitations Each user is allotted 128MB of positive detection storage per month when supplying blank tags. Which means if you do not supply a tag with a query we will only save it if you have less than 128MB of storage used for your positive detections this month. We will always store queries which contain a message in the tag flag regardless of whether you go over the 128MB of storage allotted.

Flag	Default Behaviour	Usage	Method	Description
vpn	Deactivated	&vpn=0 &vpn=1 &vpn=2 &vpn=3	GET	When the vpn flag is set to 0 no VPN check will be performed, only a proxy check. When the vpn flag is set to 1 we will perform a VPN check on the IP address in addition to a proxy check, any proxy determinations will be shown even if the address is also a VPN due to proxies being considered higher risk. When the vpn flag is set to 2 we will only perform a VPN check, no proxy check will be performed. When the vpn flag is set to 3 we will perform both a proxy and VPN check and both answers will be present in the result returned to you, this differs from &vpn=1 where a proxy result overwrites the VPN result. Please note when using &vpn=3 if an IP is detected as both a Proxy and a VPN it will use 2 queries in your accounts daily allowance due to how we log both positive results in your account seperately.
asn	Deactivated	&asn=0 &asn=1	GET	When the asn flag is supplied we will perform an ASN check on the IP address and present you with the provider name, ASN, Range, Hostname, Continent, Country, Country ISOCode, Region, Region ISOCode, City (if it's in a city), Currency (ISOCode, Name and Symbol) and Lat/Long for the IP address. Provider, Country, Region and City names will be encoded using utf8 for maximum compatibility. Address ranges and hostnames are only shown when using an API version dated January 22nd 2024 or newer.
cur	Activated (if &asn=1)	&cur=0 &cur=1	GET	When the asn flag is enabled you'll receive a currency result by default, you can choose to disable this by supplying &cur=0, please note that &cur=1 will not activate the currency display unless &asn=1 is also supplied.
node	Deactivated	&node=0 &node=1	GET	When the node flag is supplied we will display which node within our cluster answered your API call. This is only really needed for diagnosing problems with our support staff.
time	Deactivated	&time=0 &time=1	GET	When the time flag is supplied we will display how long this query took to be answered by our API excluding network overhead.
risk	Deactivated	&risk=0 &risk=1 &risk=2	GET	When the risk flag is set to 1 we will provide you with a risk score for this IP address ranging from 0 to 100. Scores below 33 can be considered low risk while scores between 34 and 66 can be considered high risk. Addresses with scores above 66 are considered very dangerous. When the risk flag is set to 2 we will still provide you with the above risk score but you'll also receive individual counts for each type of attack we witnessed this IP performing across our customer network and our own honeypots within the days you specify by the &days= flag.
port	Deactivated	&port=0 &port=1	GET	When the port flag is supplied we will display to you the port number we saw this IP address operating a proxy server on.
seen	Deactivated	&seen=0 &seen=1	GET	When the seen flag is supplied we will display to you the most recent time we saw this IP address operating as a proxy server.
short	Deactivated	&short=0 &short=1	GET	When the short flag is set to 1 we will compress the result, placing the IP address you're testing in the same array as the results instead of a sub-array under the IP address heading. This can make the API easier to parse in some languages but will lock you into only checking a single address per individual request.
p	Activated	&p=0 &p=1	GET	When the p flag is set to 1 (which is the default when the flag is absent entirely) the result will be presented using pretty formatting which is more readable for humans. When set to 0, the result will be presented as a single line which is more appropriate for machines.
days	Activated	&days=7	GET	When the days flag is supplied we will restrict our proxy results to between now and the amount of days you specify. For example if you supplied &days=2 we would only check our database for Proxies that we saw within the past 48 hours. By default without this flag supplied we search within the past 7 days.
tag	Deactivated	&tag=text	GET POST	When the tag flag is supplied we will tag your query with the message you supply. You can supply your tag using the POST method and we recommend you do so.
ver	Deactivated	&ver=date	GET	Override the API version selection you have set in the customer dashboard with a different version. You can view the version dates supported by &ver from within the dashboard. Format examples: &ver=17-August-2021 or &ver=02-December-2021

You can see example responses that contain these flags in the test console section below.

Test Console

Below you can perform dummy queries against the API and receive responses for different flags and status codes to help you build your software.

This console is using the latest API stable release which is dated 22-Jan-2024. Versions of the API can be specified from the customer dashboard or with your individual API queries using the &ver=<date> flag.

Query Flags VPN Flag

ASN Flag

Toggle All Flags

Node Flag

Time Flag

Inf Flag

Risk Flag

Port Flag

Seen Flag

Test Addresses

Status Code and Status Message

http://proxycheck.io/v2/[email protected]?key=######-######-######-######

{
    "status": "ok",
    "[email protected]": {
        "disposable": "no"
    }
}

Please note, the test console is not querying the API live and so will not incur queries against your daily allowance. This also means if you test the same addresses on the live API yourself you may receive different results to what the test console presents.

Risk Score

The risk score is something we added to allow the API to be utilised in the most conservative deployments where false positives of any kind are unacceptable. By utilising the risk score you can block or quarantine only the most dangerous IP addresses. Below is a table with suggestions to minimise false positives for conservative deployments and allow the vast majority of VPN's.

Risk Score	proxy: no	proxy: yes	proxy: yes, type: VPN
0 to 66	Allow Access	Deny Access	Allow Access
67 to 73	Deny Access	Deny Access	Allow Access
74 to 100	Deny Access	Deny Access	Deny Access

The risk score is generated live by the API based on a multitude of factors with heavy weight given to recent attacks. However the score does have a baseline dependant on what the usage type of the IP has been determined as. Below is a table illustrating the different type responses and their base scores before attack history is taken into account.

Base Scores	IP Determinations
66%	Proxy with no other data
100%	Proxy with known Protocol and Port Number
66%	Compromised Server with no other data
66%	Hosting Provider suspected as VPN source
73%	VPN server of a known VPN service

In addition to the risk score we also provide attack history in the API result if you supply the flag &risk=2 instead of &risk=1. Below is a table showing the common attack types the API will expose to you but you need not provision your software to support all of these as we will be adding more over time and we include a total count which you can use instead.

Also please note the attack history we show you adheres to your &days= range flag. So for example if you specify &days=30 we'll only show you attacks we saw within the past 30 days.

Type Response	Explanation
Login Attempt	An attempt was made by this IP address to Login to a service.
Registration Attempt	An attempt was made by this IP address to Register for a service.
Comment Spam	An attempt was made by this IP address to post a spam comment.
Denial of Service	This IP was involved in or the originator of a DoS attack.
Forum Spam	An attempt was made by this IP address to spam a forum.
Form Submission	An attempt was made by this IP address to submit a generic form.
Vulnerability Probing	An attempt was made by this IP address to probe a service for vulnerabilities.

If you need an example of how these type responses look, please check out the test console, enable the Risk flag and select Proxy from the Test Addresses dropdown.

Status Codes and Status Messages

To assist you in determining if your query was made successfully or not we have provided a status response at the top of all queries. Below is a table showing the kinds of status response codes, their meanings and example status messages that accompany the codes.

Status Code	Explanation	Status Messages
ok	Query is successful, no message provided.	None
warning	Query is successful but there is a warning message.	Your API Key has been disabled for a violation of our terms of service. You are within 10% of your query limit for the day. You are within 10% of your query limit for the day and a burst token has already been consumed. You have gone over your daily query allowance and a burst token has been consumed. You're sending more than 175 requests per second.
denied	Query is denied and a message is provided.	Your access to the API has been blocked due to using a proxy server to perform your query. Please signup for an account to re-enable access by proxy. 1,000 Free queries exhausted. Please try the API again tomorrow or purchase a higher paid plan. 1,000 Free queries exhausted and a burst token has already been consumed. 100 queries exhausted, if you sign up for a free API key you'll be able to make 1,000 free queries per day. You're sending more than 200 requests per second.
error	Query fails and there is an error message.	No valid IP addresses supplied.

You should provision your software to alert you when some of these status codes are presented from the API. Especially the ones about going over the per-second request limits and exhausting your daily query allowance.

Geography Resources

When building software that adheres to our API conventions you may find yourself in need of an index which matches our API responses, this is especially important when it comes to continents & countries. For this reason we've included the below JSON outputs and the accompanying JSON URL for you to obtain a full list of our continent and country data in an automated way.

Automate your country lists with this JSON resource! https://proxycheck.io/resources/lists/geography/

["Africa","Asia","Europe","North America","Oceania","South America","Antarctica"]

["Andorra","United Arab Emirates","Afghanistan","Antigua and Barbuda","Anguilla","Albania","Armenia","Angola","Antarctica","Argentina","American Samoa","Austria","Australia","Aruba","Aland Islands","Azerbaijan","Bosnia and Herzegovina","Barbados","Bangladesh","Belgium","Burkina Faso","Bulgaria","Bahrain","Burundi","Benin","Saint Barthelemy","Bermuda","Brunei","Bolivia","Bonaire, Saint Eustatius and Saba ","Brazil","Bahamas","Bhutan","Bouvet Island","Botswana","Belarus","Belize","Canada","Cocos Islands","Democratic Republic of the Congo","Central African Republic","Republic of the Congo","Switzerland","Ivory Coast","Cook Islands","Chile","Cameroon","China","Colombia","Costa Rica","Cuba","Cabo Verde","Curacao","Christmas Island","Cyprus","Czechia","Germany","Djibouti","Denmark","Dominica","Dominican Republic","Algeria","Ecuador","Estonia","Egypt","Western Sahara","Eritrea","Spain","Ethiopia","Finland","Fiji","Falkland Islands","Micronesia","Faroe Islands","France","Gabon","United Kingdom","Grenada","Georgia","French Guiana","Guernsey","Ghana","Gibraltar","Greenland","Gambia","Guinea","Guadeloupe","Equatorial Guinea","Greece","South Georgia and the South Sandwich Islands","Guatemala","Guam","Guinea-Bissau","Guyana","Hong Kong","Heard Island and McDonald Islands","Honduras","Croatia","Haiti","Hungary","Indonesia","Ireland","Israel","Isle of Man","India","British Indian Ocean Territory","Iraq","Iran","Iceland","Italy","Jersey","Jamaica","Jordan","Japan","Kenya","Kyrgyzstan","Cambodia","Kiribati","Comoros","Saint Kitts and Nevis","North Korea","South Korea","Kosovo","Kuwait","Cayman Islands","Kazakhstan","Laos","Lebanon","Saint Lucia","Liechtenstein","Sri Lanka","Liberia","Lesotho","Lithuania","Luxembourg","Latvia","Libya","Morocco","Monaco","Moldova","Montenegro","Saint Martin","Madagascar","Marshall Islands","North Macedonia","Mali","Myanmar","Mongolia","Macao","Northern Mariana Islands","Martinique","Mauritania","Montserrat","Malta","Mauritius","Maldives","Malawi","Mexico","Malaysia","Mozambique","Namibia","New Caledonia","Niger","Norfolk Island","Nigeria","Nicaragua","The Netherlands","Norway","Nepal","Nauru","Niue","New Zealand","Oman","Panama","Peru","French Polynesia","Papua New Guinea","Philippines","Pakistan","Poland","Saint Pierre and Miquelon","Pitcairn","Puerto Rico","Palestinian Territory","Portugal","Palau","Paraguay","Qatar","Reunion","Romania","Serbia","Russia","Rwanda","Saudi Arabia","Solomon Islands","Seychelles","Sudan","South Sudan","Sweden","Singapore","Saint Helena","Slovenia","Svalbard and Jan Mayen","Slovakia","Sierra Leone","San Marino","Senegal","Somalia","Suriname","Sao Tome and Principe","El Salvador","Sint Maarten","Syria","Eswatini","Turks and Caicos Islands","Chad","French Southern Territories","Togo","Thailand","Tajikistan","Tokelau","Timor Leste","Turkmenistan","Tunisia","Tonga","Turkey","Trinidad and Tobago","Tuvalu","Taiwan","Tanzania","Ukraine","Uganda","United States Minor Outlying Islands","United States","Uruguay","Uzbekistan","Vatican","Saint Vincent and the Grenadines","Venezuela","British Virgin Islands","U.S. Virgin Islands","Vietnam","Vanuatu","Wallis and Futuna","Samoa","Yemen","Mayotte","South Africa","Zambia","Zimbabwe","Serbia and Montenegro","Netherlands Antilles"]

Type Responses

Sometimes when receiving a result from our API we may provide extra information within a field called type. The responses you receive within the type field are subject to change and we may add additional types in the future so make sure to provision your software to accept all kinds of types and not rely on specific types always being present. Below we have included a list of our current type responses.

Type Response	Explanation
Residential	The IP address is believed to be assigned to a residence.
Wireless	The IP address is believed to be assigned to a mobile device (could be a phone or wireless modem).
Business	The IP address is believed to be assigned to and used by a business.
Hosting	The IP address is believed to be assigned to a company offering hosting services.
TOR	The IP address was found to be operating as a TOR exit node server.
SOCKS	The IP address was found to be operating multiple SOCKS based proxy servers of varying types.
SOCKS4	The IP address was found to be operating a SOCKS4 based proxy server.
SOCKS4A	The IP address was found to be operating a SOCKS4 based proxy server which is similar to SOCKS4 but also resolves hostnames.
SOCKS5	The IP address was found to be operating a SOCKS5 based proxy server.
SOCKS5H	The IP address was found to be operating a SOCKS5H based proxy server which is similar to SOCKS5 but also resolves hostnames.
Shadowsocks	The IP address was found to be operating a Shadowsocks based proxy server.
HTTP	The IP address was found to be operating a HTTP based proxy server.
HTTPS	The IP address was found to be operating a HTTPS based proxy server.
Compromised Server	Performing attacks possibly on our honeypot network. (Email Spam, Automated Signups, Comment and Forum spamming, Login Attempts).
Inference Engine	Our Inference Engine believes the IP address is operating as a proxy server but cannot access the proxy server directly to determine its type.
OpenVPN	The IP address was found to be operating an OpenVPN based "proxy" server. To be clear, you will receive OpenVPN results even when you have the VPN flag turned off because we are making a distinction about open/public OpenVPN servers, they are used like SOCKS5 proxies and are not paid for. Paid/Private OpenVPN servers will still come under the generic "VPN" type response only when using the VPN flag on your query.
VPN	The IP address is believed to be acting as a Virtual Private Network server. This could be due to it being assigned to a datacenter. You will only receive this kind of type if you have specified the VPN flag in your request.
whitelisted by x	The IP address has been whitelisted by an entry within your account. The x will display the exact whitelisted match. For example the IP Range or ASN number that you specified that this IP belongs to.
blacklisted by x	The IP address has been blacklisted by a rule within your account. The x will display the exact blacklisted match. For example the IP Range or ASN number that you specified that this IP belongs to.

This concludes all of the API documentation for the v2 API. Remember to try the test console to see various output examples.

Introduction Detection Exporting Tag Exporting Usage Exporting Custom Lists CORS

Introduction

Within the customer dashboard you will find a few features which also have API's. These include positive detection exporting, account usage exporting and whitelist/blacklist manipulation.

Below we'll show you how to interact with these API's so you can fully integrate them into your own software. All queries made against dashboard API's are free and do not incur against your regular API queries made against our proxy/vpn data.

Please note to use any of the Dashboard API's you will need to sign up for an account (which is free) and enable the Dashboard API setting toggle from within your dashboard on our website.

Positive Detection Exporting

Below is the API call url for exporting recent positive detections. Positive meaning these queries yielded positive proxy and VPN detections. By default we limit this to the most recent 100 entries but you can alter the number to view more or less.

Please note this endpoint has a per-second request limit of 2 with a 10 second resolution meaning 20 requests per 10 seconds are possible. There is no penalty for exceeding this limit, your requests will just not be served until you're back below the threshold.

https://proxycheck.io/dashboard/export/detections/?json=1&key=111111-222222-333333-444444&limit=100&offset=0

■ API Key
This is where you provide your API key, for all dashboard API queries it's required.
■ Limiter Flag
By default we show you 100 of your most recent queries however you can lower this limit to less than 100. Used in combination with the offset flag you can page through your entries, this is good for a custom control panel.
■ Offset Flag
Using this you can specify an offset in the entries we show you allowing you to add pages to your own control panel when retrieving entries from your dashboard. For example &limit=20 and &offset=20 would show you entries 21 through 40 instead of 1 through 20.

"1": {
    "time formatted": "23rd of November 2017 at 7:01 am",
    "time raw": "1511420515",
    "address": "177.154.145.103",
    "detection type": "vpn",
    "answering node": "ATLAS",
    "tag": "Login Attempt"
}

Tag Exporting

When making requests to our API you can supply a tag which is logged within your dashboard under the stats tab whenever a positive detection is made (Proxy, VPN, Rule or Blacklist). These tags help you to determine where the attacks against your service are occuring.

For example if you're protecting a website it's common to put the full URL of the page that your visitor is viewing within the tag when you perform a check of their IP address.

By leveraging tags in this manner you can then see if an IP address was just browsing your website or if they were registering, logging in or something else entirely, we also show each attempt they made allowing you to quickly identify brute force attacks.

So with all this data you can view it within the customer dashboard but you may want to export the data or integrate it with a custom control panel. To help you do this we have provided an API endpoint and it does offer a lot of control.

https://proxycheck.io/dashboard/export/tags/?key=111111-222222-333333-444444&limit=100&offset=0&addresses=1&days=1

■ API Key
This is where you provide your API key, for all dashboard API queries it's required.
■ Limiter Flag
By default we show you 100 of your most frequently used tags however you can lower this limit to less than 100. Used in combination with the offset flag you can page through your entries, this is good for a custom control panel. You can also increase this to view up to 1,000 at a time.
■ Offset Flag
Using this you can specify an offset in the entries we show you allowing you to add pages to your own control panel when retrieving entries from your dashboard. For example &limit=20 and &offset=20 would show you entries 21 through 40 instead of 1 through 20.
■ Addresses Flag
By providing the Addresses flag we will show you all the IP addresses associated with a tag and the amount of times that IP was sent to be checked with that same tag attached.
■ Days Flag
This allows you to specify how many days in the past you want to view data. For example setting it to 7 would show you tags that were used from right now to exactly 7 days ago. This flag is a basic time flag, we also support start and end flags using unix timestamps as shown in the example below.

https://proxycheck.io/dashboard/export/tags/?key=111111-222222-333333-444444&limit=100&offset=0&addresses=1&start=1566648271&end=1566345271

■ Start and End Flags
If you want to look at a specific time frame you can provide start and end times as unix timestamps as shown with the flags above. When providing these you do not provide the days flag. Also please note we're looking in the past, so the start time is nearer to the present time and the end time is further in the past.

Below is an example query result for this dashboard API endpoint

{
    "www.example.com\/wp-comments-post.php": {
        "types": {
            "total": 11,
            "proxy": 4
            "vpn": 4
            "rule": 3
        },
        "addresses": {
            "149.28.76.201": 4,
            "87.107.18.84": 4,
            "62.210.83.206": 3
        }
    },
    "www.example.com\/wp-login.php?action=register": {
        "types": {
            "total": 10,
            "proxy": 7
            "vpn": 3
        },
        "addresses": {
            "196.247.18.72": 2,
            "186.65.118.151": 2,
            "149.28.76.201": 2,
            "185.119.255.159": 2,
            "185.162.235.44": 2
        }
    }
}

Account Usage Exporting

Below is the API call url for viewing your accounts usage for today. It shows how many queries you made today and total, your total allowed query allowance and your plan type. Please note the stats are delayed by a few minutes.

https://proxycheck.io/dashboard/export/usage/?key=111111-222222-333333-444444

■ API Key
This is where you provide your API key, for all dashboard API queries it's required.

{
    "Burst Tokens Available": 1,
    "Burst Token Allowance": 1,
    "Queries Today": "255",
    "Daily Limit": "1000",
    "Queries Total": "98523",
    "Plan Tier": "Free"
}

Below is the API call url for viewing your accounts past 30 days of query volume. It is broken down into Undetected, Proxies, VPN's and Rejected queries.

https://proxycheck.io/dashboard/export/queries/?json=1&key=111111-222222-333333-444444

■ API Key
This is where you provide your API key, for all dashboard API queries it's required.

"TODAY": {
    "proxies": "18",
    "vpns": "3",
    "undetected": "273",
    "refused queries": "0",
    "total queries": 294
}

Custom Lists

Below is the API call url for viewing a list of your custom lists. This is a good way to check what lists are available before performing an action on one of them.

https://proxycheck.io/dashboard/lists/print/?key=111111-222222-333333-444444

Below is the API call url for printing out a specific list, in this case it's a list called whitelist.

https://proxycheck.io/dashboard/lists/print/whitelist?key=111111-222222-333333-444444

■ List Select Flag
This is where you choose which list you're going to perform an action on. You can also leave this absent to get a print out of all the accounts available lists.
■ Action Flag
This is where you specify what action you wish to perform. You can choose from the five listed below.

print

add

remove

set

clear

erase

forcedl

■ API Key
This is where you provide your API key, for all dashboard API queries it's required.
■ Post Data
This isn't a URL flag. If you're performing an add, remove or set action you must specify the data you wish to be added, removed or set. To do this you must provide your data in a POST request with the url you've constructed. The name of the post data must be data

Our code does conform to HTML post standards so you can supply \r\n to send a newline enabling you to format your data to make it more readable within your dashboard.

{
    "status": "ok",
    "message": "List has been added to successfully."
}

CORS Manipulation

Below is the API call url for viewing your current origin domains found under the CORS tab within your dashboard, you can also make additions, removals, set and clear actions to your origins using this API.

https://proxycheck.io/dashboard/cors/list/?key=111111-222222-333333-444444

■ CORS Select Flag
This is where you choose CORS as the item you're going to perform an action on.
■ Action Flag
This is where you specify what action you wish to perform. You can choose from the five listed below.

list

add

remove

set

clear

■ API Key
This is where you provide your API key, for all dashboard API queries it's required.
■ Post Data
This isn't a URL flag. If you're performing an add, remove or set action you must specify the data you wish to be added, removed or set. To do this you must provide your data in a POST request with the url you've constructed. The name of the post data must be data

Our code does conform to HTML post standards so you can supply \r\n or \n to send a newline enabling you add, set or remove multiple origins in a single request.

{
  "success": "Your origins have been updated.",
  "origin_count": 5
}

Introduction Rule Limits Rule Library Rule Conditions Rule Outputs Custom Variables

Introduction

Within the customer dashboard you will find the Custom Rules tab. This is where you can create rules that are acted upon by the API based on the conditions you specify whenever you send a request to our v2 API Endpoint.

Rules can accomplish basic things like increasing an IP addresses risk score or they can do more advanced things like completely changing the response to your queries with new names and values you build yourself.

Please note to use the rule feature you will need to sign up for an account (which is free) and supply your API key with all requests you make to the API.

Rule Limits

Every account can create an unlimited amount of rules but you can only enable a certain number of rules dependent on your plan size. Below is a table showing the different plans and their rule allowances.

Plan Level	1st Tier	2nd Tier	3rd Tier
Free Plan	3 Rules
Starter Plans	9 Rules	12 Rules	15 Rules
Professional Plans	20 Rules	25 Rules	30 Rules
Business Plans	40 Rules	50 Rules	60 Rules
Enterprise Plans	80 Rules	100 Rules	120 Rules

To allow complete flexibility for your rules we do not limit how many conditions or rule outputs you can specify for each rule. This means you can create extremely targeted rules and rules which completely transform the API result that you will receive when performing requests to the API.

Please note only the first matching rule will be applied unless you use the "continue processing" toggle found at the top of each rule, this toggle will allow multiple rules to run one after another. It's important to arrange your rules in priority order top-to-bottom. To aid you with this you can move your already created rules around by dragging them above or below other rules.

Rule Library

We know that learning to use the custom rules feature can be daunting and so to help you we've created a library full of rules which you can add to your account and then modify. This rule library is accessible from the custom rules tab within the customer dashboard.

Above is a screenshot showing the rule library. We are constantly adding new rules to the library as we receive requests from users for specific scenarios that a rule could solve, so please feel free to message us with your needs and we would be happy to create a rule for you and if applicable broadly add it to the library for all customers to enjoy.

Rule Conditions

When creating a rule you must provide at-least one condition which must be satisfied for your rule to be applied. We allow you to create both required conditions (indicated by a pink border) and condition groups containing optional conditions (indicated by a blue border) where only one of the conditions within the group needs to be true.

Conditions are broken up into three sections as noted below.

API Provided Values

Provides data from our API for your condition to use such as the country of an IP address.

Comparison Types

This is where you select what kind of comparison you want to make between the API's provided value and your provided value[s].

Your Values

This is where you provide your custom value[s] for the comparison to be made against the value provided by our API.

Below is an example of a rule with three conditions. The first condition is a required condition as it's surrounded by a pink border. This means this condition must always be met for the rule to run.

The second and third conditions are what we call optional conditions as they are within a condition group. You can tell they're in a group as they're surrounded by a blue border. Only one condition within a condition group needs to be met for that entire group to be considered true.

This means that in this example the pink condition must be true and any one of the conditions within the blue condition group must also be true for this rule to be run.

In the above example we only used a single required condition and a single condition group but you can add as many as you need to within each rule you create allowing you to create highly situational rules.

Rule Outputs

Rule outputs are where you can alter the output from the API when it handles your requests. When creating a rule at-least one output modification is required.

Like with Rule Conditions you can create as many outputs as you want and all of them will be applied when all the conditions are satisfied. This allows you to completely customise how the API will respond to your requests. You could even build your own API interface using custom output names and values.

Below is an example of a rule output modifier that will increase the risk score presented by the API by 30 if the rules conditions are met.

You'll notice that in the above example the Custom Output Name was greyed out. This is because the name is not needed when adding to a risk score. The Output Name box is only needed when creating a custom field within the output modifier or when completely overwriting a pre-existing field.

For example in the below screenshot I am providing a custom field called Elephant and I am filling it with a custom value called Tusk.

Now when performing a query which matches the conditions for this rule there will be a new field in the API result called Elephant with a value of Tusk. Just like in the output example below

{
    "status": "ok",
    "39.137.69.6": {
        "asn": "AS38019",
        "provider": "tianjin Mobile Communication Company Limited",
        "continent": "Asia",
        "country": "China",
        "latitude": 34.7725,
        "longitude": 113.7266,
        "isocode": "CN",
        "proxy": "yes",
        "type": "VPN",
        "last seen human": "22 minutes, 47 seconds ago",
        "last seen unix": "1564236260",
        "Elephant": "Tusk"
    },
    "query time": "0.003s"
}

As noted above, this isn't just for creating new entries in the API result. You can replace entries already present. For example if you wanted to replace the type field from saying VPN you could do that by entering type in the Custom Output Name box and then putting whatever you wanted into the Custom Output Value box.

Custom Variables

When creating a rule output which allows you to provide a custom value you can use some variables we've provided to include our data within your custom value text.

For example if you wanted to create a custom output that contained the risk score for the IP address you're checking you could include that with a variable. You can combine as many variables as you want into each custom value box for each output modifier you add. Below is a table showing the variables and what data they'll provide.

Variable Name	Data Provided
%RULENAME%	The name you have given to this rule in your Dashboard.
%TAG%	The original custom tag you have provided either in the GET or POST data with your request to the API.
%IP%	The IP address being checked.
%ASN%	The autonomous system number for the IP addresses owner.
%HOSTNAME%	The IP addresses hostname if one exists.
%PROVIDER%	The Service Provider name for the IP addresses owner.
%OPERATORNAME%	The name of the current operator for the IP address (mostly applicable to VPN services).
%TYPE%	The type of proxy this IP address is, if applicable (SOCKS5, HTTPS etc)
%RISK%	The IP addresses Risk Score.
%ATTACKHISTORY%	The amount of attacks we have seen this IP address perform on our customers and honeypots over the time frame specified by your &days= query flag.
%CONTINENT%	The continent this IP addresses country belongs to.
%COUNTRY%	The country this IP address is registered to.
%ISOCODE%	The country code for the country this IP address is registered to.
%REGION%	The region this IP address is registered to (state names).
%REGIONCODE%	The region code this IP address is registered to (state name codes).
%TIMEZONE%	The time zone this IP address resides in (iana.org format).
%CURRENCYCODE%	The currency code (e.g. USD) for the country this IP address is assigned to.
%CURRENCYNAME%	The currency name (e.g. Dollar) for the country this IP address is assigned to.
%CURRENCYSYMBOL%	The currency symbol (e.g. $) for the country this IP address is assigned to.
%CITY%	The city this IP address is registered to.
%POSTCODE%	The postcode this IP address is registered to.
%LATITUDE%	The geographic Latitude coordinates for this IP address.
%LONGITUDE%	The geographic Longitude coordinates for this IP address.

When using a variable the data is only made available for the variable to use if you have requested it to be present either through a query flag or by selecting the data from the API Provided Values dropdown for one of your rule conditions.

For example if you were to use the %COUNTRY% variable but did not select the Country API Provided Value when making your rule or you did not activate our ASN data by using the query flag in your request to the API then this variable will not have Country data available and the variable name will not be changed in the API output. This is the same for our Risk data, Attack History data, Provider Name etc

Below is an example where we have created a rule with a custom output name and value. The name is Factoid and the value is The great wall of %COUNTRY% is 13,170 miles long.

{
    "status": "ok",
    "39.137.69.6": {
        "asn": "AS38019",
        "provider": "tianjin Mobile Communication Company Limited",
        "continent": "Asia",
        "country": "China",
        "latitude": 34.7725,
        "longitude": 113.7266,
        "isocode": "CN",
        "proxy": "yes",
        "type": "VPN",
        "last seen human": "22 minutes, 47 seconds ago",
        "last seen unix": "1564236260",
        "Factoid": "The great wall of China is 13,170 miles long"
    },
    "query time": "0.003s"
}

As you can see in the above example it replaced the %COUNTRY% variable with the actual name of the country for the IP we're checking which is China. If we had not requested ASN data for this check (via a query flag or the API Provided Values dropdown) the result would instead look like the example below.

{
    "status": "ok",
    "39.137.69.6": {
        "proxy": "yes",
        "type": "VPN",
        "last seen human": "22 minutes, 47 seconds ago",
        "last seen unix": "1564236260",
        "Factoid": "The great wall of %COUNTRY% is 13,170 miles long"
    },
    "query time": "0.003s"
}

One great usage for the variables is to add data to an already present entry in the API as you can overwrite a value with something new while still including the previous entries value. For example if you wanted to add extra information to a tag you could write your customised message and then include the previous tag afterwards by using the %TAG% variable.

This concludes the documentation for the custom rules features. If you need assistance in creating a rule please feel free to contact us. We can create rules for you and save them to your dashboard for you to view and edit.

Back