Skip to main content

Company FAI (Functional Area Intelligence)

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.

Functional Area Intelligence (FAI): the DEPARTMENTAL / functional-area breakdown of technology usage at ONE company — which departments, roles, and locations use detected technologies, with per-department usage share and signal strength, per-role usage share, and decision-maker / influencer presence and titles. Provide exactly one company selector: a company domain (e.g. "cisco.com") OR an HG Insights company ID (hg_id). Narrow results with product_ids and/or vendor_ids (numeric HG IDs — resolve these via company_technographic before calling; do NOT guess numeric IDs), plus optional country, department_ids and role_ids (hex IDs from list_fai_departments — do NOT guess), has_decision_maker, has_influencer, and last_verified_date filters. MUTEX: department_ids and sort_field cannot be used together — the upstream rejects that combination; filter by departments OR sort, not both. Sort with sort_field + sort_direction; paginate with limit / offset (total_count in the response is the total matches before pagination). USE this when the user asks which departments, roles, or locations at a company use a specific technology, or wants decision-maker / influencer contacts by department. Do NOT use this to check whether a company uses a technology at all, or for whole-company install counts — use company_technographic (it also returns the product_id values to feed back in here). Do NOT use this to resolve or list valid FAI department / role IDs and names — use list_fai_departments first.

Parameters​

NameTypeRequiredDefaultDescription
company_domainstring❌ No-The company domain to analyze (e.g., "cisco.com"). Provide exactly one of company_domain or hg_id. Protocol prefixes (http://, https://), leading www., and trailing paths/queries/fragments are accepted and stripped automatically; case is normalized.
hg_idstring❌ No-HG Insights company ID (32 alphanumeric characters). Provide exactly one of company_domain or hg_id. Obtain from a previous company_search / company_firmographic result.
product_idsarray❌ No-HG Insights numeric product IDs — keep only FAI rows for these products (max 20). Get them from the product_id field of a company_technographic result for this same company. There is no product-name filter here; resolve names to IDs first. Omit to include all products.
vendor_idsarray❌ No-HG Insights numeric vendor IDs — keep only FAI rows for products from these vendors (max 20). Resolve via get_vendor_information / vendor lookups. Omit to include all vendors.
department_idsarray❌ No-FAI department IDs (hex). Call list_fai_departments first to discover valid IDs — do NOT guess or fabricate them. Omit to include all departments.
role_idsarray❌ No-FAI role IDs (hex-encoded). Narrows results to specific roles. Obtain role IDs from the role_id field of a prior company_fai response.
countryarray❌ No-ISO 3166-1 alpha-2 country codes (e.g. ["US", "CA"]) — keep only rows where the signal was detected in these countries. Case-insensitive (normalized to upper).
has_decision_makerboolean❌ No-When true, keep only rows where a decision maker for the product is present (see the row's decision_maker_titles). Omit to include rows regardless.
has_influencerboolean❌ No-When true, keep only rows where an influencer for the product is present (see the row's influencer_titles). Omit to include rows regardless.
last_verified_datestring❌ No-ISO 8601 date (YYYY-MM-DD, e.g. "2024-01-01"). Keep only rows whose last_verified_at is on or after this date.
sort_fieldstring❌ No-Field to sort results by. One of: department_usage_share, department_signal_strength, role_usage_share, role_signal_strength_at_location, product_name, department_name, role_name, country_name. role_usage_share = % of role holders at that location using the product. role_signal_strength_at_location = detection confidence at that location (can be 0 when role presence is detected but no usage-share data exists).
sort_directionstring❌ NoDESCSort direction (default DESC). Only applied when sort_field is provided.
limitinteger❌ No50Maximum number of FAI rows to return (default: 50, max: 1000). Paginate with offset; total_count gives the total before pagination.
offsetinteger❌ No0Pagination offset (default: 0, maximum: 10 000). Use with limit to page through results. The upstream API caps offset at 10 000 regardless of total_count. For large companies where total_count exceeds 10 000, apply filters (department_ids, product_ids, country, last_verified_date) to reduce total_count before paginating.

Required Integrations​

  • hginsights_v2__data_api

Use Cases​

  • Which departments at a company use a given technology? — pass a domain plus product_ids resolved from company_technographic
  • Account mapping: find which functional area to sell a product into at a target account
  • Find departments where decision makers or influencers for a product are present (has_decision_maker / has_influencer), with their titles
  • Compare per-department usage share and signal strength for a product across a company, sorted with sort_field
  • Map the geographic (country / state / city) footprint of a technology's usage within a company

Example Usage​

Which departments at Microsoft use a specific product (by numeric product_id)

{
  "tool": "company_fai",
  "arguments": {
    "company_domain": "microsoft.com",
    "product_ids": [
      10006583
    ]
  }
}

Top departments by usage share, US only (sort — no department_ids since they are mutex)

{
  "tool": "company_fai",
  "arguments": {
    "company_domain": "microsoft.com",
    "country": [
      "US"
    ],
    "sort_field": "department_usage_share",
    "sort_direction": "DESC",
    "limit": 25
  }
}

Departments with decision makers for a vendor at a company resolved by hg_id

{
  "tool": "company_fai",
  "arguments": {
    "hg_id": "1488903ED478F8C51D09F2EC5F2DCDA2",
    "vendor_ids": [
      25488
    ],
    "has_decision_maker": true
  }
}

company_technographic, list_fai_departments, get_vendor_information, company_install_time_series, search_companies