Unified & Consistent
Whois API & Whois
Parser System
Whois API User Guide
Our Hosted Whois Web Service provides registration details, also known as Whois Records,
of domain names or IP addresses.
WhoisXmlApi.com provides RESTful APIs. It is designed for
server-to-server communication between your system and the WhoisXmlApi.com network using
standard HTTP or HTTPS protocols. Query responses are delivered in either XML or JSON
format based on your requests which are made via GET/POST methods.
To get started you need a developer's account with
WhoisXmlApi.com. Authentication is required each time in order to use the API.
The first 500 Whois API calls are complimentary when you register for a free developer account.
API status
You can check the API's current performance and availability status on the API Status Page.Making a Call to Whois API Web Service
Use the following URL:
Supported input parameters
| Parameters | Values |
|---|---|
| domainName | required, the domain for which whois data is requested |
| username | required unless ApiKey authentication is used, your account username |
| password |
required unless ApiKey authentication is used, your account
password; make sure it is URL-encoded if it contains special characters (&, %, * etc.) |
| requestObject | required unless password authentication is used, encoded user identifier for ApiKey authentication |
| digest | required unless password authentication is used, ApiKey access token |
| outputFormat | XML | JSON (defaults to XML) |
| da |
0 | 1 | 2 (defaults to 0) 1 results in a quick check on domain availability, 2 is slower but more accurate |
| ip |
0 | 1 (defaults to 0) 1 results in returning ips for the domain name |
| checkProxyData |
0 | 1 (defaults to 0) 1 results in fetching proxy/whois guard data, if it exists, in the WhoisRecord → privateWhoisProxy schema element |
| thinWhois |
0 | 1 (defaults to 0) 1 results in returning whois data from registry only, without fetching data from registrar; returned registry data corresponds to the WhoisRecord → registryData schema element |
| callback |
a javascript function used when outputFormat is JSON; this is an implementation known as JSONP which invokes the callback on the returned response |
| _parse |
0 | 1 (defaults to 0) 1 provides parsing for input whois raw texts described below |
| registryRawText |
a string representing the registry whois raw text to be parsed; works only when the _parse parameter is equal to 1 |
| registrarRawText |
a string representing the registrar whois raw text to be parsed; works only when the _parse parameter is equal to 1 |
Authentication
Password authentication
This method uses your account's username and password to authenticate with the web service.
Just pass your credentials as query string parameters (username, password).
API key authentication
Generate access tokens providing your API and secret keys to make Whois API calls without sending your
username and password.
These tokens will need to be included as part of the request URL (requestObject, digest).
Please, note that all tokens expire after 5 minutes and will have to be regenerated.
Access the API Key Management
section of your account to create your keys (make sure the key you're using is marked as active).
Sample Output
XML
JSON
Terms of Service or SLA for using Whois API Web service
Please click on the link below to review the
Usage Limits
The maximum number of requests per second is 40 (20 concurrent at a time). In case that the limit is breached (either from single IP address or from multiple IPs), you will be penalized with the 30 second ban. That ban includes IPs that were used at the time of the offence, and includes all following IPs (based on username from additional requests) used during the ban time.
Query Account Balance Information
In order to query your account balance, use the following URL:
Supported input parameters
| Parameters | Values |
|---|---|
| servicetype |
required, type of service; in this case, "accountBalance" |
| username | required, your account username |
| password | required, your account password; make sure it is URL-encoded if it contains special characters (&, %, * etc.) |
| output_format | XML | JSON (defaults to XML) |
You will receive a response with your account balance.
Account Balance Low or Zero Notification
When your account balance falls below certain level (default is 100, but customizable as per your need)
you will receive an email alert. Another email will be sent when your account balance reaches 0.
To customize the warning level, use the URL:
Supported input parameters
| Parameters | Values |
|---|---|
| servicetype |
required, type of service; in this case, "accountUpdate" |
| username | required, your account username |
| password | required, your account password; make sure it is URL-encoded if it contains special characters (&, %, * etc.) |
| warn_threshold |
a positive number (defaults to 10) when your account balance reaches this value a warning email will be sent |
| warn_threshold_enabled |
0 | 1 (defaults to 1) indicates whether the low balance warning notification should be sent at all |
| warn_empty_enabled |
0 | 1 (defaults to 1) indicates whether the zero balance email notification should be sent to you |
| output_format | XML | JSON (defaults to XML) |
Usage of HTTP & HTTPS
You can use both http and https to make API queries. With HTTPS the connection will be more secure
but slightly slower.
TLDs Supported
We support thousands of TLDs, both gTLDs and ccTLDS. You can see the entire list
here.
XML Schema / Whois Query Result Documentation
You can download the following for your reference:
Sample code for making a query to Whois API Web Service
You may view examples of querying Whois API by clicking on the following links or visiting our
GitHub page
User password authentication
API key authentication
Output Schema
Frequently Asked Questions
Please click on the link below to view the FAQ
Printable guide
You can also download the
PDF version
of this guide.
