Hoover's API Version 4.0 - Person REST
Queries - REST - Person Information
IMPORTANT: All calls on this page require an Username , Password, and API key
New features are highlighted.
1 Advanced Person Search - /search/person/advanced
1.1 Overview
Returns search result of people based on varying different criteria
1.2 Input URI
This is a "POST" only call not requiring any query or path parameters other than listed.
HTTP Methods Accepted | Context Path | Headers | Sample URL |
POST | HooversAPI-40/rest | "username" and "password" HTTP headers are mandatory | http://hapi.hoovers.com/HooversAPI-40/rest/search/person/advanced?hit_offset=0&max_records=20&sort_direction=ascending&order_by=company_name |
1.3 Input Parameters
1.3.1 Path Parameters
There are no path parameters for this call. All search criteria are defined in the POST body.
1.3.2 Query Parameters
All query parameters are named in lowercase, with an underscore separator for multiple words.
Query Parameters | Sample | Type | Value(s) |
hit_offset={hit_offset} | hit_offset=0 | Number | Greater than or equal to 0 but less than or equal to 10,000. Default = 0. Paging support, the firstHit returned will be hitOffset + 1. hitOffset is zero-based. |
max_records={max_records} | max_records=20 | Number | Between 1-200. Default = 20 |
sort_direction={sort_direction} | sort_direction=ascending | String | Default sort direction is ascending. Other values for this search include:
|
order_by={order_by} | order_by=company_name | String | Default order by is relevance. Other values for this search include:
|
1.3.3 JSON Entity
Media type 'application/json'
Name | Type | Value(s) |
companySize: | Object | Top level JSON object used to wrap CompanySize input data. |
companySize: { employeesFrom: | Number | Total Employees Lower Bound |
companySize: { employeesTo: | Number | Total Employees Upper Bound |
companySize: { employeesGrowthFrom: | Number | Total Employees Growth Percentage Lower Bound |
companySize: { employeesGrowthTo: | Number | Total Employees Growth Percentage Upper Bound |
companySize: { employeesThisLocationFrom: | Number | Employees at this Location Lower Bound |
companySize: { employeesThisLocationTo: | Number | Employees at this Location Upper Bound |
companySize: { marketCapFrom: | Number | Market Cap ($ mil) Lower Bound |
companySize: { marketCapTo: | Number | Market Cap ($ mil) Upper Bound |
companySize: { salesFrom: | Number | Annual Sales ($ mil) Lower Bound |
companySize: { salesTo: | Number | Annual Sales ($ mil) Upper Bound |
companySize: { salesGrowthFrom: | Number | Annual Sales Growth (%) Lower Bound |
companySize: { salesGrowthTo: | Number | Annual Sales Growth (%) Upper Bound |
companyType: | Object | Top level JSON object used to wrap CompanyType input data. |
companyType: { locationType: [n,n...] | Array of Numbers | ID Value from GetAdvancedSearchLookups< |
companyType: { ownershipType: [n,n...] | Array of Numbers | Values are 1 (Public), 21 (Owned by a Public Company) or 0 (Non-Public) |
companyType: { subsidiaryStatus: [n,n...] | Array of Numbers | Subsidiary or Not a Subsidiary |
companyType: { franchiseStatus: [n,n...] | Array of boolean | Set the value to true for searching Franchise and false to Not a Franchise |
financialData: | Object | Top level JSON object used to wrap FinancialData input data. |
financialData: { advertisingExpenseFrom: | Number | Ad Expense ($ mil) Lower Bound. |
financialData: { advertisingExpenseTo: | Number | Ad Expense ($ mil) Upper Bound. |
financialData: { assetsFrom: | Number | Assets ($ mil) Lower Bound. |
financialData: { assetsTo: | Number | Assets ($ mil) Upper Bound. |
financialData: { filingDateFrom: | String | Filing Date Lower Bound. Format - YYYY-MM-DD |
financialData: { filingDateTo: | String | Filing Date Upper Bound. Format - YYYY-MM-DD |
financialData: { fiscalYearEnd: | Array of Numbers | Fiscal Year End Month |
financialData: { incomeFrom: | Number | Net Income ($ mil) Lower Bound. |
financialData: { incomeGrowthFrom: | Number | Net Income Growth (%) Lower Bound |
financialData: { incomeGrowthTo: | Number | Net Income Growth (%) Upper Bound |
financialData: { incomeTo: | Number | Net Income ($ mil) Upper Bound |
financialData: { marketingPreScreenScore: | Array of Strings | Values of either 'l' Low, 'm' Medium or 'h' High accepted. Allows for unique combinations of the preseeding values from 0 to 3. |
financialData: { offerFrom: | Number | US IPO Data - Offer Amount ($ mil.) Lower Bound |
financialData: { offerTo: | Number | US IPO Data - Offer Amount ($ mil.) Upper Bound |
financialData: { priceRangeFrom: | Number | US IPO Data - Price Range ($) Lower Bound |
financialData: { priceRangeTo: | Number | US IPO Data - Price Range ($) Upper Bound |
financialData: { researchExpenseFrom: | Number | R&D Expense ($ mil) Lower Bound |
financialData: { researchExpenseTo: | Number | R&D Expense ($ mil) Upper Bound |
financialData: { tradingDateFrom: | String | Trading Date Lower Bound. Format - YYYY-MM-DD |
financialData: { tradingDateTo: | String | Trading Date Upper Bound. Format - YYYY-MM-DD |
financialData: { underwriterId: | Array of Numbers | ID Value from GetAdvancedSearchLookups It searches only the lead underwriter for the given underwriterId. |
industry: | Object | Top level JSON object used to wrap Industry input data. |
industry: { hooversIndustryCode: | Array of Strings | ID Value from GetAdvancedSearchLookups |
industry: { primaryOnly: | Boolean | Primary Industry Only |
industry: { nAICS: | Array of Strings | Enter at least two digits per code. No CSV or Ranges can be specified |
industry: { nAICSRange:[ {from:,to:}... ] | Array of Objects | Enter one or more range object. Each range object must contain 'from' and a 'to' object. |
industry: { uSSIC: | Array of Strings | Enter at least two digits per code. No CSV or Ranges can be specified |
industry: { uSSICRange:[ {from:,to:}... ] | Array of Objects | Enter one or more range object. Each range object must contain 'from' and a 'to' object. |
industry: { uKSIC: | Array of Strings | Enter at least two digits per code. No CSV or Ranges can be specified |
industry: { uKSICRange:[ {from:,to:}... ] | Array of Objects | Enter one or more range object. Each range object must contain 'from' and a 'to' object. |
location: | Object | Top level JSON object used to wrap Location input data. |
location: { areacode: | Array of Strings | US/Canada Area Code |
location: { streetAddress: | Array of Strings | Street Address - e.g. 1700 Pennsylvania Ave. |
location: { county: | Array of county Objects | |
location: { county: { countyId: | String | ID Value from GetAdvancedSearchLookups |
location: { county: { state: | String | ID Value from GetAdvancedSearchLookups |
location: { county: { countryId: | String | ID Value from GetAdvancedSearchLookups |
location: { city: | Array of Strings | City - e.g. Madrid or New York |
location: { countryId: | Array of Numbers | ID Value from GetAdvancedSearchLookups |
location: { globalState: | Array of Strings | Global State/Province - e.g Queensland or NY |
location: { metropolitanId: | Number | US Metropolitan Area - ID Value from GetAdvancedSearchLookups |
location: { regionId: | Array of Numbers | World Region - ID Value from GetAdvancedSearchLookups |
location: { usStateCanadaProvince: | Array of Strings | US State/Canada Province |
location: { postalCode: | Array of Strings | Postal Code - e.g. 78701 or "SW1P 1JA" or "SW1" |
location: { usZipCodeRange: | Array of Objects | Top level JSON object used to wrap USZipCodeRange input data. |
location: { usZipCodeRange: { from: | Number | US ZIP Code Lower Bound |
location: { usZipCodeRange: { to: | Number | US ZIP Code Upper Bound |
location: { zipAreaSearch: | Object | Top level JSON object used to wrap ZipAreaSearch input data. |
location: { zipAreaSearch: { scale: | String | Units to search in: miles or kilometers - e.g. Find results within 50 miles of 78745 (up to a maximum radius of 100 miles or 160 km). Use only one 5-digit ZIP code. Requires zipareawithin and zipareazipcode.
|
location: { zipAreaSearch: { radius:: | Number | # of miles or kilometers to search within - e.g. Find results within 50 miles of 78745 (up to a maximum radius of 100 miles or 160 km). Use only one 5-digit ZIP code. Requires zipareawithin and zipareazipcode. |
location: { zipAreaSearch: { zipCode: | String | Zipcode to search within (78745 in the example) - e.g. Find results within 50 miles of 78745 (up to a maximum radius of 100 miles or 160 km). Use only one 5-digit ZIP code. Requires zipareawithin and zipareazipcode. |
location: { latLongSearch: | Object | Top level JSON object used to wrap LatLongSearch input data. |
location: { latLongSearch: { scale: | String | Units to search in: miles or kilometers
|
location: { latLongSearch: { radius: | Number | # of miles or kilometers to search within. Requires scale, latitude, and longitude. |
location: { latLongSearch: { latitude: | Number | latitude. Requires scale, radius, and longitude. |
location: { latLongSearch: { longitude: | Number | longitude. Requires scale, radius, and latitude. |
location: { allAny: | String | All or Any Matches on Location Criteria. Matching ALL means a company would have to match each type of criteria entered. Matching ANY means that a company could match any single type of criteria entered. Valid values All or Any
|
location: { ukCounty: | Array of Strings | A valid UK county name |
specialtyCriteria: | Object | Top level JSON object used to wrap SpecialtyCriteria input data. |
specialtyCriteria: { auditorId: | Array of Numbers | ID Value from GetAdvancedSearchLookups |
specialtyCriteria: { companyKeyword: | String | Company Keyword - e.g. laptops or China or acquired, merged, takeover |
specialtyCriteria: { duns: | Array of Numbers | DUNS Number The duns number must not be more than 9 digits |
specialtyCriteria: { exchangeId: | Array of Numbers | ID Value from GetAdvancedSearchLookups |
specialtyCriteria: { rankingId: | Array of Numbers | ID Value from GetAdvancedSearchLookups |
specialtyCriteria: { ukRegistration: | Array of Strings | UK Registration Number - e.g. 4044056 |
specialtyCriteria: { ukVat: | Array of Strings | UK Vat Number - e.g. 906565610 |
specialtyCriteria: { yearFoundingFrom: | Number | Year of Founding or Change in Control Lower Bound. Format - YYYY |
specialtyCriteria: { yearFoundingTo: | Number | Year of Founding or Change in Control Upper Bound. Format - YYYY |
specialtyCriteria: { ultimateParentDuns: | Array of Numbers | The ultimate parent DUNS number for a family of companies - eg. 060902413 or 884364530 |
specialtyCriteria: { primaryUrl: | Array of Strings | Primary URL |
specialtyCriteria: { companyName: | String | Company Name |
specialtyCriteria: { minorityOwned: | Boolean | Minority Owned Company (true/false) |
specialtyCriteria: { womenOwned: | Boolean | Women Owned Company (true/false) |
specialtyCriteria: { squareFootageFrom: | Number | Company square foot range from |
specialtyCriteria: { squareFootRangeTo: | Number | Company square foot range to |
specialtyCriteria: { ethnicity: | Array of Strings | Ethnicity of the company owner
|
specialtyCriteria: { legalStatus: | Array of Strings | Legal Status of the company
|
specialtyCriteria: { ownedOrRented: | String | Company resides in Owned or Rented Space
|
people: | Object | Top level JSON object used to wrap People input data. |
people: { lastName: | String | Person Last Name |
people: { firstName: | String | Person First Name |
people: { ageFrom: | Number | Person Age Lower Bound |
people: { ageTo: | Number | Person Age Upper Bound |
people: { bonusFrom: | Number | Person Bonus ($) Lower Bound |
people: { bonusTo: | Number | Person Bonus ($) Upper Bound |
people: { jobFunctionId: | Number | ID Value from GetAdvancedSearchLookups. Now named jobFunctionId instead of jobFunction |
people: { keywordsIn: | String | Keywords In - e.g. Title or Bio
|
people: { keywordSelect: | String: | Person Keyword - e.g. marketing or Harvard or ad sales |
people: { salaryFrom: | Number | Person Salary ($) Lower Bound |
people: { salaryTo: | Number | Person Salary ($) Upper Bound |
people: { totalPayFrom: | Number | Person Total Pay ($) Lower Bound |
people: { totalPayTo: | Number | Person Total Pay ($) Upper Bound |
1.3.4 Sample JSON for POST - contains ALL fields with invalid values, only use what you need
{
"companySize":{
"employeesFrom":n,
"employeesTo":n,
"employeesGrowthFrom":n,
"employeesGrowthTo":n,
"employeesThisLocationFrom":n,
"employeesThisLocationTo":n,
"marketCapFrom":n,
"marketCapTo":n,
"salesFrom":n,
"salesTo":n,
"salesGrowthFrom":n,
"salesGrowthTo":n,
},
"companyType":{
"locationType": [n,n...],
"ownershipType": [n,n...],
"subsidiaryStatus": [n,n...]
},
"financialData":{
"advertisingExpenseFrom":n,
"advertisingExpenseTo":n,
"assetsFrom":n,
"assetsTo":n,
"filingDateFrom":"",
"filingDateTo":"",
"fiscalYearEnd":[n,n,...],
"incomeFrom":n,
"incomeGrowthFrom":n,
"incomeGrowthTo":n,
"incomeTo":n,
"marketingPrescreenScore":["","",...],
"offerFrom":n,
"offerTo":n,
"priceRangeFrom":n,
"priceRangeTo":n,
"researchExpenseFrom":n,
"researchExpenseTo":n,
"tradingDateFrom":"",
"tradingDateTo":"",
"underwriterId":[n,n,...],
},
"industry":{
"hooversIndustryCode":["","",...],
"primaryOnly":boolean,
"nAICS":["","",...],
"nAICSRange":[{from:"",to:""}... ],
"uSSIC":["","",...],
"uSSICRange":[{from:"",to:""}... ],
"uKSIC":["","",...],
"uKSICRange":[{from:"",to:""}... ]
},
"location":{
"areacode":["","",...],
"streetAddress":["","",...],
"county":[
{
"countyId":n,
"state":"",
"countryId":n
},
...
],
"city":["","",...],
"countryId":[n,n,...],
"globalState":["","",...],
"metropolitanId":[n,n,...],
"regionId":[n,n,...],
"usStateCanadaProvince":["","",...],
"postalCode":["","",...],
"usZipCodeRange":[{"from":n,"to":n},...],
"zipAreaSearch":{
"scale":"",
"radius":n,
"zipCode":""
},
"latLongSearch":{
"scale":"",
"radius":n,
"latitude":n,
"longitude":n
},
"allAny":"",
"ukCounty":["","",...],
},
"specialtyCriteria":{
"auditorId":[n,n,...],
"companyKeyword":"",
"duns":[n,n,...],
"exchangeId":[n,n,...],
"rankingId":[n,n,...],
"ukRegistration":["","",...],
"ukVat":["","",...],
"yearFoundingFrom":n,
"yearFoundingTo":n,
"ultimateParentDuns":[n,n,...],
"primaryUrl":["","",...],
"companyName":"",
"minorityOwned":boolean,
"womenOwned":boolean,
"squareFootageFrom":n,
"squareFootRangeTo":n,
"ethnicity":["","",...],
"legalStatus":["","",...],
"ownedOrRented":""
},
"people":{
"ageFrom":n,
"ageTo":n,
"bonusFrom":n,
"bonusTo":n,
"jobFunctionId":[n,n,...],
"keywordsIn":["","",...],
"keywordSelect":"",
"salaryFrom":n,
"salaryTo":n,
"totalPayFrom":n,
"totalPayTo":n
},
"searchNavigation":{
"employeeSearchNavigation":{
"employeeSearchNavigationValue":["","",...]
},
"ownershipTypeSearchNavigation":{
"ownershipTypeSearchNavigationValue":["","",...]
},
"locationTypeSearchNavigation":{
"locationTypeSearchNavigationValue":["","",...]
},
"salesSearchNavigation":{
"salesSearchNavigationValue":["","",...]
},
"locationSearchNavigation":{
"countryNavigation":{
"countryNavigationValue":["","",...],
"stateNavigation":{
"stateNavigationValue":["","",...],
"cityNavigation":{
"cityNavigationValue":["","",...]
}
}
}
},
"industrySearchNavigation":{
"industrySearchNavigationValue":["","",...],
"ussicSearchNavigationValue":["","",...],
"naicsSearchNavigationValue":["","",...]
}
}
}
1.4 Output Parameters
Media type 'application/json; charset=UTF-8;'
Name | Type | Value(s) |
people: | Object | |
people: { firstHit | Number | First Hit |
people: { lastHit | Number | Last Hit |
people: { hits | Number | Total Number of Hits in this Response |
people: { totalHits | Number | Aggregate Total Number of Hits. This is the total number of results the search returned. |
people: { hit: | Object | |
people: { hit: { hitNumber | Number | Hit Number |
people: { hit: { coOfficialResults: | Object | |
people: { hit: { coOfficialResults: { coOfficialId: | Number | Hoovers Official ID |
people: { hit: { coOfficialResults: { companyId: | Number | Hoovers Company ID |
people: { hit: { coOfficialResults: { duns: | Number | DUNS |
people: { hit: { coOfficialResults: { firstName: | String | Person First Name |
people: { hit: { coOfficialResults: { lastName: | String | Person Last Name |
people: { hit: { coOfficialResults: { middleName: | String | Person Middle Name |
people: { hit: { coOfficialResults: { suffix: | String | Person Suffix |
people: { hit: { coOfficialResults: { title: | String | Person Title |
people: { hit: { coOfficialResults: { companyName: | String | Company Name |
people: { hit: { coOfficialResults: { connectMail: | Object | Wrapper object for ConnectMail indicators |
people: { hit: { coOfficialResults: { connectMail: { connectMailNameSource: | Boolean | Indicates if official's name is a ConnectMail contact |
people: { hit: { coOfficialResults: { connectMail: { connectMailEmailSource | Boolean | Indicates if official's email is a ConnectMail contact |
people: { hit: { coOfficialResults: { connectMail: { connectMailPhoneSource | Boolean | Indicates if official's phone number is a ConnectMail contact |
2 Get Person Detail - /person/{unique_company_id}/{co_official_id}
2.1 Overview
Returns all the person details for a given Hoover's Company ID or DUNS and co-Official Id
2.2 Input URI
This is a "Get" only call.
HTTP methods accepted | Context path | HTTP Headers | Sample URL |
GET | HooversAPI-trunk/rest | Username and Password headers are mandatory | http://hapi.hoovers.com/Hoovers-API-40/rest/person/13193000000000/411?view=full&connect_mail=true&convert_currency_to=usd |
2.3 Input Path and Query Parameters
[application/json] - Required fields are indicated with .
The query and path parameters as listed below.
Path Parameters | Sample Path Parameters |
person/{unique_company_id}/{co_official_id} | person/13193000000000/411 |
Query Parameters | Sample Query Parameters |
view={view} | view=full (This value is case sensitive) |
connect_mail={connect_mail} | connect_mail=true (This value must be a boolean. default to false) |
convert_currency_to={convert_currency_to} | convert_currency_to=usd (The possible values are usd, gdp, cad, eur,jpy and sek. This value is case sensitive) |
2.4 Output Parameters
Field Name | Type | Value(s) |
coOfficial: | JSON Object | JSON Object wrapping all the offical details |
coOfficial:{ companyId: | Number | Hoovers Company ID |
coOfficial:{ duns: | Number | DUNS number |
coOfficial:{ primaryCompanyPhone: | String | Primary phone number for the company |
coOfficial:{ coOfficialId: | Number | Hoovers Official ID |
coOfficial:{ currencyConvertedTo: | String | Currency in which the latest salary is returned |
coOfficial:{ biography: | String | Biographic Information |
coOfficial:{ biographySource: | String | Biography Source Name |
coOfficial:{ contact: | JSON Object | JSON Object wrapping all the Official Contact Information |
coOfficial:contact{ phoneNumber | String | Contact phone number |
coOfficial:contact{ email | String | Contact email address |
coOfficial:{ latestPosition: | JSON Object | JSON Object wrapping most recent position information |
coOfficial:latestPosition:{ title: | String | Person Title |
coOfficial:latestPosition:{ titleText: | String | Latest position title text |
coOfficial:latestPosition:{ startYear: | String | Latest position start year |
coOfficial:latestPosition:{ endYear: | String | Latest position end year |
coOfficial:{ positionHistory: | JSON Object | JSON object wrapping all the position elements (position history for the official) |
coOfficial:position:{ title: | String | Person Title |
coOfficial:position:{ titleText: | String | Latest position title text |
coOfficial:position:{ startYear: | String | Position start year |
coOfficial:position:{ endYear: | String | Position end year |
coOfficial:{ latestSalary: | JSON Object | JSON Object wrapping most recent salary information |
coOfficial:latestSalary:{ year: | Decimal | Latest salary year |
coOfficial:latestSalary:{ salary: | Decimal | Salary for the year, excluding bonus |
coOfficial:latestSalary:{ totalSalary: | Decimal | Total compensation for the year, including any bonus or other compensation |
coOfficial:latestSalary:{ bonus: | Decimal | Bonus for the year |
coOfficial:{ salaryHistory | JSON Object | JSON object containing the salary elements (salary history for the official) |
coOfficial:salaryHistory:{ salaries[] | List | List of all salary elements (salary history for the official) |
coOfficial:salaryHistory:salaries:{ year: | Decimal | Salary Year |
coOfficial:salaryHistory:salaries:{ salary: | Decimal | Salary for the year excluding bonus |
coOfficial:salaryHistory:salaries:{ totalSalary: | Decimal | Total compensation including bonus |
coOfficial:salaryHistory:salaries:{ bonus: | Decimal | Bonus for the year |
coOfficial:{ person: | JSON Object | Person Full Name |
coOfficial:person:{ fullName: | String | Person Full Name |
coOfficial:person:{ lastName: | String | Person Last Name |
coOfficial:person:{ firstName: | String | Person First Name |
coOfficial:person:{ middleName: | String | Person Middle Name |
coOfficial:person:{ suffix: | String | Person Suffix |
coOfficial:person:{ prefix: | String | Person Prefix |
coOfficial:person:{ age: | Number | Person Age |
coOfficial:{ connectMail: | JSON Object | JSON Element wrapping all the ConnectMail indicators |
coOfficial:connectMail:{ connectMailNameSource: | Boolean | Indicates if official's name is a ConnectMail contact |
coOfficial:connectMail:{ connectMailEmailSource: | Boolean | Indicates if official's email is a ConnectMail contact |
coOfficial:connectMail:{ connectMailPhoneSource: | Boolean | Indicates if official's phone number is a ConnectMail contact |
coOfficial:{ nonMarketableCompany | Object | This object contains child tags representing the reasons for which this company is taged as non-marketable. |
coOfficial:{ nonMarketableCompany{ reasons | String value | The possible reasons are
|
- Versions
- Version 3.0
- Version 3.1
- Version 3.2
- Version 3.3
- Version 3.4
- Version 4.0
- Version 4.0 Documentation
- Overview
- Security
- SOAP Services
- REST Services
- Queries - Company Information
- Queries - Person Information
- Queries - Person Information