| Person Search||http://partnerapi.zoominfo.com/partnerapi/person/search?|
The next section provides more information about the basic parts of the URL that are shared by all of the ZoomInfo Partner API queries.
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.
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:
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|
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:
The query is run on the following date:
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
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:
Thus, the URL would look like this
With the above encrypted key, the URL would look like this
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).
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.)
|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:||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).
The following example shows a Person Search query. The input parameters include:
The query is run on the following date:
The key before encryption would look like this
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:
Thus, the URL would look like this:
Using the above encrypted key, the URL would look like this:
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
Contact our award-winning customer care team.