Sign Up

Technical Overview

Technical features
  • Consistent, parsed records - WHOIS records are intrinsically designed for humans to read and exist in different formats defined by individual Domain Name Registrars and the Domain Name Registries. Email Hippo's WHOIS service returns these records in a consistent machine-readable format.
  • Machine readable dates - For the ultimate in machine integration compatibility, Email Hippo returns dates and durations in ISO 8601 standard formats.

  • Returns:
    • Domain age
    • Owner and contact information

  • Thoughtful versioning - Endpoints are ‘versioned’ allowing the release of new functionality without forcing customers to change or break if they are committed to integrating with legacy endpoints.
Technical specification

 

Item Specification
Manufacturer emailhippo.com
Current version v1
Uptime > 99.99%
Response time >0.2 seconds < 8 seconds. Typical response time 0.4 seconds. 
Maximum wait time 90 seconds. This is the maximum time we'll wait for email servers to respond.
Throughput and concurrency 50 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
Authentication License key
Infrastructure Dispersed cloud data centers, auto load balance / failover.
Supported Top Level Domains (TLDs) .asia .br .co.uk .com.br .com .de .fr .info .io .in .jp .me.uk .mobi .net .org .org.uk .ru .uk

 

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 requests 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:

  • Test your integration with representative production loads over a period of time. Monitor response codes for any 429’s. If you see any 429’s please reduce the rate at which your application is querying our servers.

  • For applications that can tolerate slight delays in your data processing mesh, consider using queuing infrastructure with a rate controllable processor. Your ‘processor’ can then schedule picking work off the queue and submitting requests to our systems at a controllable rate.

Large throughput requirement

For sustained throughput of more than 220 queries per second, please contact us.

Authentication

Email Hippo WHOIS uses API keys to allow access to the API. API keys can be managed within Hippo World.

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

{k}: yourlicensekey

 You must replace yourlicensekey with your personal API key.

 

 

Endpoint - GET WHOIS by domain

Query WHOIS records by domain and license key.

  • JSON     GET //api.whoishippo.com//v1/{k}/{d}

GET WHOIS record.

Parameter In Type Required Description
k path string true the license key
d path string true the domain to query

 

Responses (including errors)
Status Meaning Description Schema
200 OK Success ResultRecord
400 Bad Request Bad request. The server could not understand the request. Perhaps missing a license key or an email to check? Conditions that lead to this error are: No license key supplied, no email address supplied, email address > 255 characters, license key in incorrect format. None
401 Unauthorised Possible reasons: The provided license key is not valid, the provided license key has expired, you have reached your quota capacity for this account, this account has been disabled. 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. See Concurrency for further information. None
500 Internal Server Error An error occurred on the server. Possible reasons are: license key validation failed or a general server fault. None
JSON 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": "string",
    "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"
      }
    ]
  }
} 
Result record schema
Name Type Required Restrictions Description
Version        
 v string false none none
 doc string false none none
Meta        
 recordCreatedDate datetime false none none
 recordUpdatedDate datetime 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  string false none none
 executionTime integer(int64) false none none
WhoisServerRecord        
 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 datetime false none none
 changed datetime false none none
 expiry datetime false none none
 rawResponse string false none none
 customFields CustomField[]  false none none

 

Registrar

 

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

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

Name Type Required Restrictions Description
Address string false none none

 

CustomField

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

 

Value Description
Success WHOIS information found
Notfound

No WHOIS information found

 

Example custom code snippets

          
* © 2020, Email Hippo Limited. (http://emailhippo.com)


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

        
          
/*
* © 2020, Email Hippo Limited. (http://emailhippo.com)
*/
<?php



<?php

// URL which should be requested
$url = 'https://api.whoishippo.com/v1';

$apikey = 'YOUR API KEY'; // API Key

$domain = 'Domain to query'; // Domain to query

// jSON String for request
$url .= "/$apikey/$domain";

// Initializing curl
$ch = curl_init( $url );

if($ch == false) {
    die ("Curl failed!");
} else {

  // Configuring curl options
  $options = array(
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => array('Content-type: application/json')
  );

  // Setting curl options
  curl_setopt_array( $ch, $options );

  // Getting results
  $result = curl_exec($ch); // Getting jSON result string

  // display JSON data
  echo "$result";

}
?>

        
          
/*
* © 2020, Email Hippo Limited. (http://emailhippo.com)
*/



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);
});

        
          
/*
* © 2020, Email Hippo Limited. (http://emailhippo.com)
*/


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());

        
          
/*
* © 2020, Email Hippo Limited. (http://emailhippo.com)
*/


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)

        
          
# © 2020, Email Hippo Limited. (http://emailhippo.com)



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

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

}, headers = headers)

print r.json() 

        
          
/*
* © 2020, Email Hippo Limited. (http://emailhippo.com)
*/


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)
    // ...
}

        
          
/*
* © 2020, Email Hippo Limited. (http://emailhippo.com)
*/


#region Usings

using System;
using System.IO;
using System.Net;

#endregion

/// <summary>
/// The program.
/// </summary>
internal class Program
{
    #region Constants

    /// <summary>
    /// The api url.
    /// </summary>
    private const string ApiUrl = @"https://api.whoishippo.com/v1";
    /// <summary>
    /// 0 = ApiUrl
    /// 1 = API Key
    /// 2 = Domain to query
    /// </summary>
    private const string QueryFormatString = @"{0}/{1}/{2}";

    /// <summary>
    /// The your api key.
    /// </summary>
    /// <remarks>
    /// /*ENTER YOUR API KEY HERE*/
    /// </remarks>
    private const string YourAPIKey = @"<!-- ENTER A VALID KEY HERE-->";

    #endregion

    #region Methods

    /// <summary>
    /// The main program entry point.
    /// </summary>
    /// <param name="args">
    /// The args.
    /// </param>
    private static void Main(string[] args)
    {
        Console.WriteLine("Input domain to query");

        var readLine = Console.ReadLine();

        Console.WriteLine(string.Empty);

        var requestUrl = string.Format(QueryFormatString, ApiUrl, YourAPIKey, readLine);

        var myRequest = (HttpWebRequest)WebRequest.Create(requestUrl);

        WebResponse webResponse = null;

        try
        {
            webResponse = myRequest.GetResponse();

            using (var reader = new StreamReader(webResponse.GetResponseStream()))
            {
                var jsonString = reader.ReadToEnd();

                Console.ForegroundColor = ConsoleColor.Green;
                Console.WriteLine("Result:");
                Console.WriteLine(jsonString);
                Console.ResetColor();
                Console.WriteLine("Press <Enter> to continue..");
                Console.ReadLine();
            }
        }
        catch (Exception exception)
        {
            Console.WriteLine("An error occured:");
            Console.ForegroundColor = ConsoleColor.Red;
            Console.WriteLine("Exception reported: {0}", exception.Message);
            Console.ResetColor();
            Console.WriteLine("Press <Enter> to continue..");
            Console.ReadLine();
        }
        finally
        {
            if (webResponse != null)
            {
                webResponse.Dispose();
            }
        }
    }

    #endregion
}

Talk to us about your integration requirements

If you'd like more information about a popular Email Hippo integration, or would like to discuss an integration requirement,  or  if you just have an integration question please get in touch today and we'll help you find the best solution for you.

CONTACT US

Not yet using Email Hippo for your email verification?

What are you waiting for?

Trial our email verification for free. Register today for 100 free email validations. No credit card details needed to create your account.

 

Sign Up Graphic (1)