Company Firmographic

Call this when a user asks about a company's firmographics — name, location, industry, employee/revenue size, corporate hierarchy, or global HQ. Use this (not company_research) for firmographic-only questions — it is faster and returns a smaller payload than a full profile.

Returns: name, industry_name, employees_total/employees_band, revenue_total/revenue_band, city/state/country, NAICS/SIC codes, Fortune 500 / Forbes 2000 rank, it_spend, company_level, and the corporate-parent / global_hq_* hierarchy fields.

company_level values: "Group HQ" (ultimate parent — global_hq_* fields are omitted), "Corporate Parent" (intermediate parent — global_hq_* carries the ultimate parent), or subsidiary. E.g. linkedin.com → company_level="Corporate Parent", global_hq_domain="microsoft.com". Chain global_hq_id to reach the ultimate parent (same as companyId for a Group HQ).

companyId is the queried entity's HG company id (32 uppercase hex chars) for chaining downstream.

No-match detection: the API always returns found:true. When companyId is "" (empty string) and firmographics is an empty object {}, no company was matched — do NOT rely on found as a sentinel.

When the org has a Snowflake integration configured, its own account record is attached as customerData.

Provide companyDomain or hg_id; hg_id takes precedence.

Do NOT use this when: the firmographic data is already in context (e.g. from a prior company_research call); you need the full multi-level ownership tree (use get_company_hierarchy); you need a full multi-signal profile (technographic + intent + spend) — use company_research; or you are filtering/building a list of many companies — use search_companies.

Credits

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

Parameters

Name	Type	Default	Description
`companyDomain`	string	-	The company domain to look up (e.g., 'cisco.com'). Either companyDomain or hg_id is required. Protocol prefixes (http://, https://), leading www., and trailing paths/queries/fragments are accepted and stripped automatically; case is normalized.
`hg_id`	string	-	HG Insights company ID (32 uppercase hex characters; schema accepts 31-32 alphanumeric chars). When provided, companyDomain is silently ignored. Obtain from a previous search_companies result.

Required Integrations

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

HG Insights (v2) (hginsights_v2)

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
Is company X a subsidiary of company Y? — company_level + global_hq_* answer hierarchy without get_company_hierarchy
I have an hg_id from search_companies — get the firmographic profile for it
What is a company's Fortune 500 rank and NAICS classification?

Example Usage

Lookup by domain

{
  "tool": "company_firmographic",
  "arguments": {
    "companyDomain": "salesforce.com"
  }
}

URL is normalized automatically

{
  "tool": "company_firmographic",
  "arguments": {
    "companyDomain": "https://www.linkedin.com/about"
  }
}

Lookup by hg_id

{
  "tool": "company_firmographic",
  "arguments": {
    "hg_id": "25582D0E650950949A473EA7345C193E"
  }
}

Response Format

Field	Type	Description
`companyId`	string	HG Insights company identifier (hex). Empty string when the company was not found.
`companyDomain`	string	The company domain that was queried (or the domain returned by the provider).
`found`	boolean	True when a company matched the query; false when not found (companyId is empty and message explains).
`message`	string	Present only when found is false — a human-readable explanation of why no company matched.
`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 companyId) to reach the ultimate parent.
`firmographics.name`	string	Company name.
`firmographics.domain`	string	Company domain.
`firmographics.domain_normalized`	string	Normalized company domain.
`firmographics.city_name`	string	HQ city.
`firmographics.state_name`	string	HQ state/province.
`firmographics.country_code`	string	HQ ISO country code.
`firmographics.country_name`	string	HQ country name.
`firmographics.continent_name`	string	HQ continent.
`firmographics.subcontinent_name`	string	HQ subcontinent.
`firmographics.geopolitical_name`	string	HQ geopolitical region.
`firmographics.postal_code`	string	HQ postal/zip code.
`firmographics.employees_total`	number \| null	Exact employee count (null if only a band is available).
`firmographics.employees_band`	string	Banded employee range (e.g. "10,001-50,000").
`firmographics.revenue_total`	number \| null	Annual revenue in USD (null if only a band is available).
`firmographics.revenue_band`	string	Banded revenue range.
`firmographics.industry_id`	number \| string	HG industry id.
`firmographics.industry_name`	string	HG industry name.
`firmographics.naics_code`	string	NAICS classification code.
`firmographics.naics_name`	string	NAICS classification name.
`firmographics.sic_codes`	array	SIC classification codes.
`firmographics.sic_names`	array	SIC classification names.
`firmographics.forbes_2000_rank`	number \| null	Forbes 2000 ranking (null if not ranked).
`firmographics.fortune_500_rank`	number \| null	Fortune 500 ranking (null if not ranked).
`firmographics.it_spend`	number \| null	Estimated IT spend in USD (null if not available).
`firmographics.company_level`	string	UCM level (Group HQ, Corporate Parent, Domestic Parent, Site, Subsidiary).
`firmographics.corporate_parent_id`	string	Corporate parent hex id.
`firmographics.corporate_parent_name`	string	Corporate parent name.
`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 companyId.
`firmographics.global_hq_name`	string	Global HQ company name.
`firmographics.global_hq_country_code`	string	Global HQ ISO country code.
`customerData`	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).

Example response

{
  "companyId": "3AB6196C456CE3313A04A57BA6FA7BE3",
  "companyDomain": "salesforce.com",
  "found": true,
  "firmographics": {
    "name": "Salesforce, Inc.",
    "domain": "salesforce.com",
    "city_name": "San Francisco",
    "state_name": "CA",
    "country_code": "US",
    "country_name": "United States of America (the)",
    "postal_code": "94105",
    "employees_total": 83334,
    "employees_band": "Above 10,000",
    "revenue_total": 41525000000,
    "revenue_band": "Over $1,000,000,000",
    "industry_name": "Computer and Electronic Product Manufacturing",
    "naics_code": "511210",
    "naics_name": "Software Publishers",
    "sic_codes": [
      "I7372"
    ],
    "forbes_2000_rank": 158,
    "fortune_500_rank": 114,
    "it_spend": 4101304613,
    "company_level": "Group HQ"
  }
}

company_research, get_company_hierarchy, company_technographic, company_intent, search_companies

Credits​

Parameters​

Required Integrations​

Use Cases​

Example Usage​

Response Format​

Related Tools​