Company Enrich

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.

Enrich a BATCH of up to 25 companies with multiple data sections in a single call, returned as { companies: [...] }. Select companies with hg_ids and/or domains (at least one required; both may be combined and are unioned). Companies with no match are omitted from the array — do not assume positional alignment with your input. Choose sections with fields: firmographics (name, location, industry, size, hierarchy), spend (IT spend by category), ai_spend (AI spend by category — opt-in, request explicitly), technographics (installed tech stack), contracts (contract records), ai_maturity (AI/data maturity scores), cloud_maturity (per-provider cloud footprint), statistics (aggregated summaries), market_benchmarks (peer-group positioning). Defaults to firmographics + technographics + spend when fields is omitted. The same fields/filters/pagination apply to every company in the batch; credit cost scales with the number of companies returned. contracts/statistics/market_benchmarks are entitlement-gated — if your org lacks access they are omitted and listed under unavailableSections rather than failing the call. Use this when you have a known set of companies (by hg_id or domain) and need 2+ data sections — a broad profile — in one round-trip. Do NOT use when: you only need firmographics for one company or a simple lookup — use company_firmographic (faster, cheaper, smaller payload, and accepts a batch too); you are discovering/filtering companies you do not yet have identifiers for — use search_companies; you need the full multi-level ownership tree (subsidiaries, siblings) — use company_hierarchy; you need exactly one section — prefer the dedicated single-section tool (company_firmographic, company_technographic, company_spend). The interactive dashboard renders the first returned company (batches show a banner).

Parameters

