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.
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).
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 |
Python | CLI | Full | Yes | Yes | No | Roxana Schram | GitHub |
Go | CLI | Full | Yes | Yes | No | Roxana Schram | 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 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.
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).
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.
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.
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.
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.
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.
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 19-November-2024. Versions of the API can be specified from the customer dashboard or with your individual API queries using the &ver=<date> flag.
http://proxycheck.io/v2/[email protected]?key=######-######-######-######
{
"status": "ok",
"[email protected]": {
"disposable": "no"
}
}
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.
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.
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.
["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"]
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.
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.
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"
}
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 FlagsBelow 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
}
}
}
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
}
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.
{
"status": "ok",
"message": "List has been added to successfully."
}
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.
{
"success": "Your origins have been updated.",
"origin_count": 5
}
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.
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.
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.
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.
Provides data from our API for your condition to use such as the country of an IP address.
This is where you select what kind of comparison you want to make between the API's provided value and your provided value[s].
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 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.
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). |
%DEVICEADDRESSCOUNT% | An estimate of the devices behind an IP address. |
%DEVICESUBNETCOUNT% | An estimate of the devices behind an IP addresses subnet. |
%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.