Skip to main content

Search Companies

Search for companies using natural language criteria or by HG Insights company IDs.

Tool key: search_companies

Parameters​

NameTypeRequiredDefaultDescription
searchCriteriastringConditional-Natural language description of the companies you want to find. Required unless hg_id or hg_ids is provided. Min 3 characters.
hg_idstringNo-HG Insights company ID (32 alphanumeric characters). When provided, searchCriteria is optional.
hg_idsstring[]No-List of HG Insights company IDs to look up in a single call (max 100). When provided, searchCriteria is optional.
limitnumberNo100Maximum number of companies to return (1-1000).

Required Integrations​

  • hginsights

How It Works​

This tool uses natural language processing to parse your search criteria into structured filters. It automatically resolves human-readable names to API IDs via catalog lookups.

Supported filters:

  • Technologies: Product/vendor names (e.g., "AWS", "Salesforce", "Shopify Plus")
  • Industries: SaaS, Financial Services, Manufacturing, Healthcare, etc.
  • Geographies: Countries and regions (e.g., "California", "Germany", "Europe")
  • Revenue ranges: "$100M+", "under $50M", "$10M-$50M"
  • Employee counts: "50-500 employees", "enterprise", "startups"
  • Founding date: "founded after 2015"
  • Tech spend: Mentions of "spending" or "budget"

AND/OR logic for technologies:

  • "using Shopify OR Vertex" — finds companies using either (single API call)
  • "using Shopify AND Vertex" — finds companies using both (intersection of results)

Use Cases​

  • List building and prospect identification
  • Market research and segmentation
  • Territory planning
  • Technology adoption analysis

Example Usage​

{
  "tool": "search_companies",
  "parameters": {
    "searchCriteria": "SaaS companies using AWS in California with 50-500 employees"
  }
}

Technology AND query​

{
  "tool": "search_companies",
  "parameters": {
    "searchCriteria": "Companies using Shopify AND Vertex Tax",
    "limit": 50
  }
}

Direct HG ID lookup​

{
  "tool": "search_companies",
  "parameters": {
    "hg_ids": ["0FF69D9F596504A1FF4FF5B16FF", "1AA23B4C567890D1EE2FF3A45BC"]
  }
}

Response Format​

The tool returns a structured JSON response with:

  • count: Total number of matching companies
  • companies: Array of company objects with companyId, companyName, domain, revenue, employeeCount, industry, etc.
  • metadata: Search metadata including filtersApplied, catalogLookupsPerformed, unresolvedNames, and original searchCriteria

Error Handling​

Common errors:

  • No valid filters: Search criteria too vague — be more specific about technologies, industries, locations, or size
  • Missing Integration: HG Insights API key not configured
  • Authentication Error: Invalid API key
  • Rate Limit: API rate limit exceeded
  • company_firmographic - Get detailed company information
  • company_technographic - Analyze technology stack
  • company_intent - Check buying signals
  • company_spend - Analyze spending patterns

Next Steps​