MD5 Security Key Authentication

The ZoomInfo Partner API consists of the following web services with associated URLs using MD5 authentication to access ZoomInfo data.

API
URL
Person Search
http://partnerapi.zoominfo.com/partnerapi/person/search?
Person Detail
http://partnerapi.zoominfo.com/partnerapi/person/detail?
Person Match
http://partnerapi.zoominfo.com/partnerapi/person/match?
Company Search
http://partnerapi.zoominfo.com/partnerapi/company/search?
Company Detail
http://partnerapi.zoominfo.com/partnerapi/compan/detail?
Company Match
http://partnerapi.zoominfo.com/partnerapi/compan/match?
Usage Query
http://partnerapi.zoominfo.com/partnerapi/usage/query?

The next section provides more information about the basic parts of the URL that are shared by all of the ZoomInfo Partner API queries.

API Requests and URL Construction

Since Partner API requests are made via HTTP, there are several different parts to URL construction. Each part needs to be constructed correctly in order for the search to work properly. For example, in a Company Search, you can form the URL in 3 parts. The first portion of the URL contains the partner API host name and root context followed by the query request type as shown below:

The second part of the URL contains the search parameters. For example, for a Company Search looking for ZoomInfo in Massachusetts, you would set up the next part of the URL like this:

Notice that the name of the state is spelled out in full. Two-letter state names are not supported.

The third part of the URL contains the authentication. Enter your Partner Code (or Partner Name) supplied to you by ZoomInfo as ;pc=PartnerCode. Also, you must include the encryption key which needs to be generated with parts of your search criteria, a Partner Password, and the current date. Then the key is encrypted using MD5.

Note: Substitute your Partner Code (partner name) into the URL and your Partner Password into the Key.

The next section, MD5 Security Key and Encryption, provides more information on generating encrypted keys.

MD5 Security Key and Encryption

When constructing a ZoomInfo API query, an important part of the associated URL is the MD5 security key. The key contains information specific to the ZoomInfo API request that you are making, your partner password, and the current date. The MD5 security key has the following general form:

The MD5 security key contains the following concatenated elements in order:

  • The first 2 characters of each parameter value with a yes in the Key column in the order listed in the Input Parameters Table for the given request. Note: this could also be numerals if the input parameter is a number (ex. Industry Classification number).
  • Your Partner Password
  • Today's Date

Date Structure in Keys

In structuring the Key, dates are set up in a specific order: first day, then month, then year (with no padded zeros). The date that you use is Today's Date. Be sure to use the correct order in entering the date. Here are a few example key dates.

Date
Day / Month / Year
Key Date
July 4, 2014
4 7 2014
472014
August 30, 2015
30 8 2015
3082015
November 3, 2016
3 11 2016
3112016
December 25, 2017
25 12 2017
25122017

Encrypting the Key

The entire MD5 security key must be encoded using the MD5 (Message Digest 5) encryption algorithm in UTF-8 format before issuing the query to ZoomInfo. MD5 is a simple, fast, one-way encryption algorithm, developed by RSA, which you can implement in any development language. Various MD5 encryption tools are available on the web.

The following example shows a Company Search query. The input parameters include:

  • zoominfo for companyName
  • Massachusetts for state

The query is run on the following date:

  • July 30, 2014

The key contains: the first 2 characters of the search criteria, the first 2 characters of the next search criteria, a partner password, then the date. The key before encryption would look like this

zoMaPassword3072014

where zo is the 1st 2 characters in zoominfo and Ma is the 1st 2 characters in Massachusetts. For Password, enter your Partner Password. The date is formed as 30 7 2014 [first day, then month, then year (with no padded zeros) ].

After MD5 encryption, the key would look like this:

e93dad4629edc678eaf80bae551b812b

Thus, the URL would look like this

http://partnerapi.zoominfo.com/partnerapi/company/search?companyName=zoominfo&state=Massachusetts&pc=PartnerCode&key=EncryptedKey

With the above encrypted key, the URL would look like this

http://partnerapi.zoominfo.com/partnerapi/company/search?companyName=zoominfo&state=Massachusetts&pc=PartnerCode&key=e93dad4629edc678eaf80bae551b812b

Note: Since your partner password is entered into the Key (before encryption), each key is for individual use only and the above example will not work on your system until you create your own key.

The next section, Input Parameters, provides more information about which characters or digits get included in the key.

Note: Capitalization matters in regard to key generation. If you capitalize the first 2 characters of the input parameter, then you must capitalize the corresponding letter in the key (ex. zo for zoominfo & Mafor Massachusetts).

Input Parameters Used in Key Generation

Each of the Partner APIs is described in detail in their own sections in this document. Below you will find a subset of Input Parameters for the Person Search API. Notice in the table there is a heading marked Key. All the parameters of this subset are marked Yes in the Key Column to designate that they are indeed used in key generation. (Note, in the full parameter table, many parameters are marked No.)

