Email Hippo WHOIS API Documentation¶
Email Hippo ‘WHOIS’ API services facilitate easy, fast and scalable access to the global WHOIS databases in both structured and un-structured formats.
This document will show you how to get up and running with the the service. You will have the basics of the API up and running in 15 minutes or less.
Quick Start¶
Quick Start¶
This quick start guide is designed to get you up and running as fast as possible.
Please follow the steps below in sequence:
2) Try it¶
Plug your license key into the following
https://api.whoishippo.com/v1/INSERTYOURLICENSEKEY/microsoft.com
Paste the url above into your browser and watch the response come back as in the example below:
{
"version": {
"v": "Enterprise-(1.0.17)",
"doc": ""
},
"meta": {
"recordCreatedDate": "2018-07-20T13:27:04Z",
"recordUpdatedDate": "2018-07-20T13:27:04Z",
"recordAge": "0 year(s), 0 months, 2 week(s), 0 day(s), 22 hour(s), 5 minute(s)",
"recordAgeIso8601": "P14DT22H5M30.7779301S",
"timeToExpiry": "2 year(s), 8 months, 4 week(s), 1 day(s)",
"timeToExpirySeconds": 86632045,
"timeToExpiryIso8601": "P2Y8M29D",
"tld": "com",
"domain": "microsoft.com",
"domainAge": "27 year(s), 3 month(s), 0 week(s), 2 day(s)",
"domainAgeSeconds": 860225554,
"domainAgeIso8601": "P27Y3M2D",
"parseCode": "Success",
"executionTime": 611
},
"whoisServerRecord": {
"recordFound": true,
"registrar": {
"registrarId": "292",
"name": "MarkMonitor, Inc.",
"whois": "whois.markmonitor.com",
"url": "http://www.markmonitor.com",
"abuseEmail": "abusecomplaints@markmonitor.com",
"abusePhone": "+1.2083895740"
},
"dnsSec": "unsigned",
"domainName": "microsoft.com",
"tld": "com",
"domainHandle": "2724960_DOMAIN_COM-VRSN",
"domainOwnerContact": {
"userId": "",
"name": "Domain Administrator",
"organization": "Microsoft Corporation",
"street1": "One Microsoft Way,",
"street2": null,
"street3": null,
"street4": null,
"city": "Redmond",
"state": "WA",
"postalCode": "98052",
"country": "US",
"phoneNumber": "+1.4258828080",
"phoneNumberExt": "",
"faxNumber": "+1.4259367329",
"faxNumberExt": "",
"email": "domains@microsoft.com"
},
"adminContact": {
"userId": "",
"name": "Domain Administrator",
"organization": "Microsoft Corporation",
"street1": "One Microsoft Way,",
"street2": null,
"street3": null,
"street4": null,
"city": "Redmond",
"state": "WA",
"postalCode": "98052",
"country": "US",
"phoneNumber": "+1.4258828080",
"phoneNumberExt": "",
"faxNumber": "+1.4259367329",
"faxNumberExt": "",
"email": "domains@microsoft.com"
},
"billingContact": {
"userId": null,
"name": null,
"organization": null,
"street1": null,
"street2": null,
"street3": null,
"street4": null,
"city": null,
"state": null,
"postalCode": null,
"country": null,
"phoneNumber": null,
"phoneNumberExt": null,
"faxNumber": null,
"faxNumberExt": null,
"email": null
},
"techContact": {
"userId": "",
"name": "MSN Hostmaster",
"organization": "Microsoft Corporation",
"street1": "One Microsoft Way,",
"street2": null,
"street3": null,
"street4": null,
"city": "Redmond",
"state": "WA",
"postalCode": "98052",
"country": "US",
"phoneNumber": "+1.4258828080",
"phoneNumberExt": "",
"faxNumber": "+1.4259367329",
"faxNumberExt": "",
"email": "msnhst@microsoft.com"
},
"registrarContact": {
"userId": null,
"name": null,
"organization": null,
"street1": null,
"street2": null,
"street3": null,
"street4": null,
"city": null,
"state": null,
"postalCode": null,
"country": null,
"phoneNumber": null,
"phoneNumberExt": null,
"faxNumber": null,
"faxNumberExt": null,
"email": null
},
"zoneContact": {
"userId": null,
"name": null,
"organization": null,
"street1": null,
"street2": null,
"street3": null,
"street4": null,
"city": null,
"state": null,
"postalCode": null,
"country": null,
"phoneNumber": null,
"phoneNumberExt": null,
"faxNumber": null,
"faxNumberExt": null,
"email": null
},
"nameServers": [
{
"Address": "ns3.msft.net"
},
{
"Address": "ns1.msft.net"
},
{
"Address": "ns2.msft.net"
},
{
"Address": "ns4.msft.net"
}
],
"domainStati": [
"clientUpdateProhibited (https://www.icann.org/epp#clientUpdateProhibited)",
"clientTransferProhibited (https://www.icann.org/epp#clientTransferProhibited)",
"clientDeleteProhibited (https://www.icann.org/epp#clientDeleteProhibited)",
"serverUpdateProhibited (https://www.icann.org/epp#serverUpdateProhibited)",
"serverTransferProhibited (https://www.icann.org/epp#serverTransferProhibited)",
"serverDeleteProhibited (https://www.icann.org/epp#serverDeleteProhibited)"
],
"remarks": null,
"reseller": "",
"created": "1991-05-02T04:00:00Z",
"changed": "2014-10-15T11:00:12Z",
"expiry": "2021-05-03T04:00:00Z",
"rawResponse": " Domain Name: MICROSOFT.COM\r\n Registry Domain ID: 2724960_DOMAIN_COM-VRSN\r\n Registrar WHOIS Server: whois.markmonitor.com\r\n Registrar URL: http://www.markmonitor.com\r\n Updated Date: 2014-10-09T16:28:25Z\r\n Creation Date: 1991-05-02T04:00:00Z\r\n Registry Expiry Date: 2021-05-03T04:00:00Z\r\n Registrar: MarkMonitor Inc.\r\n Registrar IANA ID: 292\r\n Registrar Abuse Contact Email: abusecomplaints@markmonitor.com\r\n Registrar Abuse Contact Phone: +1.2083895740\r\n Domain Status: clientDeleteProhibited https://icann.org/epp#clientDeleteProhibited\r\n Domain Status: clientTransferProhibited https://icann.org/epp#clientTransferProhibited\r\n Domain Status: clientUpdateProhibited https://icann.org/epp#clientUpdateProhibited\r\n Domain Status: serverDeleteProhibited https://icann.org/epp#serverDeleteProhibited\r\n Domain Status: serverTransferProhibited https://icann.org/epp#serverTransferProhibited\r\n Domain Status: serverUpdateProhibited https://icann.org/epp#serverUpdateProhibited\r\n Name Server: NS1.MSFT.NET\r\n Name Server: NS2.MSFT.NET\r\n Name Server: NS3.MSFT.NET\r\n Name Server: NS4.MSFT.NET\r\n DNSSEC: unsigned\r\n URL of the ICANN Whois Inaccuracy Complaint Form: https://www.icann.org/wicf/\r\n>>> Last update of whois database: 2018-07-20T13:26:49Z <<<\r\n\r\nFor more information on Whois status codes, please visit https://icann.org/epp\r\n\r\nNOTICE: The expiration date displayed in this record is the date the\r\nregistrar's sponsorship of the domain name registration in the registry is\r\ncurrently set to expire. This date does not necessarily reflect the expiration\r\ndate of the domain name registrant's agreement with the sponsoring\r\nregistrar. Users may consult the sponsoring registrar's Whois database to\r\nview the registrar's reported date of expiration for this registration.\r\n\r\nTERMS OF USE: You are not authorized to access or query our Whois\r\ndatabase through the use of electronic processes that are high-volume and\r\nautomated except as reasonably necessary to register domain names or\r\nmodify existing registrations; the Data in VeriSign Global Registry\r\nServices' (\"VeriSign\") Whois database is provided by VeriSign for\r\ninformation purposes only, and to assist persons in obtaining information\r\nabout or related to a domain name registration record. VeriSign does not\r\nguarantee its accuracy. By submitting a Whois query, you agree to abide\r\nby the following terms of use: You agree that you may use this Data only\r\nfor lawful purposes and that under no circumstances will you use this Data\r\nto: (1) allow, enable, or otherwise support the transmission of mass\r\nunsolicited, commercial advertising or solicitations via e-mail, telephone,\r\nor facsimile; or (2) enable high volume, automated, electronic processes\r\nthat apply to VeriSign (or its computer systems). The compilation,\r\nrepackaging, dissemination or other use of this Data is expressly\r\nprohibited without the prior written consent of VeriSign. You agree not to\r\nuse electronic processes that are automated and high-volume to access or\r\nquery the Whois database except as reasonably necessary to register\r\ndomain names or modify existing registrations. VeriSign reserves the right\r\nto restrict your access to the Whois database in its sole discretion to ensure\r\noperational stability. VeriSign may restrict or terminate your access to the\r\nWhois database for failure to abide by these terms of use. VeriSign\r\nreserves the right to modify these terms at any time.\r\n\r\nThe Registry database contains ONLY .COM, .NET, .EDU domains and\r\nRegistrars.",
"customFields": null
}
}
Note
Internet Explorer may prompt to download the file instead of simply displaying it on screen. This is a quirk of Internet Explorer and not an issue with the API. We do not recommend Internet Explorer for testing with the API. Instead, use Chrome or Firefox - both will display the results on screen correctly!
Data Privacy¶
Data Privacy¶
Compliance¶
emailhippo.com has been independently assessed as being ISO27001:2013 compliant by the British Assessment Bureau. Our certification number is 209495.
This means that we take your data privacy seriously.
Security¶
emailhippo.com takes the security of your data seriously. 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:
- All data in transit is encrypted using HTTPS.
- All data at rest (e.g. stored for caching and reporting purposes) is secured using AES-265 bit encryption.
Editions¶
About Editions¶
There are three editions of endpoints.
- Basic
- Professional
- Enterprise
Each varies in the amount and structure of the data returned.
The schema across all editions remains consistent which delivers the following benefits:
- Consistent integration with a consistent entity model
- Easily change between editions based on data depth versus performance requirements.
For more information, see Endpoint Details.
Integration Guide¶
Schema¶
- Endpoint Definitions
- WADL (swagger.io)
Firewall Rules¶
If your organization implements internal firewall rule policies, you may need to ask your IT staff to allow access to our API endpoints.
Our API services are delivered via Cloudflare. Please see the Cloudflare page “IP Ranges” for a definition of the IP endpoints that are possible when accessing our API.
Features¶
Features¶
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 Data Privacy for more information.
Consistent, parsed records¶
Note
Parsed records are available in Professional and Enterprise About Editions.
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 reading the relatively chaotic structure of WHOIS records into relaible, prdictable 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.9% Service Availability¶
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 Client Libraries to see how quick and easy it is to integrate with our services from over 19 different technologies and platforms.
Fanatical Service Quality Management (SQM)¶
Email Hippo operational staff obsessively monitor services to ensure the best possible uptime and coverage.
Uptime and functional correctness is 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.
Note
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.
Reliability¶
Service Reliability¶
Reliability of your systems is important to you and your clients. You can be sure that we won’t let you down when you use our services in your business applications.
By using the latest, distributed cloud based systems, we give deliver fast response times together with enterprise grade uptime of more than 99.9%.
About Our Infrastructure¶
We operate three data centers geographically dispersed as follows:
- Europe (Netherlands)
- United Kingdom (Ireland)
- United Kingdom (London)
Data centers provide automatic fail over to another working data center.
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.
Download our full Service Level Agreement for further infomation.
Concurrency¶
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 request) for subsequent requests for a duration of one minute.
Suggestions on how to manage throughput¶
There are several things that it may be helpful to think about to control throughput so as not to exceed the maximum limits described above such as:
- 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 of of the queue and submitting requests to our systems at a controllable rate.
Large throughput requirements¶
For sustained throughput more than 50 domain queries per second, please contact us for options on private, dedicated service.
Data Dictionary¶
Data Dictionary For WHOIS API V1¶
A response is a message consisting of a standard HTTP header and body. The body of the message contains the detail of the message (e.g. the JSON data with domain information). The header of the message contains general HTTP information such as HTTP status codes.
For full details of data dictionary, response codes and errors, please see Endpoint Definitions.
Client Libraries¶
Client Libraries¶
Swagger Code Generator¶
Use the Swagger Code Generator with our Swagger Schema to Generate API client code for:
- ActionScript
- Bash
- C# (.net 2.0, 4.0 or later)
- C++ (cpprest, Qt5, Tizen)
- Clojure
- Dart
- Elixir
- Go
- Groovy
- Haskell
- Java (Jersey1.x, Jersey2.x, OkHttp, Retrofit1.x, Retrofit2.x, Feign)
- Node.js (ES5, ES6, AngularJS with Google Closure Compiler annotations) Objective-C
- Perl
- PHP
- Python
- Ruby
- Scala
- Swift (2.x, 3.x)
- Typescript (Angular1.x, Angular2.x, Fetch, jQuery, Node)
Technical Specification¶
Technical Specification¶
Manufacturer | emailhippo.com |
Uptime | > 99.9% |
Response time | >0.2seconds < 8 seconds. Typical response time 0.7 seconds. |
Throughput and concurrency | > 100 TPS. |
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. |
FAQs¶
Frequently Asked Questions¶
Can I trust you with my data?¶
Great question. See Data Privacy for more information.
How can I get a key?¶
How do I call the API?¶
For a JSON response, make a simple GET request to the endpoint. For example, to query domain microsoft.com with license key ABCD1234 call:
https://api.whoishippo.com/v1/ABCD1234/microsoft.com
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:
- Level 1 cache: CloudFlare based. Cache expiration 2 hours.
- Level 2 cache: Microsoft Azure based. Cache expiration up to 90 days (depends on domain expiry in the WHOIS record).
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 authoritive 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.
Glossary¶
Glossary¶
- ACL
Access Control List.
An ACL determines what networking traffic is allowed to pass and what traffic is blocked.
An ACL change is sometimes required to your company firewall in order to access our API.
- API
Application Programmers Interface.
See Wikipedia - API Definition for more information.
- B2B
Business To(2) Business
Business email hosting services are generally private, enterprise grade hosting services typically hosted in either private data centers or in cloud based infrastructure.
Business to business refers to the activity of businesses sending email to clients using business email addresses.
- B2C
Business To(2) Consumer
Consumer email hosting providers are generally well known, mostly web based providers such as Hotmail, Yahoo, AOL, Gmail etc.
Business to consumer refers to the activity of businesses sending email to clients using consumer email addresses.
Verifying email addresses in consumer domains is generally more technically challenging than B2B
- BSON
Binary Object Notation
See Wikipedia - BSON for further information.
- CORS
Cross Origin Resource Scripting
Allows modern browsers to work with script (e.g. JavaScript) and JSON data originating form other domains.
CORS is required to allow client script such a JavaScript, jQuery or AngularJS to work with results returned from an external RESTful API.
See Wikipedia - CORS for more information.
- DDoS
Distributed Denial of Service
See Wikipedia - Denial-of-service attack for more information.
- Domain Name Registrar
A domain name registrar is an organization that manages the reservation of Internet domain names. A domain name registrar must be accredited by a generic top-level domain (gTLD) registry or a country code top-level domain (ccTLD) registry. A registrar operates in accordance with the guidelines of the designated domain name registries
See Wikipedia - Domain name registrar for more information.
- Domain Name Registry
A domain name registry is a database of all domain names and the associated registrant information in the top level domains of the Domain Name System (DNS) of the Internet that allow third party entities to request administrative control of a domain name. Most registries operate on the top-level and second-level of the DNS.
See Wikipedia - Domain name registry for more information.
- HTTP
Hypertext Transfer Protocol
See Wikipedia - Hypertext Transfer Protocol for more information.
- ISO 3166
International standard for country codes.
See Country Codes - ISO 3166 for more information.
- ISO 8601
International standard for date formats. Designed to ease and simplify machine to machine transfer of date information.
See Wikipedia - ISO8601 for more information.
- JSON
JavaScript Object Notation
JavaScript Object Notation, is an open standard format that uses human readable text to transmit data objects consisting of attribute value pairs. It is used primarily to transmit data between a server and web application, as an efficient, modern alternative to XML.
See Wikipedia - JSON for more information.
- License Key
License key authentication is best for situations where simplicity is required and you can keep the key private. An ideal use case for key authentication would be for server based applications calling the RESTful API.
Click here to request a license key.
- ms
- Milliseconds.
- parse
- Turn random, unstructured (sometimes chaotic) text into a predictable, machine readable format.
- parsed
- See parse above.
- protobuf
Protocol Buffers is a method of serializing structured data.
See Wikipedia - Protocol Buffers for more information.
- RESTful
Representational state transfer
See Wikipedia - RESTful for further information.
- RFC
Request for Comments
The principal technical development and standards-setting bodies for The Internet.
See Wikipedia - Request for Comments for further information.
- SLA
Service Level Agreement
See Wikipedia - SLA for more information and description of SLA.
See our Service Level Agreement.
- TLD
Top Level Domaain
See Wikipedia - Top-level domain for more information.
- WHOIS
WHOIS (pronounced as the phrase “who is”) is a query and response protocol that is widely used for querying databases that store the registered users or assignees of an Internet resource, such as a domain name, an IP address block or an autonomous system, but is also used for a wider range of other information.
See Wikipedia - WHOIS for more information.
- XML
e(X)tensible Markup Language
See Wikipedia - XML for further information.
\ Sort by:\ best rated\ newest\ oldest\
\\
Add a comment\ (markup):
\``code``
, \ code blocks:::
and an indented block after blank line