API Documentation

Whois History

> > > Whois History

Overview

We recently enhanced the DomainTools Whois History API endpoint in order to help tailor searches, retrieve large historical recordsets, and allow you to consume the relevant historical records for your investigations. These updates were released in February 2021.

The Whois History API endpoint features the following capabilities:

  • Returns the most recent historical records first, sorting them in ascending or descending (default) order based on the record date field.
  • Allows investigators to retrieve and consume relevant historical records that are part of investigations via pagination and offsetting of results.

The API endpoint response will only provide up to 100 historical Whois records at a time. Please use the new offset parameter to retrieve the next set of historical records using the pagination functionality. No other updates are required to the URI formation.

Please review the Product Service Levels and Whois History Parameters section below for optimal implementation.

API Endpoint

https://api.domaintools.com/v1/DOMAIN/whois/history/
URI: /v1/{{QUERY}}/whois/history/

Note: The URI pattern in this API is different from most other DomainTools APIs, which follow a different URI formation.

Note: For more information about API endpoint authentication parameters and methods, please see the API Authentication page.

Prerequisites

  • You must provide the correct API credentials to use this API.
  • API access is not disabled or expired.
  • API provisioning service limitations have not been exceeded. See the Account Information API.

Product Service Levels

A product service level authorizes your API account to access an API product and defines the price and usage limits for that access. If your account is not authorized to access a certain product, contact DomainTools member services for help.

Your API account is provisioned for a maximum number of historical records you can retrieve monthly. Account usage is tracked based on the number of historical records retrieved across all domain queries in a given month, and not per API request. Use the pagination and limit capabilities to effectively manage your monthly consumption.

Whois History Parameters

Parameters

Description
domain Required.

 

Input the domain for which the Whois data is desired.

Usage:

  • Only provide the domain as SLD.TLD format (e.g. domaintools.com).
  • If you provide a hostname/subdomain (e.g. www.domaintools.com or mail.domaintools.com), only the SLD.TLD (domaintools.com) will be used.
  • Data type: String.
sort An optional parameter. Sort the records returned in either ascending or descending order.

 

Usage:

  • date_asc – Date ascending. API will return the oldest historical record first, sorting them from oldest-to-newest
  • date_desc – Date descending. API will return the latest historical record first, sorting them from newest-to-oldest
  • The default option will sort records in descending order (date_desc).
  • Data type: String.

For example, add the date_asc parameter and set the limit to 5 to retrieve the 5 oldest historical records associated with this domain.
limit An optional parameter. Specify the maximum number of records to retrieve in an API query.

 

Usage:

  • Any value between 1 to 100.
    • For example, to retrieve a maximum of 2 historical records associated with a domain, add limit=2
    • If the limit is 0, no historical records are provided.
    • If the limit is more than 100, only the first 100 records are provided. To retrieve subsequent records, pagination must be used. The API does not provide validation of the limit parameter value.
  • The default value is 100.
  • Data type: Integer.
offset An optional parameter. Allows users to paginate results if there are more than 100 results. Up to 100 results are provided per API query.

 

Pagination begins with the offset=m parameter, where m is the number of records to skip.

For example, when accessing page 3 of historical records for a given domain, this would necessitate the parameter offset=200. If you use the limit parameter

Usage:

  • The default value is 0 (no records are skipped).
  • Use this parameter to skip results. For example, if the API record_count is 150, set the offset value to 100 to skip the first 100 results and see the rest of the 50 results.
  • To retrieve a maximum of 20 subsequent historical records using pagination, add both the offset and limit parameters – offset=100&limit=20
  • Data type: Integer.
mode An optional parameter that changes the mode of the API result and supports the following:

 

  • check_existence
  • count
  • list

Usage:

  • check_existence – checks if the domain exists in the DomainTools database. Returns a result of true or false.
  • count – Returns a record_count of how many historical records are associated with the queried domain.
  • list – This is the default for this parameter and returns the historical records associated with the domain.
  • Data type: String.

Note: Querying the API with mode as check_existence or count does not return any historical data and hence does not impact your monthly account limits. Only when querying with mode as list, will the API return the historical records, and will it count toward your account limit. Please refer to Product Service Levels for additional information.
format An optional parameter to obtain the API response in XML, JSON, or HTML formats.

 

Usage:

  • html – Set the API response format in HTML. This format may be useful for debugging and previewing.
  • xml – Set the API response format in XML. This is structured data in XML format.
  • json – Set the API response format in JSON. This is structured data in Javascript Object Notation.
  • Default value is json.
  • Data type: String.

Sample Query – Retrieve the Oldest (in Ascending Order) Historical Records of a Domain

