NAV Navbar
Shell HTTP JavaScript Node.JS Ruby Python Java Go

Email Hippo WHOIS API v1

Scroll down for code samples, example requests and responses. Select a language for code samples from the tabs above or the mobile navigation menu.

Eh horiz 695x161

Introduction

Email Hippo WHOIS API services facilitate easy, fast and scalable access to the global WHOIS databases in both structured and unstructured formats.

Quick start

Ready to get implementing?

Data privacy

We take your privacy, data security and legislative compliance seriously.

Compliance

emailhippo.com has been independently assessed as being ISO27001:2013 compliant by the British Assessment Bureau. Our certification number is 209495.

Security

Email Hippo takes the security of your data seriously. Here are the details of how your data is received, stored and processed.

Other than the human-based policies and procedures defined in the Data processing terms, there are a few technology-based issues to mention:

Data processing terms

Click to learn more

Privacy policy

Click to learn more

Click to learn more

Product information

Terms of service

Click to learn more

Features and benefits

Confidence in data security

With ISO27001:2013 certification, robust technology and clearly defined policies and procedures, you can trust Email Hippo with your data.

See privacy policy for more information.

Consistent, parsed records

WHOIS records are intrinsically designed for humans to read and records come in different formats according to the choices made by an individual Domain Name Registrar and the Domain Name Registry.

For any serious application demanding data in a predictable, consistent machine-readable format, the standard WHOIS system will not work. This is where Email Hippo adds value to the WHOIS system by adding services capable of presenting the relatively chaotic structure of WHOIS records as reliable, predictable and machine-readable formats.

Machine readable dates

For ultimate in machine integration compatibility, Email Hippo returns dates and durations in ISO 8601 standard formats.

> 99.95% uptime

Fully load balanced and automatic fail-over systems dispersed across multiple data centers in multiple regions deliver enterprise-grade resilience.

See Service reliability for more information on availability and SLA.

Easy integration

See integrations to see how quick and easy it is to integrate with our services from over 19 different technologies and platforms.

Fanatical Service Quality Management

Email Hippo operational staff obsessively monitor services to ensure the best possible uptime and coverage.

Uptime and functional correctness are actively monitored on a minute by minute basis from multiple data centers dispersed across North America, Europe, and Asia.

Fast, transparent response times

Every query response includes stopwatch data that shows the time taken to execute the request.

Unrivalled performance

Strategic data centers in Europe, aggressive caching, global network delivery optimization and cloud-based auto-scaling deliver outstanding performance. Typical queries are answered between 0.2 to 1.5 seconds.

Thoughtful versioning

Endpoints are “versioned”. This means that Email Hippo can continue to release new functionality without “breaking” existing clients committed to integrating with our systems on legacy endpoints.

What it does

Email Hippo is used to query WHOIS records in real-time.

Editions

Features by edition

Edition 1 2
Raw WHOIS text
Hippo database dates
Time to expiry date
Time to expiry (ISO-8601)
Domain age
Domain age (ISO-8601)
WHOIS Record created date
Registrar data
Administrator data
Billing contact data
Technical contact data
Registrar contact data
Zone contact data
Name servers
Domain status details
Created date
Changed date
Expiry date

Supported Top Level Domains (TLDs)

Service reliability

Like you, we care about the reliability of our services.

By using the latest, distributed cloud-based systems, we deliver fast response times together with an enterprise-grade uptime of more than 99.95%.

About our infrastructure

We operate three data centers geographically dispersed as follows:

Network traffic is optimized for fast, reliable global delivery using Cloudflare Argo.

Service level agreement

Our API has a stated SLA that ensures that we provide you with more than 99.9% uptime for our services.

See our full service level agreement for further information.

Concurrency

To preserve the operational integrity of the service to all of our customers, there is a maximum concurrency enforced by our systems.

Limits

Allowed throughput is 50 WHOIS queries per second.

Throughput exceeding these limits will receive HTTP response code 429 (too many requests) for subsequent requests for a duration of one minute.

Suggestions on how to manage throughput

If you experience or anticipate exceeding throughput limits, here are two ways to control query rates:

Large throughput requirement

For sustained throughput of more than 50 domain queries per second, please contact us about a private, dedicated service.

