Hoover's API Version 3.0 - Overview

New Production Version - Hoover's API Version 3.0

Hoover's has launched version 3.0 of the Hoover's API, providing customers with significantly more company, people and international records. With this release, Hoover's doubled the number of company records from 30 million to 60 million and increased the number of people records from 44 million to 69 million. In addition to these new features, Hoover's has improved the performance of the API with a new, more scalable architecture.

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

New features are highlighted.

Changes to Documentation

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

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.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 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.

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 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.

Hoover's will support 3 versions on Production and 3 on Development - the versions will be staggered forward on Development after the third released version - e.g. Production versions supported will be 3,2,1 while Development versions supported will be 4,3,2.

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. Authentication

Every user is provided with an API Key that will be used as part of each request to the Hoover's service. This key is specific to an environment. Therefore, your Hoover's API Development key will not work for Production and vice versa. Make sure you are using the correct key/environment pair.

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, you will be directed to the forum.

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