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:
  • ascending
  • descending
order_by={order_by} order_by=company_name String Default order by is relevance. Other values for this search include:
  • company_name
  • company_type
  • country_name
  • city_name
  • state_name
  • phone_number
  • fax_number
  • sales_growth_12_mon
  • total_assets
  • sales_us
  • employees_total
  • employees_here
  • fiscal_year_end_month
  • merket_cap
  • net_income_growth_12_mon
  • employee_growth_12_mon
  • roe
  • roa
  • earnings_compairson
  • book_value_comparison
  • net_income
  • person_first_name
  • person_last_name
  • person_title

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.
  • miles
  • kilometers
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
  • miles
  • kilometers
Requires radius, latitude, and longitude.
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
  • all
  • 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
  • asn
  • blk
  • hsp
  • isu
  • nat
  • unk
specialtyCriteria: { legalStatus: Array of Strings Legal Status of the company
  • corporation
  • partnership
  • proprietorship
  • national_government_entity
  • regional_local_government_entity
  • joint_venture
  • non_profit_organization
  • co_operative_mutual_organization
  • foreign_company
specialtyCriteria: { ownedOrRented: String Company resides in Owned or Rented Space
  • owned
  • rented
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
  • title
  • 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
  • Out of business
  • Invalid address
  • Key data missing/needing revision
  • Donot market to