Specification

Item Spec
Manufacturer emailhippo.com
Uptime > 99.95%
Response time >0.2seconds < 8 seconds. Typical response time 0.7 seconds.
Throughput and concurrency > 100 TPS(Transactions Per Second)
Security and encryption Transport security using HTTPS. Data at rest encrypted using 256-bit AES encryption.
Integration RESTful GET over HTTPS, XML GET over HTTPS, BSON over HTTPS, protobuf over HTTPS
Authentication License key
Infrastructure Geographically dispersed cloud data centers, auto load balance / failover

Integrations

Download ready-made server and client integrations for many languages and platforms from our Swagger Hub.

Integration libraries included for:

Frequently asked questions

Can I trust you with my data?

Great question. See Data privacy for more information.

How can I get a key?

Click here to request a key

How reliable is the API?

> 99.95% average availability with a defined SLA.

Does the system get slower when it’s busy?

No. All infrastructure is hosted in cloud based platforms with automatic scaling enabled. Automatic scaling kicks in at busy times to provide more hardware resources to meet demand.

Do you cache results?

To deliver the speed and reliability demanded by our customers, verification results are cached as follows:

Can I get my usage in real-time?

Not yet. This feature is in the development pipeline.

How does it work?

At a basic conceptual level, the process of querying WHOIS services is very simple. First, find the authoritative WHOIS server for a particular TLD. Next, connect to the server on port 43, query the domain and capture the response.

The hard bit is dealing with WHOIS services that are intrinsically configured to work against the process of querying domains in any form large volume scale. Additionally, the WHOIS system does not follow one, unified standard which means that the data returned from WHOIS services is very difficult to parse to anything that is useful for automation or integration purposes.

Email Hippo’s strength in dealing with the “hard bit” of the WHOIS system comes from years of experience in solving similar challenges in email verification.

Can I get blacklisted using this API?

No. It’s Email Hippo infrastructure that does the work.

Will anyone know that I am quering a domain?

No. It’s Email Hippo infrastructure that does the work.

Swagger

You can access our Swagger resources as below:

WHOIS API reference

Authorization

Email Hippo WHOIS uses API keys to allow access to the API. You can register a new WHOIS API key at our contact form.

Email Hippo WHOIS expects the API key to be included in all API requests to the server.

{k}: yourlicensekey

Base URLs:

//api.whoishippo.com/

Get WHOIS By Domain

Query WHOIS records by domain and license key.

Code samples

# You can also use wget
curl -X GET //api.whoishippo.com/v1/{k}/{d} \
  -H 'Accept: application/json'

GET //api.whoishippo.com/v1/{k}/{d} HTTP/1.1
Host: null

Accept: application/json

var headers = {
  'Accept':'application/json'

};

$.ajax({
  url: '//api.whoishippo.com/v1/{k}/{d}',
  method: 'get',

  headers: headers,
  success: function(data) {
    console.log(JSON.stringify(data));
  }
})

const request = require('node-fetch');

const headers = {
  'Accept':'application/json'

};

