Developers

Once you sign up for a plan, you would be provided with an API Key. Please ensure that you do not share the API key with anyone. In order to use the APIs inside an application, you need to pass the API Key in the header of the request.

ID API’s enterprise-grade Email, IP and Phone Number validation capabilities are compatible with all programming languages via an API.

Our solutions are made for applications that are in need of real-time customer data validation, our real-time validation API is the perfect choice for the same. The various endpoints in our API are available through the very easy to implement GET method for developers.

Currently the API supports only IPv4 addresses. Work is in progress to cover IPv6 ranges as well. Please consult this ID API API documentation page for further information on when IPV6 addresses are going to be supported in our endpoints. The following are our two endpoints for IP address queries

Location Detection

If you don’t pass IP address we will return the result for your public IP. As IP ranges are announced on a daily bases, we are trying to keep our database as up to date and accurate as possible. All IP locations are approximate and should not be treated as exact house address. The fact that IP ranges assigned from RIPE (European IP Registrar) could be announced for use outside Europe makes it really hard to trace. We can’t rely on the registered address of the ASN either as more than likely some IP addresses will be allocated for use outside their city or even country. For this sole reason we are using third party locations list that is kept updated.

In order to get the location of IP address you need to perform GET request to api.id-api.com/ip/location/ followed by the IP address. For example if you want to get the location of

212.21.145.15

you will need to send GET request to

api.id-api.com/ip/location/212.21.145.15

The response would be a JSON object containing the IP address along with another JSON object for its location. For example please take a look at our response object for the above query.

The location object has the following key/value pairs

KeyValue typeDescription
latitudeFloatThe latitude of the Geo location
longitudeFloatThe longitude of the Geo location
accuracyIntApproximate radius of the location in KM
cityStringName of the city. (Could be empty!)
countryStringCountry Name
country_codeStringISO country code

IP Health Check

As we all know locating an IP address doesn’t solve your problems especially if you are in the online business and you’re trying to identify potentially fraudulent transactions. This was the reason why we created an API endpoint to give you full and detailed information about IP address. In order to perform the IP address health check query you need to make GET request to

api.id-api.com/ip/health/

followed by the IP address. For example if you want to check 212.21.145.15 you will need to send GET request to

api.id-api.com/ip/health/212.21.145.15

If you don’t pass IP address we will return the result for your public IP.

By querying this endpoint we will perform the following three health checks:

  1. Toxic IP Detection – we consider an IP address to be toxic if it’s part of hacked network, or is being used for unethical activities like SCAM for example. This check will only return a Boolean (true or false).

  2. Proxy IP Detection – this check will return FALSE if the IP address has not being detected as proxy. Our database includes thousands of records from Tor project and other publicly available proxy services. Only Tor project exit IPs will be marked as anonymous proxy as all other routing IPs can’t be used as exit point therefor should never be treated as proxy. We keep our proxy records updated as frequent as possible as proxy servers appear all the time. In case of positive result you will get JSON object containing the type of the proxy (anonymous, open) and last seen date/time. For reference see the table below:

    KeyValue TypeDescription
    typeStringanonymous or open depending on proxy type
    last_seenDatelast seen date in format yyyy-mm-dd HH:mm:ss in GMT+1
  3. Spam IP Detection – IP address could be part of a hacked network and used for SPAM and other unethical activities. That’s why we have separated this health check from our Toxic result. In order to get better understanding on how spammy an IP address is we will give you the count of the reports people have submitted for it and also its last seen date/time as follows:

KeyValue TypeDescription
times_reportedIntNumber of times reported
last_seenDatelast seen date in format yyyy-mm-dd HH:mm:ss in GMT+1

IP Info API

Same as with all other endpoints, if you don’t specify IP address we will return result for your public IP address. This endpoint maps IP address to ASN and gives you the following information:

  1. IP – IP address for the returned result.

  2. host – hostname for the given IP address or ‘undefined’ if no hostname available.

  3. org – JSON object containing organization details or ‘undefined’ if not available.

  • name – organization name or ‘undefined’ of no name available
  • asn – Autonomous System Number
  • asn_assigned – Date above ASN has been assigned in ‘yyyymmdd’ format
  • country – Registration country
  • registry – one of the five Regional Internet Registries (RIRs): afrinic, apnic, arin, ripe or lacnic
RIRDescription
afrinicAfrica Regional Internet Registry – www.afrinic.net
apnicAsia Pacific Regional Internet Registry – www.apnic.net
arinAmerican Regional Internet Registry – www.arin.net
ripeEuropean Regional Internet Registry – www.ripe.net
lacnicLatin America Regional Internet Registry – www.lacnic.net
  • category – category of the organization responsible for given IP address: mobile, hosting, education, bank, government or undefined
