Skip to main content

Contact Search

Search for contacts at a company by title, seniority, and location.

Important: Free Tool - No Credits Used​

This tool does not consume credits. Use it freely to search and identify contacts before enriching the best matches with contact_enrich.

Parameters​

NameTypeRequiredDefaultDescription
companyDomainstringNosalesforce.comCompany domain to search (preferred over companyName)
companyNamestringNo-Company name for fuzzy search
personTitlesstring[]No-Job titles to filter by (e.g., ["VP Marketing", "CMO"])
personSenioritiesstring[]No-Seniority levels (owner, founder, c_suite, partner, vp, head, director, manager, senior, entry, intern)
personLocationsstring[]No-Person locations (e.g., ["California, US"])
organizationLocationsstring[]No-Filter by company HQ location
organizationNumEmployeesRangesstring[]No-Employee count ranges (e.g., ["1,10", "11,50"])
contactEmailStatusstring[]No-Filter by email status (verified, unverified, likely_to_engage, unavailable)
pagenumberNo1Page number for pagination
perPagenumberNo25Results per page (max: 100)

Required Integrations​

  • apollo (Contact Data — configure in Integrations Marketplace)

Best Practices​

Combine Title Variations in One Call​

Do this:

{
  "tool": "contact_search",
  "parameters": {
    "companyDomain": "salesforce.com",
    "personTitles": ["VP Marketing", "CMO", "Head of Marketing", "Marketing Director"]
  }
}

Don't do this:

// BAD: Multiple separate calls for each title
{"personTitles": ["VP Marketing"]}
{"personTitles": ["CMO"]}
{"personTitles": ["Head of Marketing"]}

Search Then Enrich​

  1. Use contact_search to find contacts (free)
  2. Review results to identify best matches
  3. Use contact_enrich on selected contacts (uses credits)

Handle Zero Results Gracefully​

If a search returns 0 results, do not retry with different title variations. Report "no matches found" to the user.

Example Usage​

MCP Client​

{
  "tool": "contact_search",
  "parameters": {
    "companyDomain": "salesforce.com",
    "personTitles": ["VP Sales", "Director of Sales"],
    "personSeniorities": ["vp", "director"],
    "perPage": 10
  }
}

Find Marketing Leaders​

{
  "tool": "contact_search",
  "parameters": {
    "companyDomain": "stripe.com",
    "personTitles": ["CMO", "VP Marketing", "Head of Marketing"],
    "personSeniorities": ["c_suite", "vp", "head"]
  }
}

Response Format​

{
  "data": {
    "contacts": [
      {
        "id": "contact_id",
        "firstName": "John",
        "lastName": "Smith",
        "name": "John Smith",
        "title": "VP of Sales",
        "seniority": "vp",
        "linkedinUrl": "https://linkedin.com/in/johnsmith",
        "organization": {
          "id": "org_123",
          "name": "Salesforce",
          "domain": "salesforce.com",
          "industry": "Software",
          "employeeCount": 50000
        },
        "city": "San Francisco",
        "state": "California",
        "country": "United States"
      }
    ],
    "pagination": {
      "page": 1,
      "perPage": 25,
      "totalResults": 150,
      "hasMore": true
    }
  }
}

Error Handling​

Common errors:

  • Invalid API key: Check Contact Data integration configuration
  • Rate limit exceeded: Wait and retry
  • Access denied: Check API key permissions
  • Missing company: Provide either companyDomain or companyName
  • contact_enrich - Get full contact details (email, phone) - uses credits
  • company_firmographic - Get company information
  • company_technographic - Analyze company tech stack

Next Steps​