Group
Parameter
Description
Key
Name
firstName
First name of the person being searched for
yes
middleInitial
Middle initial of the person being searched for
yes
lastName
Last name of the person being searched for
yes
Title
personTitle
Title of the person being searched for (ex. VP of Sales)
yes
TitleSeniority
Restricts searches to people in one or more of the following: Board Members, Executives, Mid Management, Non Management, C_EXECUTIVES, VP_EXECUTIVES, DIRECTOR, MANAGER. Accepts multiple values by passing a comma-separated list.
yes
TitleClassification
Restricts searches to people with a title related to the title classification specified. Accepts multiple values by passing a comma-separated list.
yes
Company ID
companyId
Searches for people who work or have worked for the specific company which has this unique ZoomInfo company ID.
yes
Company Name
companyName
Searches for people who work or have worked for a specific company.
yes
Industry / Keyword
companyDesc
Search for people whose companies contain the given description.
yes
IndustryClassification
A hierarchy of industries. See list of industry codes here. Searches for people within these industries. Accepts multiple values by passing a comma-separated list.
yes
IndustryKeywords
Search for people in the industry related to the given search term. Accepts multiple values by passing a comma-separated list
yes
Geography
State
Searches for people in one or more US states. Ex. Pennsylvania. Accepts multiple values by passing a comma-separated list. Note: State abbreviations are not yet supported.
yes
MetroRegion
Searches for people in one or more metro regions. Ex. Detroit, MI. Accepts multiple values by passing a comma-separated list.
yes
Country
Searches for people in one or more countries. Accepts multiple values by passing a comma-separated list. Example: Country.USA,Country.Sweden,Country.Brazil
yes
ZipCode
Restricts search to an area determined by zip code. Use this parameter in combination with RadiusMiles to increase the size of the area to search.
yes
RadiusMiles
Used in conjunction with ZipCode, designates how far in miles from zip code to include in search.
yes
location
Accepts any address, city, state, country, or zipcode and searches for people at that location.
yes
locationSearchType
Used in conjunction with other Geography group parameters to allow a person search request to find people related to the location they specify in the following ways:
  • PersonOrHQ-Finds people who are either located at the specified location or who's Company HQ is located at the specified location
  • PersonAndHQ- Finds people who are BOTH located at the specified location AND who's Company HQ is located at the specified location
  • Person-Finds people located at the specified location
  • HQ- Finds people who's Company HQ is located at the specified location
yes
Company Size
RevenueClassificationMin
Minimum revenue dollar amount of a company. Use this parameter with RevenueClassificationMax to set a range.
yes
RevenueClassificationMax
Maximum revenue dollar amount of a company. Use this parameter with RevenueClassificationMin to set a range.
yes
RevenueClassification
Accepts a comma separated list of revenue ranges for a company. Cannot be used with RevenueClassificationMin and/or RevenueClassificationMax.

yes
EmployeeSizeClassificationMin
Minimum employee size of a company. Use this parameter with EmployeeSizeClassificationMax to set a range.
yes
EmployeeSizeClassificationMax
Maximum employee size of a company. Use this parameter with EmployeeSizeClassificationMin to set a range.
yes
EmployeeSizeClassification
Accepts a comma separated list of employee size ranges for a company. Cannot be used with EmployeeSizeClassificationMin and/or EmployeeSizeClassificationMax.



yes
IsPublic
Restricts searches to people in just publicly traded or just privately held companies. Leave blank to search for people in public and private companies.
yes
CompanyRanking
Restricts searches to a company in a specific ranked list ex. Fortune 500. Accepts multiple values by passing a comma-separated list.
yes
Education
school
Searches for people who attended a specific school or university.
yes
degree
Searches for people who have received a specific type of degree (Ex. bachelors, masters, etc).
yes
Diversity
gender
Searches for people based on their gender.
yes
Source Website
companyDomainName
Restricts searches to those people who are found on a specific website.
yes
Credentials
titleCertification
Searches for people who hold a certain credential or certification (ex. Registered Nurse). This input parameter searches both current and past titles for the specified credential or certification.
yes
Date Filters
companyPastOrPresent
Designates the type of company the search criteria should be applied to: the person's present and past company, present company only, or past company only.
yes
ValidDateMonthDist
Searches for people whose profile has been updated within a certain time period.
yes
Contact Filter
ContactRequirements
Searches for people who have a certain type of contact information.
yes
Email
EmailAddress
Searches for people based on email address.
yes

The order in which the parameter appears in the table is the order in which you would use them. In key construction, you include the first 2 characters of each parameter value that you include in the search.

If the input parameter being used has only one character, then that single character can be used in the key (Ex. J for middleInitial).

Example – Person Search with Key Generation

The following example shows a Person Search query. The input parameters include:

  • Vice President for PersonTitle
  • 200714 for IndustryClassification (Search Engines & Internet Portals)
  • California for State

The query is run on the following date:

  • July 30, 2014

The key before encryption would look like this

Vi20CaPassword3072014

where Vi is the first 2 characters in Vice President, 20 is the first 2 digits of 200714, and Ca is the first 2 characters in California. For Password, enter your Partner Password. The date is formed as 30 72014 [day, month, year].

After MD5 encryption, the key would look like this:

37388ac2ee37169088980be348f50409

Thus, the URL would look like this:

http://partnerapi.zoominfo.com/partnerapi/person/search?PersonTitle=VicePresident&IndustryClassification=200714&state=California&pc=PartnerCode&key=EncryptedKey

Using the above encrypted key, the URL would look like this:

http://partnerapi.zoominfo.com/partnerapi/person/search?PersonTitle=VicePresident&IndustryClassification=200714&state=California&pc=PartnerCode&key=37388ac2ee37169088980be348f50409

Note: Since your partner password is entered into the Key (before encryption), each key is for individual use only and the above example will not work on your system until you create your own key

Was this article helpful?

Can’t find what you’re looking for?

Contact our award-winning customer care team.