Company Firmographic

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.

Batch firmographic lookup for one or more known companies. Call this when the user asks about a company's firmographics — name, location, industry, employee/revenue size, corporate hierarchy, or global HQ — or wants the same facts for a short list of companies. Use this (not company_enrich) for firmographic-only questions: it is faster and returns a smaller payload than a full profile. Each entry returns the HG record with name, industry_name, employees_total/band, revenue_total/band, city/state/country, NAICS/SIC codes, Fortune 500 / Forbes 2000 rank, it_spend, company_level, and the corporate-parent / global_hq_* hierarchy. company_id is that entry's HG company id (hex); for a subsidiary or intermediate parent, chain on global_hq_id to reach the ultimate parent (equal to company_id for a Group HQ, where the duplicate global_hq_* fields are dropped). Selection is batch-only: pass hg_ids OR domains (mutually exclusive — not both; up to 25 each). The response is always { companies: [...] }, one entry per matched company, with no found/message flag. No-match sentinel: unmatched companies are omitted, so a fully unmatched request returns an empty array ({ companies: [] }) — check that each requested id/domain has a corresponding entry. When the org has a Snowflake integration configured, its own account record for each company is attached as customer_data. Do NOT use this when: the firmographic data is already in context (e.g. from a prior company_enrich call); you need the full multi-level ownership tree (subsidiaries, siblings, depth traversal) — use company_hierarchy; you need a full multi-signal profile (technographic + intent + spend) — use company_enrich; or you are discovering companies you lack ids or domains for — use search_companies.

Credits

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

Parameters

Name	Type	Default	Description
`hg_ids`	array	-	HG Insights company IDs to look up, as a batch array (up to 25). Each id is 31-32 alphanumeric/hex chars, obtained from a prior search_companies or company_enrich result. Each returns one entry under companies[], in request order; ids that upstream cannot match are omitted. Provide EITHER hg_ids OR domains — exactly one selector is required, they are mutually exclusive, and passing both is rejected.
`domains`	array	-	Company domains to look up, as a batch array (e.g. ['cisco.com', 'salesforce.com'], up to 25). Protocol prefixes (http://, https://), a leading www., and trailing paths/queries are stripped automatically, and case is normalized. Each domain resolves to the matching HG entity (e.g. linkedin.com → LinkedIn Corporation, company_level "Corporate Parent", with Microsoft surfaced under global_hq_*) and returns one entry under companies[]; domains that upstream cannot match are omitted. Provide EITHER hg_ids OR domains — exactly one selector is required, they are mutually exclusive, and passing both is rejected.

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

What industry and employee count does a company report? — single-domain lookup
What is a company's estimated IT spend and revenue? — it_spend + revenue_total fields
Get firmographics for a short list of companies in one call — pass domains: [...] (up to 25)
Is company X a subsidiary or intermediate parent? — company_level + global_hq_* answer hierarchy without company_hierarchy
I have hg_ids from search_companies — get the firmographic record for each

Example Usage

Lookup by domain

{
  "tool": "company_firmographic",
  "arguments": {
    "domains": [
      "salesforce.com"
    ]
  }
}

Batch lookup by domain (URLs are normalized)

{
  "tool": "company_firmographic",
  "arguments": {
    "domains": [
      "cisco.com",
      "https://www.linkedin.com/about"
    ]
  }
}

Lookup by hg_id

{
  "tool": "company_firmographic",
  "arguments": {
    "hg_ids": [
      "25582D0E650950949A473EA7345C193E"
    ]
  }
}

Response Format

Field	Type	Description
`companies`	array
`companies[].company_id`	string	HG Insights company identifier (hex). Empty string when no company matched the query.
`companies[].company_domain`	string	The company domain that was queried (or the domain returned by the provider).
`companies[].firmographics`	object	Firmographic record passed through from the HG v2 API (snake_case fields). global_hq_* fields carry the ultimate-parent record for a subsidiary; for a Group HQ they duplicate the base fields and are omitted. company_level indicates the entity tier: Group HQ, Corporate Parent, Domestic Parent, Site, or Subsidiary. For a subsidiary, chain enrichment tools on global_hq_id (not company_id) to reach the ultimate parent.
`companies[].firmographics.name`	string	Company name.
`companies[].firmographics.domain`	string \| null	Company domain (null when unavailable).
`companies[].firmographics.domain_normalized`	string	Normalized company domain.
`companies[].firmographics.city_name`	string	HQ city.
`companies[].firmographics.state_name`	string	HQ state/province.
`companies[].firmographics.country_code`	string \| null	HQ ISO country code (null when unavailable).
`companies[].firmographics.country_name`	string	HQ country name.
`companies[].firmographics.continent_name`	string	HQ continent.
`companies[].firmographics.subcontinent_name`	string	HQ subcontinent.
`companies[].firmographics.geopolitical_name`	string	HQ geopolitical region.
`companies[].firmographics.postal_code`	string	HQ postal/zip code.
`companies[].firmographics.employees_total`	number \| null	Exact employee count (null if only a band is available).
`companies[].firmographics.employees_band`	string	Banded employee range (e.g. "10,001-50,000").
`companies[].firmographics.revenue_total`	number \| null	Annual revenue in USD (null if only a band is available).
`companies[].firmographics.revenue_band`	string	Banded revenue range.
`companies[].firmographics.industry_id`	number \| string	HG industry id.
`companies[].firmographics.industry_name`	string	HG industry name.
`companies[].firmographics.naics_code`	string	NAICS classification code.
`companies[].firmographics.naics_name`	string	NAICS classification name.
`companies[].firmographics.sic_codes`	array	SIC classification codes.
`companies[].firmographics.sic_names`	array	SIC classification names.
`companies[].firmographics.forbes_2000_rank`	number \| null	Forbes 2000 ranking (null if not ranked).
`companies[].firmographics.fortune_500_rank`	number \| null	Fortune 500 ranking (null if not ranked).
`companies[].firmographics.it_spend`	number \| null	Estimated IT spend in USD (null if not available).
`companies[].firmographics.company_level`	string	UCM level (Group HQ, Corporate Parent, Domestic Parent, Site, Subsidiary).
`companies[].firmographics.corporate_parent_id`	string \| null	Corporate parent hex id (null for a top-level/GHQ company).
`companies[].firmographics.corporate_parent_name`	string \| null	Corporate parent name (null for a top-level/GHQ company).
`companies[].firmographics.global_hq_id`	string	Ultimate-parent (global HQ) hex company id — the chaining target for a subsidiary. Omitted for a Group HQ, where it equals company_id.
`companies[].firmographics.global_hq_name`	string	Global HQ company name.
`companies[].firmographics.global_hq_country_code`	string	Global HQ ISO country code.
`companies[].customer_data`	object	The org's own account record for this company, joined by domain from Snowflake (present only when a Snowflake integration is configured and a row matched).

company_enrich, company_hierarchy, company_technographic, company_intent, search_companies

Credits​

Parameters​

Required Integrations​

Use Cases​

Example Usage​

Response Format​

Related Tools​