Bulk Whois API User Guide

This version of the API is deprecated. For the latest version, please visit
bulk-whois-api.whoisxmlapi.com/docs

Bulk Whois API provides Whois records for a list of Domans/IPs via a single REST API query. 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 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 Bulk 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 Bulk Whois API Web Service

Send the list of domains via a POST request to:

https://www.whoisxmlapi.com/BulkWhoisLookup/bulkServices/bulkWhois

Provide the JSON-encoded parameters in the request's body, setting the Content-Type header to application/json.

Server response will contain the requestId field which you'll need to retrieve the requested Whois records.

Supported input parameters

Parameters	Values
domains	required, an array of domains for which Whois data is requested
username	required, your account username
password	required, your account password; make sure it is URL-encoded if it contains special characters (&, %, * etc.)
outputFormat	XML \| JSON (defaults to XML)

Sample JSON request

Sample JSON response

Getting Whois Records

Send the request ID via POST to:

https://www.whoisxmlapi.com/BulkWhoisLookup/bulkServices/getRecords

Since processing all the input domains may take some time, you'll have to repeatedly query this resource until the returned recordsLeft field value is 0.

Set the maxRecords input parameter to 1 if you don't need to monitor each record's progress.

Otherwise, each element of the whoisRecords array contains the whoisRecordStatus field:

0 - processed;

1/2 - incomplete/missing data;

3 - processing.

Supported input parameters

Parameters	Values
requestId	required, bulk request identifier
maxRecords	required, maximum amount of Whois records to be returned
username	required, your account username
password	required, your account password; make sure it is URL-encoded if it contains special characters (&, %, * etc.)
startIndex	the first Whois record to be returned by the server (starting from 1)
outputFormat	XML \| JSON (defaults to XML)

Sample JSON request

Result CSV Download

Send a POST request to:

https://www.whoisxmlapi.com/BulkWhoisLookup/bulkServices/download

Supported input parameters

Parameters	Values
requestId	required, bulk request identifier
username	required, your account username
password	required, your account password; make sure it is URL-encoded if it contains special characters (&, %, * etc.)
searchType	noError lets you filter out records with processing errors, no data etc. all \| noError (defaults to all)

Sample JSON request

Authentication

Use your account's username and password to authenticate with the web service. Just pass your credentials in request body (username, password).

XML Schema / Bulk Whois Query Result Documentation

You can download the following for your reference:

sample xml result

Query Account Balance Information

In order to query your account balance, use the following URL:

https://www.whoisxmlapi.com/accountServices.php?servicetype=accountbalance&username=xxxxx&password=xxxxx

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:

https://www.whoisxmlapi.com/accountServices.php?servicetype=accountUpdate&username=xxxxx&password=xxxxx&warn_threshold=30

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)

TLDs Supported

We support thousands of TLDs, both gTLDs and ccTLDS. You can see the entire list here.

Sample code for making a query to Bulk Whois API Web Service

You may view examples of querying Bulk Whois API by clicking on the following links or visiting our GitHub page

C# code: example, full project

Java code: example, full project

Javascript code: example

Node.js code: example

Perl code: example

PHP code: example

PowerShell code: example

Python code: example

Ruby code: example

Usage Limits

The maximum number of requests per second is 5. 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. Maximum number of domains per query is 500,000.

Printable Guide

You can also download the PDF version of this guide.

Retrieving the List of your Requests

Send a POST request to:

https://www.whoisxmlapi.com/BulkWhoisLookup/bulkServices/getUserRequests

Supported input parameters

Parameters	Values
username	required, your account username
password	required, your account password; make sure it is URL-encoded if it contains special characters (&, %, * etc.)
outputFormat	XML \| JSON (defaults to XML)

Sample JSON response

Sample Output

XML

JSON

Frequently Asked Questions

Please click on the link below to view the FAQ

Whois API FAQ

Terms of Service or SLA for using Whois API Web service

Please click on the link below to review the