# Enrich Companies

Unified endpoint to enrich company data with firmographics, spend, technographics, and contracts.
Select which data categories to include using the `fields` parameter.
Filter technographics by categories, vendors, or products using the `filters` parameter.
Control pagination for both technographics and spend data using the `pagination` parameter.
Configure contracts options using the optional `contracts` sub-body.
Contracts require the contracts entitlement.

Endpoint: POST /data-api/v2/companies/enrich
Security: authorization

## Security:

  - `authorization` (unknown)
    http bearer API_KEY

## Request body:

  - `application/json` (unknown)
    Enrich Request

## Request fields (application/json):

  - `companies` (object, required)
    Filter companies by IDs or domains (mutually exclusive)
    Example: {"ids":["E48EDEB162A5FBFDAF2DCF707079F8F","1698C53EBC888758570396E0334965C1"]}

  - `companies.domains` (array)
    Array of company domains (e.g., example.com)

  - `companies.ids` (array)
    Array of hex-encoded company IDs

  - `contracts` (object)
    Configuration for contracts data in enrich request

  - `contracts.filters` (object)
    Filters for contracts data

  - `contracts.filters.active_only` (boolean)
    When true, return only active contracts

  - `contracts.filters.vendor_names` (array)
    Filter by vendor names (max 10)

  - `contracts.limit` (integer)
    Maximum number of contracts per company

  - `contracts.offset` (integer)
    Number of contracts to skip

  - `fields` (array, required)
    Which data categories to include in the response

  - `filters` (object)
    Filters for enrich request

  - `filters.ai_spend` (object)
    Filters for AI spend data
    Example: {"categories":{"ids":["32144E4D868532F1D3A1264DE832ED2F"],"names":["AI Hardware"]}}

  - `filters.ai_spend.categories` (object)
    Filter by hex-encoded IDs and/or names (assumes ANY_PRESENT inclusion method)

  - `filters.ai_spend.categories.ids` (array)
    Array of hex-encoded IDs

  - `filters.ai_spend.categories.names` (array)
    Array of entity names for substring matching (case-insensitive)

  - `filters.mentions` (object)
    Filters for mentions data
    Example: {"granularity":"global","mention_categories":{"ids":["SW036"]},"mentions":{"ids":[24290]}}

  - `filters.mentions.country` (object)
    Filter by country

  - `filters.mentions.country.codes` (array)
    Array of ISO 3166-1 alpha-2 country codes (e.g., US, GB, DE)

  - `filters.mentions.granularity` (string)
    Controls the shape of returned mentions. "country" returns one row per mention per country. "global" returns deduplicated rows per mention with country_code null.
    Enum: "global", "country"

  - `filters.mentions.localized` (boolean)
    DEPRECATED: use `granularity` instead. When `granularity` is provided, it takes precedence.

  - `filters.mentions.mention_attributes` (object)
    Filter by numeric IDs and/or names (assumes ANY_PRESENT inclusion method)

  - `filters.mentions.mention_attributes.ids` (array)
    Array of numeric IDs

  - `filters.mentions.mention_attributes.names` (array)
    Array of entity names for substring matching (case-insensitive)

  - `filters.mentions.mention_categories` (object)
    Filter by string IDs and/or names (assumes ANY_PRESENT inclusion method)

  - `filters.mentions.mention_categories.ids` (array)
    Array of string IDs

  - `filters.mentions.mention_categories.names` (array)
    Array of entity names for substring matching (case-insensitive)

  - `filters.mentions.mention_last_verified_date` (object)
    Filter by product last verified date range (inclusive)

  - `filters.mentions.mention_last_verified_date.max` (string)
    Maximum last verified date (inclusive), e.g. 2024-12-31

  - `filters.mentions.mention_last_verified_date.min` (string)
    Minimum last verified date (inclusive), e.g. 2024-01-01

  - `filters.spend` (object)
    Filters for spend data
    Example: {"categories":{"ids":["32144E4D868532F1D3A1264DE832ED2F"],"names":["Cloud"]}}

  - `filters.technographics` (object)
    Filters for technographics data
    Example: {"country":{"codes":["US"]},"installs":{"granularity":"country"},"product_attributes":{"ids":[222]},"product_categories":{"ids":["319D067B229178F03BCFA1DA4AC4DEDE"],"names":["CRM"]},"product_last_veri…

  - `filters.technographics.installs` (object)
    Install-level filter options

  - `filters.technographics.installs.granularity` (string)
    Controls the shape of returned installs. "country" returns one row per product per country with `country_code` populated (across all countries the company has installs in, unless restricted by the country code filter). "global" returns deduplicated rows per product with `country_code` null. When omitted, behavior falls back to `localized`. Takes precedence over `localized` when provided.
    Enum: "global", "country"

  - `filters.technographics.installs.localized` (boolean)
    DEPRECATED: use `granularity` instead. Only match records where installs are within the same country as the company. Overridden by country code filter when provided. When `granularity` is provided, it takes precedence over this field.

  - `filters.technographics.product_attributes` (object)
    Filter by product attribute IDs (assumes ANY_PRESENT inclusion method)

  - `filters.technographics.product_attributes.ids` (array, required)
    Array of product attribute IDs

  - `pagination` (object)
    Pagination parameters for companies and nested data

  - `pagination.ai_spend` (object)
    Pagination parameters for spend data. Set paginate to false to return all categories without pagination (limit and offset are ignored).

  - `pagination.ai_spend.limit` (integer)
    The number of records to return in the request.

  - `pagination.ai_spend.offset` (integer)
    Used for paginating records.

  - `pagination.ai_spend.paginate` (boolean)
    When false, returns all spend categories without pagination. The limit and offset parameters are ignored.

  - `pagination.mentions` (object)
    Pagination parameters for mentions data

  - `pagination.mentions.limit` (integer)
    The number of technographics records to return in the request.

  - `pagination.mentions.sort` (string)
    How to order mentions results. `intensity`: highest-intensity mentions first (default). `last_seen`: most recently verified mentions first.
    Enum: "intensity", "last_seen"

  - `pagination.technographics` (object)
    Pagination parameters for technographics data

  - `pagination.technographics.sort` (string)
    How to order technographics results. `intensity`: highest-intensity products first (default). `last_seen`: most recently verified products first, i.e. sorted by the `product_last_verified_date` response field.
    Enum: "intensity", "last_seen"

## Response 200:

  - `200` (unknown)
    Enrich Response

## Response 200 fields (application/json):

  - `companies` (array)

  - `companies.ai_maturity` (any)
    AI maturity data for a company

  - `companies.ai_spend` (object)
    AI Spend data

  - `companies.ai_spend.all` (array)
    Array of AI spend records

  - `companies.ai_spend.all_count` (integer)
    Total count of AI spend records

  - `companies.cloud_maturity` (any)
    Cloud maturity data for a company

  - `companies.contracts` (object)
    Contracts data

  - `companies.contracts.count` (integer)
    Total count of contracts

  - `companies.contracts.records` (array)
    Array of contract records

  - `companies.domain` (string)
    Company domain (populated only when the request includes domains)

  - `companies.firmographics` (any)
    Firmographic data for a company

  - `companies.firmographics.city_name` (string)

  - `companies.firmographics.continent_name` (string)

  - `companies.firmographics.country_code` (string)

  - `companies.firmographics.country_name` (string)

  - `companies.firmographics.domain` (string)

  - `companies.firmographics.domain_normalized` (string)

  - `companies.firmographics.employees_band` (string)

  - `companies.firmographics.employees_total` (integer)

  - `companies.firmographics.forbes_2000_rank` (integer)

  - `companies.firmographics.fortune_500_rank` (integer)

  - `companies.firmographics.geopolitical_name` (string)

  - `companies.firmographics.id` (string)

  - `companies.firmographics.industry_id` (integer)

  - `companies.firmographics.industry_name` (string)

  - `companies.firmographics.naics_code` (string)

  - `companies.firmographics.naics_name` (string)

  - `companies.firmographics.name` (string)

  - `companies.firmographics.postal_code` (string)

  - `companies.firmographics.revenue_band` (string)

  - `companies.firmographics.revenue_total` (number)

  - `companies.firmographics.sic_codes` (array)

  - `companies.firmographics.sic_names` (array)

  - `companies.firmographics.state_name` (string)

  - `companies.firmographics.subcontinent_name` (string)

  - `companies.firmographics.company_level` (string)

  - `companies.firmographics.corporate_parent_id` (string)

  - `companies.firmographics.corporate_parent_name` (string)

  - `companies.firmographics.domestic_parent_id` (string)

  - `companies.firmographics.domestic_parent_name` (string)

  - `companies.firmographics.global_hq_city_name` (string)

  - `companies.firmographics.global_hq_continent_name` (string)

  - `companies.firmographics.global_hq_country_code` (string)

  - `companies.firmographics.global_hq_country_name` (string)

  - `companies.firmographics.global_hq_domain` (string)

  - `companies.firmographics.global_hq_domain_normalized` (string)

  - `companies.firmographics.global_hq_employees_band` (string)

  - `companies.firmographics.global_hq_forbes_2000_rank` (integer)

  - `companies.firmographics.global_hq_fortune_500_rank` (integer)

  - `companies.firmographics.global_hq_geopolitical_name` (string)

  - `companies.firmographics.global_hq_id` (string)

  - `companies.firmographics.global_hq_industry_id` (integer)

  - `companies.firmographics.global_hq_industry_name` (string)

  - `companies.firmographics.global_hq_naics_code` (string)

  - `companies.firmographics.global_hq_naics_name` (string)

  - `companies.firmographics.global_hq_name` (string)

  - `companies.firmographics.global_hq_postal_code` (string)

  - `companies.firmographics.global_hq_revenue_band` (string)

  - `companies.firmographics.global_hq_sic_codes` (array)

  - `companies.firmographics.global_hq_sic_names` (array)

  - `companies.firmographics.global_hq_state_name` (string)

  - `companies.firmographics.global_hq_subcontinent_name` (string)

  - `companies.firmographics.it_spend` (number)

  - `companies.firmographics.parent_id` (string)

  - `companies.id` (string)
    HG company ID (hex-encoded). Null when a requested domain is not tracked by HG; echoes the requested ID when a requested HG ID is not tracked.

  - `companies.market_benchmarks` (object)
    Peer-group percentile benchmarking against similar organizations

  - `companies.market_benchmarks.computed_at` (string)
    When market benchmarks were computed

  - `companies.market_benchmarks.peer_group` (object)
    Peer group definition used for benchmarking

  - `companies.market_benchmarks.peer_group.employee_range` (string)
    Employee count range (e.g. 1000-5000)

  - `companies.market_benchmarks.peer_group.industry` (string)
    Industry classification

  - `companies.market_benchmarks.peer_group.peer_count` (integer)
    Number of peers in the group

  - `companies.market_benchmarks.peer_group.region` (string)
    Geographic region

  - `companies.market_benchmarks.similar_organizations` (array)
    List of similar organizations

  - `companies.market_benchmarks.similar_organizations.location_country` (string)
    Country of the organization

  - `companies.market_benchmarks.similar_organizations.organization_id` (string, required)
    HG organization ID

  - `companies.market_benchmarks.similar_organizations.organization_name` (string, required)
    Organization name

  - `companies.market_benchmarks.similar_organizations.similarity_factors` (array, required)
    Factors contributing to similarity

  - `companies.market_benchmarks.similar_organizations.similarity_score` (number, required)
    Similarity score (0.0 to 1.0)

  - `companies.market_benchmarks.spend_benchmarks` (object)
    IT spend benchmarks against peer group

  - `companies.market_benchmarks.spend_benchmarks.it_spend_percentile` (integer)
    Percentile rank for IT spend vs peers

  - `companies.market_benchmarks.spend_benchmarks.peer_median_spend` (integer)
    Median IT spend among peers

  - `companies.market_benchmarks.spend_benchmarks.spend_per_employee` (integer)
    IT spend per employee

  - `companies.market_benchmarks.spend_benchmarks.spend_per_employee_percentile` (integer)
    Percentile rank for spend per employee vs peers

  - `companies.market_benchmarks.spend_benchmarks.spend_vs_peer_median` (number)
    Ratio of spend to peer median (e.g. 1.2 = 20% above median)

  - `companies.market_benchmarks.technology_benchmarks` (object)
    Technology stack benchmarks against peer group

  - `companies.market_benchmarks.technology_benchmarks.cloud_adoption_percentile` (integer)
    Percentile rank for cloud adoption vs peers

  - `companies.market_benchmarks.technology_benchmarks.modern_stack_score` (integer)
    Modern stack score vs peers (reserved for future use)

  - `companies.market_benchmarks.technology_benchmarks.peer_median_products` (integer)
    Median product count among peers

  - `companies.market_benchmarks.technology_benchmarks.security_stack_percentile` (integer)
    Percentile rank for security stack vs peers (reserved for future use)

  - `companies.market_benchmarks.technology_benchmarks.total_products_percentile` (integer)
    Percentile rank for total products vs peers

  - `companies.mentions` (object)
    Mentions data

  - `companies.mentions.count` (integer)
    Total count of mentions

  - `companies.mentions.records` (array)
    Array of mention records

  - `companies.mentions.records.country_code` (string)
    Country code (when granularity is country)

  - `companies.mentions.records.first_verified_date` (string)
    First verified date

  - `companies.mentions.records.intensity` (integer)
    Mention intensity (distinct days detected)

  - `companies.mentions.records.last_verified_date` (string)
    Last verified date

  - `companies.mentions.records.mention_attribute_ids` (array)
    Mention attribute IDs

  - `companies.mentions.records.mention_attributes` (array)
    Mention attribute names

  - `companies.mentions.records.mention_category_id` (string)
    Mention category ID (hex-encoded)

  - `companies.mentions.records.mention_category_name` (string)
    Mention category name

  - `companies.mentions.records.mention_description` (string)
    Mention product description

  - `companies.mentions.records.mention_id` (integer)
    Mention product ID

  - `companies.mentions.records.mention_name` (string)
    Mention product name

  - `companies.mentions.records.mention_recency` (integer)
    Mention recency signal

  - `companies.spend` (object)
    Spend data

  - `companies.spend.all` (array)
    Array of spend records

  - `companies.spend.all_count` (integer)
    Total count of spend records

  - `companies.statistics` (object)
    Aggregated summary statistics across tech stack, spend, contracts, and employees

  - `companies.statistics.computed_at` (string)
    When statistics were computed

  - `companies.statistics.contract_summary` (object)
    Summary statistics for a company's contracts

  - `companies.statistics.contract_summary.average_contract_length_months` (integer)
    Average contract length in months

  - `companies.statistics.contract_summary.average_contract_value` (integer)
    Average contract value

  - `companies.statistics.contract_summary.total_active_contracts` (integer)
    Total active contracts

  - `companies.statistics.contract_summary.total_contract_value` (integer)
    Total value of all contracts

  - `companies.statistics.contract_summary.upcoming_renewals_30d` (integer)
    Contracts renewing in next 30 days

  - `companies.statistics.contract_summary.upcoming_renewals_90d` (integer)
    Contracts renewing in next 90 days

  - `companies.statistics.employee_summary` (object)
    Summary statistics for organization employees

  - `companies.statistics.employee_summary.decision_makers_identified` (integer)
    Number of decision makers identified

  - `companies.statistics.employee_summary.departments_mapped` (integer)
    Number of departments identified

  - `companies.statistics.employee_summary.total_local_employees` (integer)
    Total employees at this location

  - `companies.statistics.spend_summary` (object)
    Summary statistics for a company's IT spend

  - `companies.statistics.spend_summary.category_count` (integer)
    Number of spend categories

  - `companies.statistics.spend_summary.currency` (string)
    Currency code (always USD)

  - `companies.statistics.spend_summary.spend_efficiency_score` (integer)
    Spend efficiency score (0-100)

  - `companies.statistics.spend_summary.top_category` (string)
    Category with highest spend

  - `companies.statistics.spend_summary.top_category_spend` (integer)
    Spend in top category

  - `companies.statistics.spend_summary.total_it_spend` (integer)
    Total estimated IT spend

  - `companies.statistics.spend_summary.yoy_growth_rate` (number)
    Year-over-year spend growth rate (decimal, e.g. 0.15 = 15%)

  - `companies.statistics.tech_stack_summary` (object)
    Summary statistics for a company's technology stack

  - `companies.statistics.tech_stack_summary.by_category` (array)
    Product distribution by category (top 20)

  - `companies.statistics.tech_stack_summary.by_category.category_name` (string, required)
    Category name

  - `companies.statistics.tech_stack_summary.by_category.percentage` (number)
    Percentage of total products

  - `companies.statistics.tech_stack_summary.by_category.product_count` (integer, required)
    Number of products in this category

  - `companies.statistics.tech_stack_summary.deployment_distribution` (object)
    Distribution of products by deployment model

  - `companies.statistics.tech_stack_summary.deployment_distribution.cloud` (integer)
    Number of cloud products

  - `companies.statistics.tech_stack_summary.deployment_distribution.cloud_percentage` (number)
    Percentage of cloud products

  - `companies.statistics.tech_stack_summary.deployment_distribution.hybrid` (integer)
    Number of hybrid products

  - `companies.statistics.tech_stack_summary.deployment_distribution.on_premise` (integer)
    Number of on-premise products

  - `companies.statistics.tech_stack_summary.total_categories` (integer)
    Total unique categories

  - `companies.statistics.tech_stack_summary.total_products` (integer)
    Total installed products

  - `companies.statistics.tech_stack_summary.total_vendors` (integer)
    Total unique vendors

  - `companies.statistics.tech_stack_summary.vendor_concentration` (object)
    Vendor concentration metrics

  - `companies.statistics.tech_stack_summary.vendor_concentration.concentration_level` (string)
    Overall concentration level
    Enum: "high", "medium", "low"

  - `companies.statistics.tech_stack_summary.vendor_concentration.top_5_vendors_percentage` (number)
    Percentage of products from top 5 vendors

  - `companies.statistics.tech_stack_summary.vendor_concentration.top_vendor` (string)
    Top vendor by product count

  - `companies.statistics.tech_stack_summary.vendor_concentration.top_vendor_product_count` (integer)
    Product count for top vendor

  - `companies.technographics` (object)
    Technographics data

  - `companies.technographics.installs` (array)
    Array of technology installs

  - `companies.technographics.installs.country_code` (string)

  - `companies.technographics.installs.product_category_id` (string)

  - `companies.technographics.installs.product_category_level1_name` (string)

  - `companies.technographics.installs.product_category_level2_name` (string)

  - `companies.technographics.installs.product_category_level3_name` (string)

  - `companies.technographics.installs.product_category_level4_name` (string)

  - `companies.technographics.installs.product_category_level5_name` (string)

  - `companies.technographics.installs.product_description` (string)

  - `companies.technographics.installs.product_id` (integer)

  - `companies.technographics.installs.product_last_verified_date` (string)

  - `companies.technographics.installs.product_name` (string)

  - `companies.technographics.installs.vendor_domain` (string)

  - `companies.technographics.installs.vendor_id` (integer)

  - `companies.technographics.installs.vendor_name` (string)

  - `companies.technographics.installs.intensity` (integer)

  - `companies.technographics.installs.location_count` (integer)

  - `companies.technographics.installs.product_first_verified_date` (string)

  - `companies.technographics.installs_count` (integer)
    Total count of installs

## Response 401:

  - `401` (unknown)
    Unauthorized

## Response 401 fields (application/json):

  - `errors` (array)

  - `errors.detail` (string, required)
    Example: The api key provided is not valid

  - `errors.source` (string)

  - `errors.title` (string, required)
    Example: Unauthorized

## Response 422:

  - `422` (unknown)
    Unprocessable Entity

## Response 422 fields (application/json):

  - `errors` (array, required)

  - `errors.detail` (string, required)
    Example: null value where string expected

  - `errors.source` (object, required)

  - `errors.source.pointer` (string, required)
    Example: /data/attributes/petName

  - `errors.title` (string, required)
    Example: Invalid value

## Response 503:

  - `503` (unknown)
    Service Unavailable

## Response 503 fields (application/json):

  - `errors` (array)

  - `errors.detail` (string, required)
    Example: Unable to verify credit availability. Please try again later. If the error persists, contact customersupport@hginsights.com.

  - `errors.source` (string)

  - `errors.title` (string, required)
    Example: Service unavailable