Contact Search

contact_search — find people / search contacts / prospect contacts at a company by title, seniority, or location. Returns a list of individuals (name, title, seniority, LinkedIn, org), not company facts. Do NOT use when: you already know the specific person and want their email/phone — use contact_enrich; you want company-level firmographics — use company_firmographic. PROVIDER DEPENDENCY: results come from an EXTERNAL contact provider (Apollo or ZoomInfo) auto-selected from your org's configured integrations (NOT the HG Insights data API). Availability is org-specific (commonly Apollo only); with none configured the tool is unavailable. Leave provider on 'auto' (default). Costs 2 credits per call regardless of result count — batch all filters into one call. ONLY filters: personTitles · personSeniorities · personLocations · organizationLocations · organizationNumEmployeesRanges · contactEmailStatus. NO free-text/keyword search — express intent via personTitles and personSeniorities. Params like q, keywords, or seniority are not real and are silently ignored; confirm a filter worked by comparing totalResults with and without it. LARGE COMPANIES: always pass personTitles and/or personSeniorities — an unfiltered search on a big account returns an unranked default page. RULES: combine ALL title variations into ONE call via arrays (never one call per title); on 0 results STOP and report 'no matches found' instead of retrying; max 2 searches per request. Then use contact_enrich for email/phone of the best matches.

Credits

2 — Per call. See the full credit table for how AI Credits work.

Parameters

Name	Type	Default	Description
`company_domain`	string	-	Company domain to search (e.g., "salesforce.com"). Preferred over company_name for accuracy. Either company_domain or company_name is required. Protocol prefixes (http://, https://), leading www., and trailing paths/queries/fragments are accepted and stripped automatically; case is normalized.
`company_name`	string	-	Company name for fuzzy match (e.g., "Salesforce") when the domain is unknown. Prefer company_domain for accuracy. Provide one of company_domain or company_name (domain wins if both are given).
`personTitles`	array	-	Job titles to match, as an array — combine ALL variations in one call (e.g., ["VP Marketing", "CMO", "Head of Marketing"]). This is the primary way to express search intent; there is no free-text/keyword param.
`personSeniorities`	array	-	Seniority levels to match (array). One or more of: owner, founder, c_suite, partner, vp, head, director, manager, senior, entry, intern. Combine with personTitles to narrow large accounts.
`personLocations`	array	-	Filter contacts by the PERSON's location, "City/State, Country" style (e.g., ["California, US", "New York, US"]).
`organizationLocations`	array	-	Filter by the company's HQ location (e.g., ["San Francisco, US"]) — distinct from personLocations, which filters the individual.
`organizationNumEmployeesRanges`	array	-	Company employee-count ranges as "min,max" strings (e.g., ["1,10", "11,50", "51,200"]).
`contactEmailStatus`	array	-	Filter by email deliverability status (array): verified, unverified, likely_to_engage, unavailable. Not all providers support this; when the tool can detect it, ignored/unsupported params are listed in metadata.warnings, which is omitted when there is nothing to report.
`page`	integer	`1`	Page number for pagination (default: 1)
`perPage`	integer	`25`	Results per page (default: 25, max: 100)
`provider`	string	`auto`	Contact data provider. Prefer "auto" (default), which selects an available provider. "apollo" or "zoominfo" target a specific provider, but requesting one your org has not configured returns a hard error rather than falling back — check availableProviders in the response.

Required Integrations

This tool is only available when your organization has the following integrations configured in the HG Insights Integrations settings:

Apollo.io (apollo)
ZoomInfo (zoominfo)

Use Cases

Find the VPs and Heads of Marketing at a target account to build an outreach list
Discover IT / security decision-makers (director+ seniority) at a company before a sales call
List C-suite contacts at a company, filtered to verified email status for a campaign
Identify prospects at a company within a specific region (e.g. California, US)
Pull a page of contacts at a large account, narrowed by title and seniority so results are ranked usefully

Example Usage

Marketing leaders at a company by domain

{
  "tool": "contact_search",
  "arguments": {
    "company_domain": "salesforce.com",
    "personTitles": [
      "VP Marketing",
      "CMO",
      "Head of Marketing"
    ],
    "perPage": 25
  }
}

Senior IT decision-makers with verified email

{
  "tool": "contact_search",
  "arguments": {
    "company_domain": "cisco.com",
    "personSeniorities": [
      "c_suite",
      "vp",
      "director"
    ],
    "contactEmailStatus": [
      "verified"
    ]
  }
}

Contacts by company name in a region

{
  "tool": "contact_search",
  "arguments": {
    "company_name": "Adobe",
    "personSeniorities": [
      "director",
      "manager"
    ],
    "personLocations": [
      "California, US"
    ]
  }
}

Response Format

Field	Type	Description
`contacts`	array	List of contacts found
`contacts[].id`	string	Contact ID (use for enrichment with the same provider)
`contacts[].firstName`	string \| null	First name
`contacts[].lastName`	string \| null	Last name
`contacts[].name`	string \| null	Full name
`contacts[].title`	string \| null	Job title
`contacts[].seniority`	string \| null	Seniority level
`contacts[].linkedinUrl`	string \| null	LinkedIn profile URL
`contacts[].organization`	object	Organization information
`contacts[].organization.id`	string	Organization ID
`contacts[].organization.name`	string	Company name
`contacts[].organization.domain`	string \| null	Company domain
`contacts[].organization.industry`	string \| null	Industry
`contacts[].organization.employeeCount`	number \| null	Employee count
`contacts[].organization.location`	string \| null	Company location
`contacts[].city`	string \| null	City
`contacts[].state`	string \| null	State/Region
`contacts[].country`	string \| null	Country
`pagination`	object	Pagination information
`pagination.page`	number	Current page number
`pagination.perPage`	number	Results per page
`pagination.totalResults`	number	Total number of matching contacts
`pagination.hasMore`	boolean	Whether more results are available
`metadata`	object	Search metadata
`metadata.searchCriteria`	object	The search criteria used
`metadata.tip`	string	Usage tip
`metadata.provider`	string	Contact data provider used (e.g., apollo, zoominfo)
`metadata.usedProvider`	string	Which provider fulfilled this request
`metadata.availableProviders`	array	Providers configured for the organization
`metadata.warnings`	array	Warnings about ignored parameters

contact_enrich, company_firmographic, search_companies

Credits​

Parameters​

Required Integrations​

Use Cases​

Example Usage​

Response Format​

Related Tools​