CategoryDescription
mobile3G, 4G providers and mobile operators. If a given mobile operator is also internet service provider, all of its IP addresses will categorized as mobile
hostingVPS, VPN, Dedicated and shared hosting providers etc.
educationschools, colleges, universities etc.
bankAll banks with assigned ASN
governmentGovernments, institutions, local authorities etc.
undefinedEverything that doesn’t fall in any of the above categories

Email address health check is very useful upon accepting signups, orders, restricting access to specific users etc. Send GET request to

api.id-api.com/email/

followed by the email you want to query. For example to perform an email health check on

info@gmail.com

you will need to send GET request the following URL

api.id-api.com/email/info@gmail.com

By querying this endpoint you will get detailed overview on the health of the email your interested in. We will perform the following four important checks:

  1. Free email detection: you will get true or false result for this email check. We consider someone as a free provider if you could signup and get an email address for free. Good example for a free email provider would be Google’s email service Gmail, Yahoo Mail and thousands more. Yes you heard that right, there are thousands of free email providers in our database.

  2. Spam email check: this is another good health check for emails that we perform for you. Same as the spam health check we perform for a specific IP address in case of positive result you will get a JSON object with number of times this email was reported as spam and last seen date/time as follows:

KeyValue TypeDescription
times_reportedIntNumber of times reported
last_seenDatelast seen date in format yyyy-mm-dd HH:mm:ss in GMT+1
  1. Scam email check: this is another unethical activity users could do with their email address. We have it as a separate health check in our results. Identical to spam check in case of positive result you will see the number of times this email was reported as spam as well as last seen date/time in a JSON object or false if the email does not appear in your scam reports.
KeyValue TypeDescription
times_reportedIntNumber of times reported
last_seenDatelast seen date in format yyyy-mm-dd HH:mm:ss in GMT+1
  1. Disposable email detection: result of true or false will be given for this health check. Disposable emails are another good thing to look around for. These are emails people can use and throw away if they don’t want to receive spam, which is a very valid point. However you might want to block people using disposable emails to get your promo code, make orders (kinda positive indication of possible fraud) or when you’re building your email lists, as they’re useless and as the name says ‘disposable’ people use them once and throw them away. We leave this up to you on how to handle this email health check, but at the end of the day we though it’s useful to have this in as well 🙂

Phone number validation endpoint is a powerful tool to help you filter out invalid numbers. It will validate wide range of both national and international numbers worldwide. Use it with landline, mobile, toll free, VoIP etc. For example today a valid mobile number is required within the registration process in some platforms, then SMS is sent and user have to type it in to complete its registration. Allowing invalid numbers can increase the number of bogus users, abandonment of registration and it will costs more to send SMS to invalid numbers that wont be delivered. At very least using ID API Phone validation endpoint will help differentiate between mobile, landline and other types of phone numbers.

IMPORTANT
Use numeric values without spaces. Only allowed special character is the plus sign (+)
Validate international numbers

Normally international phone numbers start with either 00 or + then followed by the country code and the phone number. In almost all cases the leading zero from the local phone number is dropped.

If we use the following phone number +442012345678 the leading + indicates the beginning of international phone number followed by the country code, in this case 44 and then the local number 02012345678. As you can see the leading zero from the local number has been dropped. For example this rule does not apply to Italian phone numbers.

If we are to validate +442012345678 then we need to send GET request to api.id-api.com/phone/ followed by the phone number, and the final URL will be

api.id-api.com/phone/+442012345678

From the JSON response we can see that this is a valid fixed line number, located in London. We can also see that its timezone is Europe/London.

IMPORTANT
All international numbers should start with + instead of 00
 
Validate national/local phone numbers

National or local phone numbers can be also used for validation. In order to validate such numbers a two letter country code in ISO 3166 format is also required. For example to validate the following Irish mobile number 0831234567 we need to send a GET request to api.id-api.com/phone/ followed by the country code IE and then 0831234567.

Final URL would look like api.id-api.com/phone/ie/0831234567

From the JSON response we can see that this is a valid mobile number, located anywhere in Ireland, and its carrier is 3. We can also see that its timezone is Europe/Dublin.

Our API uses the following error codes:

 

Error CodeMeaning
400Bad Request – Your request sucks
401Unauthorized – Your API key is wrong
404Not Found – The specified endpoint could not be found
405Method Not Allowed – You tried to access our endpoint with an invalid method
429Too Many Requests – You’re making too many requests! Slow down!
500Internal Server Error – We had a problem with our server. Try again later.
503Service Unavailable – We’re temporarially offline for maintanance. Please try again later.

Quick Demo