fetch('//api.whoishippo.com/v1/{k}/{d}',
{
  method: 'GET',

  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

require 'rest-client'
require 'json'

headers = {
  'Accept' => 'application/json'
}

result = RestClient.get '//api.whoishippo.com/v1/{k}/{d}',
  params: {
  }, headers: headers

p JSON.parse(result)

import requests
headers = {
  'Accept': 'application/json'
}

r = requests.get('//api.whoishippo.com/v1/{k}/{d}', params={

}, headers = headers)

print r.json()

URL obj = new URL("//api.whoishippo.com/v1/{k}/{d}");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("GET");
int responseCode = con.getResponseCode();
BufferedReader in = new BufferedReader(
    new InputStreamReader(con.getInputStream()));
String inputLine;
StringBuffer response = new StringBuffer();
while ((inputLine = in.readLine()) != null) {
    response.append(inputLine);
}
in.close();
System.out.println(response.toString());

package main

import (
       "bytes"
       "net/http"
)

func main() {

    headers := map[string][]string{
        "Accept": []string{"application/json"},

    }

    data := bytes.NewBuffer([]byte{jsonReq})
    req, err := http.NewRequest("GET", "//api.whoishippo.com/v1/{k}/{d}", data)
    req.Header = headers

    client := &http.Client{}
    resp, err := client.Do(req)
    // ...
}

GET /v1/{k}/{d}

Get WHOIS record.

Parameters

Parameter In Type Required Description
k path string true The key.
d path string true The domain to query.

Example responses

200 Response

{
  "version": {
    "v": "string",
    "doc": "string"
  },
  "meta": {
    "recordCreatedDate": "2018-08-09T10:26:42Z",
    "recordUpdatedDate": "2018-08-09T10:26:42Z",
    "recordAge": "string",
    "recordAgeIso8601": "string",
    "timeToExpiry": "string",
    "timeToExpirySeconds": 0,
    "timeToExpiryIso8601": "string",
    "tld": "string",
    "domain": "string",
    "domainAge": "string",
    "domainAgeSeconds": 0,
    "domainAgeIso8601": "string",
    "parseCode": 0,
    "executionTime": 0
  },
  "whoisServerRecord": {
    "recordFound": true,
    "registrar": {
      "registrarId": "string",
      "name": "string",
      "whois": "string",
      "url": "string",
      "abuseEmail": "string",
      "abusePhone": "string"
    },
    "dnsSec": "string",
    "domainName": "string",
    "tld": "string",
    "domainHandle": "string",
    "domainOwnerContact": {
      "userId": "string",
      "name": "string",
      "organization": "string",
      "street1": "string",
      "street2": "string",
      "street3": "string",
      "street4": "string",
      "city": "string",
      "state": "string",
      "postalCode": "string",
      "country": "string",
      "phoneNumber": "string",
      "phoneNumberExt": "string",
      "faxNumber": "string",
      "faxNumberExt": "string",
      "email": "string"
    },
    "adminContact": {
      "userId": "string",
      "name": "string",
      "organization": "string",
      "street1": "string",
      "street2": "string",
      "street3": "string",
      "street4": "string",
      "city": "string",
      "state": "string",
      "postalCode": "string",
      "country": "string",
      "phoneNumber": "string",
      "phoneNumberExt": "string",
      "faxNumber": "string",
      "faxNumberExt": "string",
      "email": "string"
    },
    "billingContact": {
      "userId": "string",
      "name": "string",
      "organization": "string",
      "street1": "string",
      "street2": "string",
      "street3": "string",
      "street4": "string",
      "city": "string",
      "state": "string",
      "postalCode": "string",
      "country": "string",
      "phoneNumber": "string",
      "phoneNumberExt": "string",
      "faxNumber": "string",
      "faxNumberExt": "string",
      "email": "string"
    },
    "techContact": {
      "userId": "string",
      "name": "string",
      "organization": "string",
      "street1": "string",
      "street2": "string",
      "street3": "string",
      "street4": "string",
      "city": "string",
      "state": "string",
      "postalCode": "string",
      "country": "string",
      "phoneNumber": "string",
      "phoneNumberExt": "string",
      "faxNumber": "string",
      "faxNumberExt": "string",
      "email": "string"
    },
    "registrarContact": {
      "userId": "string",
      "name": "string",
      "organization": "string",
      "street1": "string",
      "street2": "string",
      "street3": "string",
      "street4": "string",
      "city": "string",
      "state": "string",
      "postalCode": "string",
      "country": "string",
      "phoneNumber": "string",
      "phoneNumberExt": "string",
      "faxNumber": "string",
      "faxNumberExt": "string",
      "email": "string"
    },
    "zoneContact": {
      "userId": "string",
      "name": "string",
      "organization": "string",
      "street1": "string",
      "street2": "string",
      "street3": "string",
      "street4": "string",
      "city": "string",
      "state": "string",
      "postalCode": "string",
      "country": "string",
      "phoneNumber": "string",
      "phoneNumberExt": "string",
      "faxNumber": "string",
      "faxNumberExt": "string",
      "email": "string"
    },
    "nameServers": [
      {
        "Address": "string"
      }
    ],
    "domainStati": [
      "string"
    ],
    "remarks": "string",
    "reseller": "string",
    "created": "2018-08-09T10:26:42Z",
    "changed": "2018-08-09T10:26:42Z",
    "expiry": "2018-08-09T10:26:42Z",
    "rawResponse": "string",
    "customFields": [
      {
        "customFieldId": 0,
        "name": "string",
        "value": "string"
      }
    ]
  }
}

Responses

Status Meaning Description Schema
200 OK Success WhoisRecord
400 Bad Request Must enter a valid license key and domain to query or; A domain to query is required. None
401 Unauthorized * License key refused or; Key expired or quota exceeded. None
404 Not Found The domain is not found in WHOIS. None
422 Unprocessable Entity Cannot process a fully parsed respone. Top Level Domain (TLD) is not supported. None
429 Too Many Requests Maximum processing rate exceeded. Please slow your requests to < 50 queries per second. None
500 Internal Server Error Server error. None

Schemas

WhoisRecord

{
  "version": {
    "v": "string",
    "doc": "string"
  },
  "meta": {
    "recordCreatedDate": "2018-08-09T10:26:42Z",
    "recordUpdatedDate": "2018-08-09T10:26:42Z",
    "recordAge": "string",
    "recordAgeIso8601": "string",
    "timeToExpiry": "string",
    "timeToExpirySeconds": 0,
    "timeToExpiryIso8601": "string",
    "tld": "string",
    "domain": "string",
    "domainAge": "string",
    "domainAgeSeconds": 0,
    "domainAgeIso8601": "string",
    "parseCode": 0,
    "executionTime": 0
  },
  "whoisServerRecord": {
    "recordFound": true,
    "registrar": {
      "registrarId": "string",
      "name": "string",
      "whois": "string",
      "url": "string",
      "abuseEmail": "string",
      "abusePhone": "string"
    },
    "dnsSec": "string",
    "domainName": "string",
    "tld": "string",
    "domainHandle": "string",
    "domainOwnerContact": {
      "userId": "string",
      "name": "string",
      "organization": "string",
      "street1": "string",
      "street2": "string",
      "street3": "string",
      "street4": "string",
      "city": "string",
      "state": "string",
      "postalCode": "string",
      "country": "string",
      "phoneNumber": "string",
      "phoneNumberExt": "string",
      "faxNumber": "string",
      "faxNumberExt": "string",
      "email": "string"
    },
    "adminContact": {
      "userId": "string",
      "name": "string",
      "organization": "string",
      "street1": "string",
      "street2": "string",
      "street3": "string",
      "street4": "string",
      "city": "string",
      "state": "string",
      "postalCode": "string",
      "country": "string",
      "phoneNumber": "string",
      "phoneNumberExt": "string",
      "faxNumber": "string",
      "faxNumberExt": "string",
      "email": "string"
    },
    "billingContact": {
      "userId": "string",
      "name": "string",
      "organization": "string",
      "street1": "string",
      "street2": "string",
      "street3": "string",
      "street4": "string",
      "city": "string",
      "state": "string",
      "postalCode": "string",
      "country": "string",
      "phoneNumber": "string",
      "phoneNumberExt": "string",
      "faxNumber": "string",
      "faxNumberExt": "string",
      "email": "string"
    },
    "techContact": {
      "userId": "string",
      "name": "string",
      "organization": "string",
      "street1": "string",
      "street2": "string",
      "street3": "string",
      "street4": "string",
      "city": "string",
      "state": "string",
      "postalCode": "string",
      "country": "string",
      "phoneNumber": "string",
      "phoneNumberExt": "string",
      "faxNumber": "string",
      "faxNumberExt": "string",
      "email": "string"
    },
    "registrarContact": {
      "userId": "string",
      "name": "string",
      "organization": "string",
      "street1": "string",
      "street2": "string",
      "street3": "string",
      "street4": "string",
      "city": "string",
      "state": "string",
      "postalCode": "string",
      "country": "string",
      "phoneNumber": "string",
      "phoneNumberExt": "string",
      "faxNumber": "string",
      "faxNumberExt": "string",
      "email": "string"
    },
    "zoneContact": {
      "userId": "string",
      "name": "string",
      "organization": "string",
      "street1": "string",
      "street2": "string",
      "street3": "string",
      "street4": "string",
      "city": "string",
      "state": "string",
      "postalCode": "string",
      "country": "string",
      "phoneNumber": "string",
      "phoneNumberExt": "string",
      "faxNumber": "string",
      "faxNumberExt": "string",
      "email": "string"
    },
    "nameServers": [
      {
        "Address": "string"
      }
    ],
    "domainStati": [
      "string"
    ],
    "remarks": "string",
    "reseller": "string",
    "created": "2018-08-09T10:26:42Z",
    "changed": "2018-08-09T10:26:42Z",
    "expiry": "2018-08-09T10:26:42Z",
    "rawResponse": "string",
    "customFields": [
      {
        "customFieldId": 0,
        "name": "string",
        "value": "string"
      }
    ]
  }
}

Properties

Name Type Required Restrictions Description
version Version false none none
meta Meta false none none
whoisServerRecord WhoisServerRecord false none none

Version

{
  "v": "string",
  "doc": "string"
}

Properties

Name Type Required Restrictions Description
v string false none none
doc string false none none

Meta

{
  "recordCreatedDate": "2018-08-09T10:26:42Z",
  "recordUpdatedDate": "2018-08-09T10:26:42Z",
  "recordAge": "string",
  "recordAgeIso8601": "string",
  "timeToExpiry": "string",
  "timeToExpirySeconds": 0,
  "timeToExpiryIso8601": "string",
  "tld": "string",
  "domain": "string",
  "domainAge": "string",
  "domainAgeSeconds": 0,
  "domainAgeIso8601": "string",
  "parseCode": 0,
  "executionTime": 0
}

Properties

Name Type Required Restrictions Description
recordCreatedDate string(date-time) false none none
recordUpdatedDate string(date-time) false none none
recordAge string false none none
recordAgeIso8601 string false none none
timeToExpiry string false none none
timeToExpirySeconds integer(int64) false none none
timeToExpiryIso8601 string false none none
tld string false none none
domain string false none none
domainAge string false none none
domainAgeSeconds integer(int64) false none none
domainAgeIso8601 string false none none
parseCode integer(int32) false none none
executionTime integer(int64) false none none

Enumerated Values

Property Value
parseCode 0
parseCode 200
parseCode 401
parseCode 403
parseCode 404
parseCode 406
parseCode 408
parseCode 410
parseCode 418
parseCode 429
parseCode 451
parseCode 500
parseCode 501
parseCode 503

WhoisServerRecord

{
  "recordFound": true,
  "registrar": {
    "registrarId": "string",
    "name": "string",
    "whois": "string",
    "url": "string",
    "abuseEmail": "string",
    "abusePhone": "string"
  },
  "dnsSec": "string",
  "domainName": "string",
  "tld": "string",
  "domainHandle": "string",
  "domainOwnerContact": {
    "userId": "string",
    "name": "string",
    "organization": "string",
    "street1": "string",
    "street2": "string",
    "street3": "string",
    "street4": "string",
    "city": "string",
    "state": "string",
    "postalCode": "string",
    "country": "string",
    "phoneNumber": "string",
    "phoneNumberExt": "string",
    "faxNumber": "string",
    "faxNumberExt": "string",
    "email": "string"
  },
  "adminContact": {
    "userId": "string",
    "name": "string",
    "organization": "string",
    "street1": "string",
    "street2": "string",
    "street3": "string",
    "street4": "string",
    "city": "string",
    "state": "string",
    "postalCode": "string",
    "country": "string",
    "phoneNumber": "string",
    "phoneNumberExt": "string",
    "faxNumber": "string",
    "faxNumberExt": "string",
    "email": "string"
  },
  "billingContact": {
    "userId": "string",
    "name": "string",
    "organization": "string",
    "street1": "string",
    "street2": "string",
    "street3": "string",
    "street4": "string",
    "city": "string",
    "state": "string",
    "postalCode": "string",
    "country": "string",
    "phoneNumber": "string",
    "phoneNumberExt": "string",
    "faxNumber": "string",
    "faxNumberExt": "string",
    "email": "string"
  },
  "techContact": {
    "userId": "string",
    "name": "string",
    "organization": "string",
    "street1": "string",
    "street2": "string",
    "street3": "string",
    "street4": "string",
    "city": "string",
    "state": "string",
    "postalCode": "string",
    "country": "string",
    "phoneNumber": "string",
    "phoneNumberExt": "string",
    "faxNumber": "string",
    "faxNumberExt": "string",
    "email": "string"
  },
  "registrarContact": {
    "userId": "string",
    "name": "string",
    "organization": "string",
    "street1": "string",
    "street2": "string",
    "street3": "string",
    "street4": "string",
    "city": "string",
    "state": "string",
    "postalCode": "string",
    "country": "string",
    "phoneNumber": "string",
    "phoneNumberExt": "string",
    "faxNumber": "string",
    "faxNumberExt": "string",
    "email": "string"
  },
  "zoneContact": {
    "userId": "string",
    "name": "string",
    "organization": "string",
    "street1": "string",
    "street2": "string",
    "street3": "string",
    "street4": "string",
    "city": "string",
    "state": "string",
    "postalCode": "string",
    "country": "string",
    "phoneNumber": "string",
    "phoneNumberExt": "string",
    "faxNumber": "string",
    "faxNumberExt": "string",
    "email": "string"
  },
  "nameServers": [
    {
      "Address": "string"
    }
  ],
  "domainStati": [
    "string"
  ],
  "remarks": "string",
  "reseller": "string",
  "created": "2018-08-09T10:26:42Z",
  "changed": "2018-08-09T10:26:42Z",
  "expiry": "2018-08-09T10:26:42Z",
  "rawResponse": "string",
  "customFields": [
    {
      "customFieldId": 0,
      "name": "string",
      "value": "string"
    }
  ]
}

Properties

Name Type Required Restrictions Description
recordFound boolean false none none
registrar Registrar false none none
dnsSec string false none none
domainName string false none none
tld string false none none
domainHandle string false none none
domainOwnerContact Contact false none none
adminContact Contact false none none
billingContact Contact false none none
techContact Contact false none none
registrarContact Contact false none none
zoneContact Contact false none none
nameServers [NameServer] false none none
domainStati [string] false none none
remarks string false none none
reseller string false none none
created string(date-time) false none none
changed string(date-time) false none none
expiry string(date-time) false none none
rawResponse string false none none
customFields [CustomField] false none none

Registrar

{
  "registrarId": "string",
  "name": "string",
  "whois": "string",
  "url": "string",
  "abuseEmail": "string",
  "abusePhone": "string"
}

Properties

Name Type Required Restrictions Description
registrarId string false none none
name string false none none
whois string false none none
url string false none none
abuseEmail string false none none
abusePhone string false none none

Contact

{
  "userId": "string",
  "name": "string",
  "organization": "string",
  "street1": "string",
  "street2": "string",
  "street3": "string",
  "street4": "string",
  "city": "string",
  "state": "string",
  "postalCode": "string",
  "country": "string",
  "phoneNumber": "string",
  "phoneNumberExt": "string",
  "faxNumber": "string",
  "faxNumberExt": "string",
  "email": "string"
}

Properties

Name Type Required Restrictions Description
userId string false none none
name string false none none
organization string false none none
street1 string false none none
street2 string false none none
street3 string false none none
street4 string false none none
city string false none none
state string false none none
postalCode string false none none
country string false none none
phoneNumber string false none none
phoneNumberExt string false none none
faxNumber string false none none
faxNumberExt string false none none
email string false none none

NameServer

{
  "Address": "string"
}

Properties

Name Type Required Restrictions Description
Address string false none none

CustomField

{
  "customFieldId": 0,
  "name": "string",
  "value": "string"
}

Properties

Name Type Required Restrictions Description
customFieldId integer(int32) false none none
name string false none none
value string false none none

Errors

The WHOIS API uses the following error codes:

Status Meaning Description
400 Bad Request Must enter a valid license key and domain to query or; A domain to query is required.
401 Unauthorized * License key refused or; Key expired or quota exceeded.
404 Not Found The domain is not found in WHOIS.
422 Unprocessable Entity Cannot process a fully parsed respone. Top Level Domain (TLD) is not supported.
429 Too Many Requests Maximum processing rate exceeded. Please slow your requests to < 50 queries per second.
500 Internal Server Error Server error.