No charge sample query:

https://api.domaintools.com/v1/domaintools.com/whois/history/?sort=date_asc

Sample Response

{
  "response": {
	"record_count": 744,
	"history": [
	  {
		"date": "2001-10-26",
		"is_private": 0,
		"whois": {
		  "registrant": "VRW2",
		  "registration": {
			"created": "1998-08-02",
			"expires": "2002-08-02",
			"registrar": "NETWORK SOLUTIONS, INC.",
			"statuses": [
			  "ACTIVE"
			]
		  },
		  "name_servers": [
			"DNS1.INTERLAND.NET"
		  ],
		  "server": "whois.networksolutions.com",
		  "record": "Registrant:nVRW2n    7770 Regents Road #113/194n    San Diego, CA 92122n    USnn    Domain Name: DOMAINTOOLS.COMnn    Administrative Contact:n        Whiting, Van R    [email protected]        IPE Advisory Servicesn        7770 Regents Road Suite 113/194n        San Diego, CA 92122n        18585347622 (FAX) 18585340756n    Technical Contact:n        James, Caio    [email protected]        Yeat Choice Technologiesn        PO Box 782n        Orangevale, CA 95662n        (619) 678-8745 (FAX) (916)729-9343n    n    Record last updated on 26-Oct-2001n    Record expires on 02-Aug-2002n    Record created on 02-Aug-1998n    Database last updated on 11-Jan-2002 15:00:24 ESTnn    Domain servers in listed order:nn    DNS1.INTERLAND.NET        64.224.20.132n    DNS2.INTERLAND.NET        64.224.20.133n    DNS3.INTERLAND.NET        64.224.20.134n"
		}
	  },
	  ...
	  {
		"date": "2019-01-18",
		"is_private": 0,
		"whois": {
		  "registrant": "REDACTED FOR PRIVACY",
		  "registration": {
			"created": "1998-08-02",
			"expires": "2027-08-01",
			"updated": "2017-09-21",
			"registrar": "eNom, Inc.",
			"statuses": [
			  "clientTransferProhibited"
			]
		  },
		  "name_servers": [
			"NS1.P09.DYNECT.NET",
			"NS2.P09.DYNECT.NET",
			"NS3.P09.DYNECT.NET",
			"NS4.P09.DYNECT.NET"
		  ],
		  "server": "whois.enom.com",
		  "record": "Domain Name: domaintools.comnRegistry Domain ID: 1697312_DOMAIN_COM-VRSNnRegistrar WHOIS Server: WHOIS.ENOM.COMnRegistrar URL: WWW.ENOM.COMnUpdated Date: 2017-09-21T13:20:39.00ZnCreation Date: 1998-08-02T04:00:00.00ZnRegistrar Registration Expiration Date: 2027-08-01T04:00:00.00ZnRegistrar: ENOM, INC.nRegistrar IANA ID: 48nDomain Status: clienttransferprohibited https://www.icann.org/epp#clienttransferprohibitednDomain Status: registrar-lock* https://www.icann.org/epp#registrar-lock*nRegistrant Name: REDACTED FOR PRIVACYnRegistrant Organization: REDACTED FOR PRIVACYnRegistrant Street: REDACTED FOR PRIVACYnRegistrant Street: nRegistrant City: REDACTED FOR PRIVACYnRegistrant State/Province: REDACTED FOR PRIVACYnRegistrant Postal Code: REDACTED FOR PRIVACYnRegistrant Country: REDACTED FOR PRIVACYnRegistrant Phone: REDACTED FOR PRIVACYnRegistrant Phone Ext: nRegistrant Fax: REDACTED FOR PRIVACYnRegistrant Email: REDACTED FOR PRIVACYnAdmin Name: REDACTED FOR PRIVACYnAdmin Organization: REDACTED FOR PRIVACYnAdmin Street: REDACTED FOR PRIVACYnAdmin Street: nAdmin City: REDACTED FOR PRIVACYnAdmin State/Province: REDACTED FOR PRIVACYnAdmin Postal Code: REDACTED FOR PRIVACYnAdmin Country: REDACTED FOR PRIVACYnAdmin Phone: REDACTED FOR PRIVACYnAdmin Phone Ext: nAdmin Fax: REDACTED FOR PRIVACYnAdmin Email: REDACTED FOR PRIVACYnTech Name: REDACTED FOR PRIVACYnTech Organization: REDACTED FOR PRIVACYnTech Street: REDACTED FOR PRIVACYnTech Street: nTech City: REDACTED FOR PRIVACYnTech State/Province: REDACTED FOR PRIVACYnTech Postal Code: REDACTED FOR PRIVACYnTech Country: REDACTED FOR PRIVACYnTech Phone: REDACTED FOR PRIVACYnTech Phone Ext: nTech Fax: REDACTED FOR PRIVACYnTech Email: REDACTED FOR PRIVACYnName Server: NS1.P09.DYNECT.NETnName Server: NS2.P09.DYNECT.NETnName Server: NS3.P09.DYNECT.NETnName Server: NS4.P09.DYNECT.NETnDNSSEC: UNSIGNEDnRegistrar Abuse Contact Email: [email protected] Abuse Contact Phone: +1.4259744689nURL of the ICANN WHOIS Data Problem Reporting System: HTTP://WDPRS.INTERNIC.NET/n"
		}
	  }
	]
  }
}

