Skip to main content

Contact Search

Coming soon

The v2 MCP API is in preview and not yet generally available. These pages document its tools and request/response shapes; live data access is limited to enrolled organizations until v2 is released.

Discover PEOPLE (contacts) at a company by job title, seniority, and location — returns a list of individuals (name, title, seniority, LinkedIn, org), not company facts. Use this when you need to find contacts at an account (e.g. 'who are the VPs of Marketing at Salesforce') to identify prospects to reach out to. Do NOT use this when: you already know the specific person and want their email/phone — use contact_enrich; you want company-level firmographics (revenue, size, industry) not people — 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, so batch all filters into one call. The ONLY filters are: personTitles, personSeniorities, personLocations, organizationLocations, organizationNumEmployeesRanges, contactEmailStatus. There is NO free-text/keyword search — express intent via personTitles and personSeniorities. Params like q, keywords, titles, or seniority are not real and are silently ignored; confirm a filter worked by comparing totalResults with and without it. LARGE COMPANIES: for big accounts (tens of thousands of contacts) an unfiltered search returns an unranked default page — always pass personTitles and/or personSeniorities. 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 variations; max 2 searches per request (initial + optional pagination). Then use contact_enrich for email/phone of the best matches.

Parameters​

NameTypeRequiredDefaultDescription
companyDomainstring❌ No-Company domain to search (e.g., "salesforce.com"). Preferred over companyName for accuracy. Either companyDomain or companyName is required. Protocol prefixes (http://, https://), leading www., and trailing paths/queries/fragments are accepted and stripped automatically; case is normalized.
companyNamestring❌ No-Company name for fuzzy match (e.g., "Salesforce") when the domain is unknown. Prefer companyDomain for accuracy. Provide one of companyDomain or companyName (domain wins if both are given).
personTitlesarray❌ No-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.
personSenioritiesarray❌ No-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.
personLocationsarray❌ No-Filter contacts by the PERSON's location, "City/State, Country" style (e.g., ["California, US", "New York, US"]).
organizationLocationsarray❌ No-Filter by the company's HQ location (e.g., ["San Francisco, US"]) — distinct from personLocations, which filters the individual.
organizationNumEmployeesRangesarray❌ No-Company employee-count ranges as "min,max" strings (e.g., ["1,10", "11,50", "51,200"]).
contactEmailStatusarray❌ No-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.
pageinteger❌ No1Page number for pagination (default: 1)
perPageinteger❌ No25Results per page (default: 25, max: 100)
providerstring❌ NoautoContact 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​

  • apollo
  • 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": {
    "companyDomain": "salesforce.com",
    "personTitles": [
      "VP Marketing",
      "CMO",
      "Head of Marketing"
    ],
    "perPage": 25
  }
}

Senior IT decision-makers with verified email

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

Contacts by company name in a region

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

contact_enrich, company_firmographic, search_companies