Name	Type	Default	Description
`hg_ids`	array	-	HG Insights company IDs for batch enrichment (up to 25). Each is 31-32 alphanumeric/hex chars, from a previous search_companies result. Provide hg_ids or domains (at least one is required); both may be combined and are unioned.
`domains`	array	-	Company domains for batch enrichment (e.g. ['cisco.com', 'salesforce.com'], up to 25). Protocol prefixes (http://, https://), leading www., and trailing paths/queries/fragments are stripped automatically; case is normalized. Provide hg_ids or domains; both may be combined.
`fields`	array	-	Which data sections to return. One or more of: firmographics, spend, ai_spend, technographics, contracts, ai_maturity, cloud_maturity, statistics, market_benchmarks. Defaults to ['firmographics','technographics','spend'] when omitted (ai_spend is opt-in — request it explicitly). contracts/statistics/market_benchmarks are entitlement-gated and are omitted (with unavailableSections noting them) if your org lacks access.
`filters`	object	-	Optional upstream filters, forwarded verbatim. `spend.categories.{ids,names}`, `ai_spend.categories.{ids,names}` and `technographics.{country,installs,product_attributes,product_categories,product_last_verified_date,products,vendors}` — see the /v2/companies/enrich contract. Filters only apply to the matching section. IMPORTANT: category and product `names` filters require EXACT catalog strings (e.g. "Infrastructure-as-a-Service (IaaS)", not "Cloud Infrastructure"; "Cloud Services", not "Cloud Infrastructure") — resolve canonical names via get_product_category or get_vendor_information first when unsure. A non-matching name silently returns no data for that section, indistinguishable from a true empty result.
`filters.spend`	object	-
`filters.spend.categories`	object	-
`filters.spend.categories.ids`	array	-
`filters.spend.categories.names`	array	-
`filters.ai_spend`	object	-
`filters.ai_spend.categories`	object	-
`filters.ai_spend.categories.ids`	array	-
`filters.ai_spend.categories.names`	array	-
`filters.technographics`	object	-
`filters.technographics.country`	object	-
`filters.technographics.country.codes` Required	array	-
`filters.technographics.installs`	object	-
`filters.technographics.installs.granularity`	string	-
`filters.technographics.installs.localized`	boolean	-
`filters.technographics.product_attributes`	object	-
`filters.technographics.product_attributes.ids` Required	array	-
`filters.technographics.product_categories`	object	-
`filters.technographics.product_categories.ids`	array	-
`filters.technographics.product_categories.names`	array	-
`filters.technographics.product_last_verified_date`	object	-
`filters.technographics.product_last_verified_date.min`	string	-
`filters.technographics.product_last_verified_date.max`	string	-
`filters.technographics.products`	object	-
`filters.technographics.products.ids`	array	-
`filters.technographics.products.names`	array	-
`filters.technographics.vendors`	object	-
`filters.technographics.vendors.ids`	array	-
`filters.technographics.vendors.names`	array	-
`pagination`	object	-	Optional independent pagination for the nested spend, ai_spend and technographics arrays: `{ spend?: {limit,offset}, ai_spend?: {limit,offset}, technographics?: {limit,offset} }`. limit is 0-100.
`pagination.spend`	object	-
`pagination.spend.limit`	integer	-
`pagination.spend.offset`	integer	-
`pagination.ai_spend`	object	-
`pagination.ai_spend.limit`	integer	-
`pagination.ai_spend.offset`	integer	-
`pagination.technographics`	object	-
`pagination.technographics.limit`	integer	-
`pagination.technographics.offset`	integer	-
`contracts`	object	-	Optional contracts request block `{ filters?: {active_only, vendor_names (max 10)}, limit?, offset? }`. Requires 'contracts' in fields AND the contracts entitlement — providing this block alone does not return contracts.
`contracts.filters`	object	-
`contracts.filters.active_only`	boolean	-
`contracts.filters.vendor_names`	array	-
`contracts.limit`	integer	-
`contracts.offset`	integer	-
`full`	boolean	`false`	When true, return every row per section (technographic installs, spend/ai_spend rows, contract records) instead of the default per-section caps that keep a call under the 40KB inline limit. Use only when you need the complete section arrays. Default: false.

Required Integrations

This tool is only available when your organization has the following integration configured in the Phoenix Integrations settings:

HG Insights (Data API) (hginsights_v2__data_api)

Use Cases

Build a full company profile (firmographics + technographics + spend) for a domain in one call — omit fields to get the default trio
Enrich a short list of companies at once — pass domains: [...] and/or hg_ids: [...] (up to 25, unioned)
Get IT spend AND installed tech stack for a company without two separate tool calls — fields: ["spend", "technographics"]
Pull AI spend and AI/data maturity together for account research — fields: ["ai_spend", "ai_maturity"] (ai_spend is opt-in)
Enrich the hg_ids returned by search_companies with several sections in a single round-trip

Example Usage

Default profile (firmographics + technographics + spend) by domain

{
  "tool": "company_enrich",
  "arguments": {
    "domains": [
      "cisco.com"
    ]
  }
}

Batch enrich with selected sections

{
  "tool": "company_enrich",
  "arguments": {
    "domains": [
      "salesforce.com",
      "workday.com"
    ],
    "fields": [
      "firmographics",
      "spend",
      "ai_spend"
    ]
  }
}

Enrich by hg_id with a technographics country filter

{
  "tool": "company_enrich",
  "arguments": {
    "hg_ids": [
      "25582D0E650950949A473EA7345C193E"
    ],
    "fields": [
      "technographics"
    ],
    "filters": {
      "technographics": {
        "country": {
          "codes": [
            "US"
          ]
        }
      }
    }
  }
}

Response Format

Field	Type	Description
`companies`	array	One enriched company per matched selector.
`companies[].company_id`	string	HG Insights company id (hex).
`companies[].company_domain`	string	The resolved company domain.
`companies[].found`	boolean	Always true for entries present in the array (unmatched companies are omitted).
`companies[].header`	object	Company header (drives the dashboard). Populated from firmographics when requested; other fields fall back to null when firmographics was not fetched.
`companies[].header.company_name`	string	The company's name from firmographics; falls back to the company domain when firmographics wasn't requested (always a non-empty string).
`companies[].header.domain`	string \| null
`companies[].header.industry`	string \| null
`companies[].header.employee_count`	string \| number \| null
`companies[].header.revenue`	string \| number \| null
`companies[].header.location`	object \| null
`companies[].header.website`	string \| null
`companies[].header.founded_year`	number \| null
`companies[].header.company_type`	string \| null
`companies[].key_metrics`	object
`companies[].key_metrics.it_spend`	number \| null
`companies[].key_metrics.fortune_500_rank`	number \| null
`companies[].key_metrics.forbes_2000_rank`	number \| null
`companies[].key_metrics.top_tech_categories`	array
`companies[].fields`	array	The sections requested.
`companies[].unavailableSections`	array	Requested sections that were dropped because the org is not entitled to them.
`companies[].firmographics`	object \| null	Firmographic record (upstream passthrough, snake_case).
`companies[].spend`	object \| null	IT spend: { all: [...], all_count }.
`companies[].ai_spend`	object \| null	AI spend: { all: [...], all_count } (opt-in; only present when ai_spend is in fields).
`companies[].technographics`	object \| null	Tech installs: { installs: [...], installs_count }.
`companies[].contracts`	object \| null	Contracts: { count, records: [...] } (records passed through unchanged).
`companies[].ai_maturity`	object \| null	AI/data maturity scores (upstream passthrough).
`companies[].cloud_maturity`	object \| null	Cloud footprint counts/percentages (upstream passthrough).
`companies[].statistics`	object \| null	Aggregated summaries (upstream passthrough).
`companies[].market_benchmarks`	object \| null	Peer-group positioning (upstream passthrough).

company_firmographic, company_technographic, company_spend, company_hierarchy, search_companies

Parameters​

Required Integrations​

Use Cases​

Example Usage​

Response Format​

Related Tools​

Parameters

Required Integrations

Use Cases

Example Usage

Response Format

Related Tools