HG Firmographic

When to use

• A workflow has a domain or hg_id and needs the canonical HG company record: name, size, revenue, industry, HQ location, hierarchy level.
• A prompt has only a company name and must resolve it to an hg_id before any other call.
• An author needs to know which entity a domain actually resolved to (brand, group or subsidiary).

Tools you'll touch

• company_firmographic: firmographic lookup for up to 25 companies. Cost: 0.1 per company, billed proportionally to the batch. Cached 30 days.
• search_companies: name or criteria search returning identity only. Cost: 1 per 100 companies returned. See hg-search-companies.
• company_hierarchy: the ownership tree, when level fields aren't enough. See hg-subsidiary-handling.

Calling it

• Pass hg_ids or domains, never both (passing both is rejected). Up to 25 per call.
• Domains are normalised: scheme, www., paths and case are stripped. Other subdomains are kept (uk.acme.com is not acme.com).
• The response is { companies: [...] }. Unmatched companies are omitted; a fully unmatched batch returns an empty array. Match results by company_id or company_domain, never by position.

What HG returns

Each entry has company_id, company_domain and a firmographics object:

Field	Meaning
name, domain, domain_normalized	Identity. domain can be null
employees_total, employees_band	Exact headcount (null when only a band is known) and the band
revenue_total, revenue_band	Annual revenue in USD (null when only a band is known) and the band
industry_id, industry_name	HG industry (23 buckets, no Software bucket)
naics_code, naics_name, sic_codes, sic_names	Standard classifications
city_name, state_name, country_code, country_name, continent_name	HQ location
it_spend	Modeled IT spend estimate in USD (null if unavailable)
fortune_500_rank, forbes_2000_rank	Null if not ranked
company_level	Group HQ, Corporate Parent, Domestic Parent, Subsidiary or Site
corporate_parent_id, corporate_parent_name	The brand-level parent (null at the top)
global_hq_id, global_hq_name, global_hq_country_code	The ultimate parent. Absent (not null) for a Group HQ, which is its own GHQ

When your org has connected its own account data, the entry may also carry customer_data. That is the org's own record for the account, not HG data: cite it as "your CRM record", never as HG.

No ticker or public/private flag is returned. Don't decide "skip SEC, the company is private" from firmographics.

Hierarchy: read the level fields, not the id

• HG ids are hexadecimal; leading zeros may be omitted, so 31- and 32-character forms are the same company. Length says nothing about hierarchy. Compare ids case-insensitively after left-padding to 32 characters.
• Check company_level after every domain lookup. A group's main domain can resolve to a small subsidiary, and every downstream call then returns subsidiary-scale data.
• global_hq_id is the ultimate parent: a brand owned by a larger group points at the group. For brand-level questions use corporate_parent_id; use global_hq_id only when the user asks about the whole group.
• Full decision flow and logging: hg-subsidiary-handling.

Resolving a name without a domain

1. If you can find the official domain (user input, CRM, the company's site), use it: domain lookup is the most reliable route.
2. Otherwise call search_companies with company_identifiers.name, firmographics.company_level:"CORPORATE_PARENT" and a second filter such as country_codes. Name search is a token-substring match, so a brand name can return hundreds of loosely matching entities.
3. It returns identity only (hg_id, name, domain, domain_normalized). Pass the candidate hg_ids to company_firmographic and choose on name, domain, country, level and size.
4. If two candidates remain plausible, ask the user before spending on paid calls.

How to read it

Size and revenue. There is no confidence field.

• employees_total / revenue_total present → quote the figure as an HG estimate: "about 12,400 employees (HG)".
• Null → quote the band: "in the 10,001 to 50,000 employee range".
• Revenue and IT spend are modeled estimates. Round them in prose.

NAICS depth. naics_code is a 6-digit NAICS 2012 leaf. Use it as is to describe the company. For peer cohorts, take its 4-digit industry group as the grain, then expand that group back to its 6-digit leaves before searching, because search_companies only matches leaves. See hg-peer-cohort-selection.

Industry bucket. The HG industry taxonomy files software publishers under a computer-manufacturing bucket. For tech companies, describe the industry from NAICS or SIC, not industry_name.

Common pitfalls

1. Reading hg_id length as a hierarchy signal. It is a formatting artefact. Use company_level.
2. Accepting a domain's match without checking company_level. A brand domain can resolve to a small subsidiary.
3. Jumping to global_hq_id for a brand question. That's the ultimate parent. Use corporate_parent_id.
4. Quoting a band as an exact number. If *_total is null, say the band.
5. Citing customer_data as HG. It's the org's own record.
6. Passing both hg_ids and domains. The call is rejected.

Citation rules

Cite company_firmographic once at the section boundary ("HG, October 2026"). For a name resolved through search_companies, state the search term and the chosen candidate's domain.

Reference

• V2 tool docs: https://phoenix.hginsights.com/docs/mcp-tools/v2/company-firmographic
• Full docs for LLMs: https://phoenix.hginsights.com/docs/llms-full.txt
• Related skills: hg-mcp-calling-rules, hg-subsidiary-handling, hg-search-companies, hg-peer-cohort-selection, hg-company-profile