Hoover's API Version 3.3 - Overview

New Production Version - Hoover's API Version 3.3

Version 3.3 of the Hoover's API is now available. This release includes several REST services to complement the existing SOAP services available. These services allow access via a RESTful manner to some of our most popular data and searches - namely company and people build a list searches (aka Advanced searches), our company keyword search and company and person details. This release also adds new Personalization services, including access to the MyContacts feature and notes which can be seen on our website as well. Also included in the release are various minor enhancements and bugfixes.

Please note that a valid Hoover's username and password is required to use the REST services. This username/password should be added to the HTTP header. A valid Hoover's username and password is also required for the Personalization services and should be added as part of the SOAP header.

The documentation below outlines the new data points and search parameters available, as well as other code changes.

New features are highlighted.

What's New

If you have used the Hoover's API documentation in versions 2.0 and older, you will notice a few changes. We have listed the major changes below to assist you in your transition to the new layout and calls.

  • New for Version 3.3
    • 8 REST services covering searches and company/person detail
    • New SOAP Services - Personalization features around Notes and Contacts
    • New SOAP Service - GetCompanyFinancialDetail
    • New SOAP Service - AdvancedCompanySearchOptionalData - returns more data optionally for a company. The tradeoff being the more data you request, the slower the call as it has to gather more information.
    • Historical indicator and historical text added to GetCompanyDetail
    • Additional sources of data for ConnectMail direct phone numbers and emails
    • GetPersonDetail & GetPersonDetailSimple - Pick a Currency
    • Navigators added to Advanced Searches
  • New for Version 3.2 - GetCompanyNews, ConnectMail fields in GetPersonDetail and GetPersonDetailSimple
  • New for Version 3.1 - All monetary fields in the advanced person and company search requests are now of xs:decimal type.
  • Documentation page broken up into multiple pages - The old format was fine when we had 10 service operations but now that we have 20 and more planned, we broke the page up into multiple sections - this Overview, Company, Person, Industry and Lookup
  • Sample XML Removed - Providing the sample XML was time consuming and we did not feel it added value, as most development done against the Hoover's API uses some sort of SOAP framework, and therefore the XML is not hand-coded
  • Required column removed - Previously, if a field was required in the request, we had a column named "Required" that had either "true" or "false" as the value. We now use the required indicator to mark a field as required
  • Removed data types - The WSDL is the definitive source for the datatype of each field. If there is something strange about the datatype, we will list it in the Notes.
  • Company ID change - while DUNS is still standard, we have slightly modified our external Company ID. Going forward, the Company ID will either be solely a 7 to 9 digit DUNS or a 14 to 15 digit Company ID that is a 5 to 6 digit id followed by 9 zeros. If you stored the Company ID previously, you will need to convert that ID. Specifically:
    • If your Company ID is greater than 9 digits, replace the last 9 digits with zeros to get the version 3.0 compatible Company ID
    • If your Company ID is 9 or fewer digits, do not change it - it will work with version 3.0 as is


1. API Overview

The Hoover's API allows you to integrate Hoover's people and company data into your own applications. The API Documentation covers all aspects of the Hoover's API. If you have any questions, please post them on the Ask a Question section of the forum.

1.1 API URL and WSDL

The WSDL for the Hoover's API can be found at http://hapi-dev.hoovers.com/HooversAPI-33/hooversAPI/hooversAPI.wsdl. To make a call to the Hoover's API, send your SOAP request (don't forget your developer key in the SOAP Header) to http://hapi-dev.hoovers.com/HooversAPI-33.

1.2 API Use and Timeouts

On occasion, your application may experience a timeout when calling the Hoover's API. The timeout will appear as an HTTP 403 or 504 error with a useful error message in the HTTP Header. It could be that you exceeded the number of queries per second or day in your Terms of Service or it is possible that you were denied access due to the aggregate queries per second limit. The aggregate queries per second limit is a fail-safe of the Hoover's API, where the system denies all requests over a certain amount per second (set by Hoover's) to ensure the stability of the Hoover's environment. This second type of timeout should only happen in the rarest of situations.

In case the number of calls per second or the aggregate queries per second is exceeded, you will receive a timeout. Write your application to re-attempt the request. However, if your application tries several times and cannot get through, please allow your request to fail and return an error. Otherwise, your application will be stuck calling the Hoover's API over and over again (which is not a good thing for you or Hoover's).

1.3 API Sample Code

Sample code which demonstrates how to consume the Hoover's API are available for .Net, Java and PHP.

.Net Sample (zip file)

Java Sample (zip file)

PHP Sample (zip file)

1.4 API Versioning

The Hoover's API contains the concept of versioning. Each major API release will create a new version; that is it will have a new endpoint. Versioning is intended to allow us to make changes to the WSDL that are not necessarily backwards compatible. This will allow us to better deliver new functionality as well as make improvements to existing functionality without breaking our existing customers. Be aware that due to WSDL changes future releases might potentially change the way the API is used.

Each version will have its own endpoint and documentation on the site. Please see the Previous Versions link on the left for older versions of the API.

Support will not be available for retired versions. We will support each version for a minimum of six months. Future forum posts should include the version number you are using for better support.

1.5 API Pre-Development Tools

If you would like to test out the Hoover's API without writing code to do so, use one of the freely available SOAP tools found at the sites below:

Remember, only send elements with valid values to the service. Certain tools generate every optional element with a placeholder (ex. "?") which is not a valid parameter.


2. Security

Please see the Security page for more informmation

3. Hoover's API Support

All Support Questions should be posted to the forum. Please indicate if you are using the Development or Production environment and the API Version. All questions and issues will be answered as quickly as possible. After hours posts will be handled the next business day. If you call Hoover's for a Development issue, you will be directed to the forum.

If you have an urgent Production issue, please call or email the address provided to you as part of your Production contract.