Sample Query – Retrieve Subsequent Historical Records Associated with a Domain

No charge sample query:

https://api.domaintools.com/v1/domaintools.com/whois/history/?offset=100

Sample Response Snippet

{
  "response": {
	"record_count": 744,
	"history": [
	  {
		"date": "2020-09-25",
		"is_private": 0,
		"whois": {
		...
	  {
		"date": "2020-09-24",
		"is_private": 0,
		"whois": {
		  "registrant": "REDACTED FOR PRIVACY",
		  "registration": {
	  ...
		}
	  }
	]
  }
}

Sample Query- Retrieve A Maximum of 20 Subsequent Historical Records Using Pagination

No charge sample query:

https://api.domaintools.com/v1/domaintools.com/whois/history/?offset=100&limit=20

Sample Response Snippet

{
  "response": {
	"record_count": 744,
	"history": [
	  {
		"date": "2020-09-25",
		"is_private": 0,
		"whois": {
		...
	  )
	  {
		"date": "2020-09-06",
		"is_private": 0,
		"whois": {
		  "registrant": "REDACTED FOR PRIVACY",
		  "registration": {
		  ...
		}
	  }
	]
  }
}

Other Sample Responses

[HTML]
[JSON]
[XML]

Reading the Response

response

The container for the response of this API call.

record_count

The number of records in this API response ‘page’. The default number of records per response is 100. Use the offset parameter to obtain subsequent records.

date

The date of the Whois record, in YYYY-MM-DD format.

is_private

Can be 0 (a publicly available record), or 1 (record with redactions made to it).
Note: “Use this to filter for records where DomainTools has identified the use of Whois privacy services or other instances of data redaction. DomainTools identification of privacy services or redacted data is on a best-effort basis only.”

whois

Marks the container containing the metadata and the actual Whois historical record. Certain field values may be missing if the data was not available when the record was stored in our system.

This container has the following properties:

  • registrant
  • registration
  • created
  • expires
  • registrar
  • statuses

name_servers

Hostname of the name server associated with the domain.

server

The server from which the Whois records are sourced in this result.

record

Marks the beginning container of the Whois record. The record is unparsed.

Use Cases for Whois History API Dataset

The API does not include Whois records with identical data unless those records are necessary to understand the history of the domain name.

For example, consider this hypothetical domain history:

  1. A domain name was registered in January 2020. DomainTools stores that initial Whois record.
  2. The contact information for that domain name changed in March 2020 and DomainTools stores the new record.
  3. No changes are made to that record for the next several months; however, DomainTools continues to store identical snapshots of the record.
  4. The domain name was sold in January 2021, and DomainTools stores the new ownership record.

In the above scenario, these records would indicate the following:

  • Length of ownership: The time between the first record (initial registration in January 2020) and the record representing the last record archived for the first owner.
  • Indication of no ownership changes: The record showing the March 2020 contact information update and subsequent records of snapshots of this March record may indicate that no ownership changes have occurred.
  • Indication of domain ownership change and the time window of such a change: The dates between the last record archived for the first owner record and the first record showing new domain ownership indicates a time window when the ownership of the domain changed.

API Specific Error Handling

Scenario: Partial Response Retrieved (from reaching Account Limits)

Response:

"record_count": 91,
"error": "Only partial results have been returned as your per-month service level was reached.",

Please contact Enterprise Support [email protected] for information regarding increasing your account limit.

To read more about the rest of the generic error handling codes and messages, please refer to the Error Codes page.

General Information
Products
DomainTools Logo
Pricing Contact Login Support Request a Demo

© 2024 DomainTools

DomainTools® and DomainTools™ are owned by DomainTools, all rights reserved.

Privacy Policy    |    California Privacy Notice
Do Not Sell My Personal Information    |    Terms of Service    |    Sitemap