Contact Search

Discover PEOPLE (contacts) at a company by job title, seniority, and location — returns a list of individuals, not company facts. Use this to find contacts at an account (e.g. 'who are the VPs of Marketing at Salesforce', 'find IT decision-makers at Cisco') and 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) rather than 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). Coverage and fields depend on which provider is configured; with none configured this tool is unavailable. Returns basic contact info (name, title, seniority, LinkedIn, org). Costs 2 credits per call regardless of result count — batch every filter into ONE call. Filter only via the declared parameters: personTitles, personSeniorities, personLocations, organizationLocations, organizationNumEmployeesRanges, contactEmailStatus. There is NO free-text or keyword search — express intent through personTitles and personSeniorities; unknown params are silently ignored (check metadata.warnings if filters seem to have no effect). LARGE COMPANIES: for big accounts an unfiltered search returns a default page that is NOT meaningfully ranked — always pass personTitles and/or personSeniorities. If a search returns 0 results, STOP and report 'no matches found' — do not retry with different title variations. Limit yourself to 2 searches per request (initial + optional pagination). Use contact_enrich to get email/phone for the best matches.

Credits

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

Parameters

Name	Type	Default	Description
companyDomain	string	-	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.
companyName	string	-	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).
personTitles	array	-	Job titles to match, as an array — combine ALL variations into this ONE array (e.g., ["VP Marketing", "CMO", "Head of Marketing"]) rather than making separate calls per title. This is the primary way to express search intent; there is no free-text/keyword param. Do NOT pass q, keywords, or titles — those are not real parameters and are silently ignored.
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. Do NOT pass a "seniority" param — only personSeniorities is honored; anything else is silently ignored.
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 (see metadata.warnings).
page	integer	1	Page number for pagination (default: 1)
perPage	integer	25	Results per page (default: 25, max: 100)
provider	string	auto	Which external contact provider to use: "auto" (default — picks a configured provider), "apollo", or "zoominfo". A named provider must be configured for your org or the call fails.

Required Integrations

This tool is only available when your organization has the following integrations configured in the Phoenix 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": {
    "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"
    ]
  }
}

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

Example response

{
  "contacts": [
    {
      "id": "aaaaaaaaaaaaaaaaaaaaaaaa",
      "firstName": "Jordan",
      "lastName": "Rivera",
      "name": "Jordan Rivera",
      "title": "Vice President Marketing",
      "seniority": "vp",
      "linkedinUrl": "http://www.linkedin.com/in/example-jordan-rivera",
      "organization": {
        "id": "bbbbbbbbbbbbbbbbbbbbbbbb",
        "name": "Salesforce",
        "domain": "salesforce.com",
        "location": ""
      },
      "city": "New York",
      "state": "New York",
      "country": "United States"
    }
  ],
  "pagination": {
    "page": 1,
    "perPage": 2,
    "totalResults": 65,
    "hasMore": true
  },
  "metadata": {
    "searchCriteria": {
      "companyDomain": "salesforce.com",
      "personTitles": [
        "VP Marketing"
      ],
      "personSeniorities": [
        "vp"
      ],
      "page": 1,
      "perPage": 2
    },
    "tip": "Use contact_enrich with the contact ID to reveal email/phone for the best matches.",
    "provider": "apollo"
  }
}

Related Tools

contact_enrich, company_firmographic, search_companies