API Documentation background

API Documentation

This API Documentation was reapproved on July 15, 2023

WhoAPI is a RESTful based API. Communication is made through normal HTTP or HTTPS requests.
Requests are made as strings using the HTTP GET method. All outputs are provided as a JSON or XML formatted response.

Authentication

Authentication is needed in order to use the API, and for this a WhoAPI account is required. You’ll need your API key every time you make a request. You have the option to limit API requests by a certain IP addresses in your account settings.

You can find your unique API key inside the “My account” section on the left once you register.

Setting Up Input Request

Get requests should provide their parameters as a request string, part of the URL.

GET http://api.whoapi.com/?domain=whoapi.com&r=NAME_OF_API&apikey=YOUR_API_KEY

We suggest you test the API requests via the API console before you start your implementation.

You have to be logged in to access the API console at: https://my.whoapi.com/api/console

When you make an API request, you have to specify the value of these parameters:

Request param.Description
domainfull domain name, including the tld e.g. whoapi.com
rtype of the request are explained separately on API page
apikeyyour private unique api key
rr (optional)returns your request in json result (useful for testing your scripts)
ip (optional)ip address for APIs like email blacklist it is not mandatory
fullurl (optional)some functions allow full URL e.g. screenshot API

The Content-Type header of the response is set to “application/json; charset=utf-8” Output is compressed with gzip.

Description of Input Parameters

WhoAPI consists of several different APIs. Complete list here. You can access (send requests) to any of our APIs, and upgrade the ones you plan to use. You can send requests to all APIs with the same API key. You can see in the examples below, you can put your API key at the beginning or the end of the URL. Once you register your account and get an API key, you can open the URL in your browser.

  • Example API request for Whois API
    https://api.whoapi.com/?domain=whoapi.com&r=whois&apikey=YOUR_API_KEY
  • Example API request for Domain Availability API
    https://api.whoapi.com/?domain=whoapi.com&r=taken&apikey=YOUR_API_KEY
  • Example API request for Screenshot API
    https://api.whoapi.com/?apikey=YOUR_API_KEY&r=screenshot&fullurl=whoapi.com&process=thumb&resolution=1366×768&asap=&node_geo=&delay=&thumbwidth=&thumbheight=
  • Example API request for Blacklist API
    https://api.whoapi.com/?apikey=YOUR_API_KEY&r=blacklist&domain=whoapi.com&ip=
  • Example API request for SSL API
    https://api.whoapi.com/?apikey=YOUR_API_KEY&r=cert&domain=whoapi.com
  • Example API request for Domain Score API (set)
    https://api.whoapi.com/?apikey=YOUR_API_KEY&r=domainscore&domain=whoapi.com
  • Example API request for Domain Score API (check)
    https://api.whoapi.com/?apikey=YOUR_API_KEY&r=domainscore-check&domain=whoapi.com
  • Example API request for Email Score API (set)
    https://api.whoapi.com/?apikey=YOUR_API_KEY&r=emailscore&domain=whoapi.com
  • Example API request for Email Score API (check)
    https://api.whoapi.com/?apikey=YOUR_API_KEY&r=emailscore-check&domain=whoapi.com

Default Output Variables

You will always get these fields in the response:

Output ParameterDescription
statusstatus code for your request, check all the codes here
status_descdescription of the status in plain English

Let’s make an example request: (check domain availiability for whoapi.com)
http://api.whoapi.com/?domain=whoapi.com&r=taken&apikey=demokey

Output in the JSON format:

{
  "status":"0",
  "status_desc":"Request successful!",
  "taken": "1",
  "ip": "78.47.103.206"
}

The result is stored in the “taken” value, which is, in this case, “1”, same as “Domain not available for registration”.
Each function has a set of its own resulting variables.

API Status Codes

Status CodeDescription
0Request successful!
1Invalid characters in a domain name.
2Use of a double dot in the domain name.
3Domain name starting or ending with dash or dot.
4TLD does not exist.
5Too many characters in domain name (without TLD), maximum length is 64.
6Too many characters in TLD.
7Whois server not yet supported. We are adding new servers on a monthly basis.
8Missing request type in ‘r’ parameter.
9Invalid request type in ‘r’ parameter.
10API key invalid.
11Invalid characters in ‘port’ parameter.
12Invalid API account.
13Account suspended.
14Account canceled.
15IP not whitelisted in Account settings.
16Too many tries, your IP has been blocked for a minute.
17Query limit exceeded.
18Query high usage limit exceeded.
19Missing domain name in ‘domain’ parameter.
20Invalid IP address in ‘ip’ parameter.
21Invalid ‘fullurl’ parameter, must be fully qualified URL.
22Invalid node data, only numeric characters allowed.
23Missing ‘port’ parameter.
24Missing valid TLD in a domain name.
25Unknown output type.
26Timeout getting the result from a node.
27Fatal error detected in result from a node.
28Unknown error detected in result from a node.
29Cannot resolve domain name, IP needed.
30Problem with the WHOIS server, please try again later.
31WHOIS limit reached for used WhoAPI node. Please make a new request.
32Cannot resolve domain availability by using the requested method.
33You can’t make requests on a free account. Please upgrade.
34Your free account has ended. Please upgrade in order to make additional requests.
35You run out of free requests. Please upgrade in order to make additional requests.
36You run out of monthly requests. Query limit exceeded.
37You need to pass domain or IP param. or both to get the score.
38Invalid domain address in ‘domain’ parameter.
39Invalid IP in ‘IP’ parameter.
40You need to pass ’email’ or ‘IP’ parameter or both to get the score.
41Invalid email address in ’email’ parameter.
42Unable to check domain availability.