# Enrich Companies

The enrichment endpoint returns firmographics, spend, and technographics data for companies.

## Use Cases

Use the company enrichment endpoint to:

- **Enrich CRM records**: Add firmographics, spend, and technology data to existing company records
- **Account planning**: Understand a prospect's tech stack and IT spending before outreach
- **Qualify leads**: Evaluate company size, revenue, and technology adoption for your sales pipeline
- **Competitive intelligence**: Analyze the technologies and IT investments of specific companies


## Endpoint

```
POST /data-api/v2/companies/enrich
```

## Preview Credit Cost

**Before calling** `/companies/enrich` **you can call** `/companies/enrich/estimate` **to check the credit cost.**

```
POST /data-api/v2/companies/enrich/estimate
```

Pass the same request body you'd send to `/companies/enrich`. No credits are consumed, no data is returned, it's just a cost preview.

**What the** `credits_estimate` **means:**

- **It's a ceiling, not a guarantee.** Actual charges may be lower if you've already pulled this data within your 12-month contract period.
- **It covers the full result set.** The estimate assumes you page through every result. If you stop after page 1, you only pay for page 1. Paging through the full set costs the same as fetching it all at once, pagination doesn't multiply the cost


See [Credits and Usage](/v2/guides/credits-and-usage#estimating-cost-before-you-call) for the full request and response schema.

## Request

You can enrich companies using either **HG IDs** or **domains**. The API supports **bulk enrichment** of up to 25 companies per request.

### Request by HG ID

```json
{
  "companies": {
    "ids": ["1698C53EBC888758570396E0334965C1"]
  },
  "fields": [
    "firmographics",
    "spend",
    "ai_spend",
    "technographics",
    "contracts",
    "ai_maturity",
    "cloud_maturity",
    "mentions",
    "statistics",
    "market_benchmarks"
  ]
}
```

**HG IDs** are unique identifiers assigned by HG Insights to each company in our database. These IDs are returned in API responses and ensure precise company matching.

### Request by Domain

```json
{
  "companies": {
    "domains": ["walmart.com", "example.com"]
  },
  "fields": [
    "firmographics",
    "spend",
    "ai_spend",
    "technographics",
    "contracts",
    "ai_maturity",
    "cloud_maturity",
    "mentions",
    "statistics",
    "market_benchmarks"
  ]
}
```

You can use company domains (e.g., `walmart.com`) to enrich companies without knowing their HG ID.

### Parameters

| Parameter | Type | Required | Description |
|  --- | --- | --- | --- |
| `companies.ids` | array | Yes* | HG company IDs (hex format, max 25) |
| `companies.domains` | array | Yes* | Company domains (e.g., example.com, max 25) |
| `fields` | array | Yes | Data categories to return |


*Either `ids` or `domains` is required, but not both.

The API accepts up to 25 companies per request. For enriching larger datasets, see [Bulk Enrich Companies](/v2/guides/bulk-enrichment).

### Field Groups

You can request specific data categories by including them in the `fields` array:

Field Group
Description
firmographics
Company information including name, domain, location, industry classification, revenue, employee counts, and HG rankings.
Key fields: 
name
, 
domain
, 
country_code
, 
employees_total
, 
revenue_total
, 
industry_name
, 
naics_code
, 
sic_codes
, 
fortune_500_rank
. Premium: 
company_level
, 
corporate_parent_id
, 
global_hq_*
.
spend
IT spending data organized by technology category.
Key fields: 
category_id
, 
category_name
, 
category_parent_id
, 
country_code
, 
spend
(USD).
ai_spend
IT spending specific to AI technology categories.
Same shape as 
spend
: 
category_id
, 
category_name
, 
category_parent_id
, 
country_code
, 
spend
(USD).
technographics
Technology installation data including products, vendors, usage intensity, and installation dates.
Key fields: 
product_id
, 
product_name
, 
vendor_id
, 
vendor_name
, 
product_category_level1_name
–
level5_name
, 
product_last_verified_date
. Premium: 
intensity
, 
location_count
, 
product_first_verified_date
.
contracts
Contract records for the company.
Key fields: 
count
, 
records[]
. Requires the contracts entitlement.
ai_maturity
Composite AI maturity scoring for the company.
Key fields: 
ai_maturity_score
, 
ai_maturity_rank
, 
ai_maturity_6m_delta
, 
ai_product_use
, 
data_maturity_score
, 
data_maturity_level
, 
genai_intent_score
, 
cloud_intensity
.
cloud_maturity
Cloud adoption and stack composition data.
Key fields: 
current_products_used_cloud_percent
, 
new_products_used_cloud_percent
, 
cloud_stack_percent_change
, 
aws_products_count
, 
azure_products_count
, 
gcp_products_count
.
mentions
Public mentions of the company across tracked sources.
Key fields: 
mention_id
, 
mention_category_name
, 
mention_description
, 
intensity
, 
first_verified_date
, 
last_verified_date
.
statistics
Aggregated summary statistics across tech stack, spend, contracts, and employees.
Key fields: 
tech_stack_summary
, 
spend_summary
, 
contract_summary
, 
employee_summary
.
market_benchmarks
Peer-group percentile benchmarking against similar organizations.
Key fields: 
peer_group
, 
spend_benchmarks
, 
technology_benchmarks
, 
similar_organizations[]
.
**Important**: The data returned by the company enrichment endpoint depends on your plan's entitlements. You can only access the field groups included in your subscription. Contact your account manager if you need access to additional data categories.

## Response

```json
{
  "companies": [
    {
      "id": "1698C53EBC888758570396E0334965C1",
      "firmographics": {
        "name": "Walmart Inc.",
        "domain": "walmart.com",
        "country_code": "US",
        "employees_total": 2100000,
        "revenue_total": 680985000000
      },
      "spend": {
        "all": [...],
        "all_count": 135
      },
      "technographics": {
        "installs": [...],
        "installs_count": 5900
      }
    }
  ]
}
```

## Filtering Technographics

You can narrow down technographics results by vendor, product, or product category. Filters support both **names** and **IDs** — use names for simplicity, or IDs if you already have them from the Catalog API.

### Filter by Name

The easiest way to filter. Just pass the vendor, product, or category name directly.

**Filter by vendor** (only Salesforce technologies):

```json
{
  "companies": {"domains": ["walmart.com"]},
  "fields": ["technographics"],
  "filters": {
    "technographics": {
      "vendors": {"names": ["Salesforce"]}
    }
  }
}
```

**Filter by product** (only Salesforce CRM):

```json
{
  "companies": {"domains": ["walmart.com"]},
  "fields": ["technographics"],
  "filters": {
    "technographics": {
      "products": {"names": ["Salesforce CRM"]}
    }
  }
}
```

**Filter by product category** (all CRM products, any vendor):

```json
{
  "companies": {"domains": ["walmart.com"]},
  "fields": ["technographics"],
  "filters": {
    "technographics": {
      "categories": {"names": ["CRM"]}
    }
  }
}
```

**Combine filters** (Salesforce and Microsoft products in the CRM category):

```json
{
  "companies": {"domains": ["walmart.com"]},
  "fields": ["technographics"],
  "filters": {
    "technographics": {
      "vendors": {"names": ["Salesforce", "Microsoft"]},
      "categories": {"names": ["CRM"]}
    }
  }
}
```

### Filter by ID

If you need exact matching or are building programmatic integrations, you can use IDs instead. Look up IDs from the Catalog API — all catalog endpoints support `?name=` for searching, plus `limit` and `offset` for pagination. See [Use the Catalog](/v2/guides/catalog) for the full set of lookup and search endpoints, including multi-field filtering by vendor + category + attribute at once.

```bash
# Find a vendor ID
curl "https://api.hginsights.com/data-api/v2/catalog/vendors?name=Salesforce" \
  -H "Authorization: Bearer $HG_API_KEY"

# Find a product ID
curl "https://api.hginsights.com/data-api/v2/catalog/products?name=Salesforce%20CRM" \
  -H "Authorization: Bearer $HG_API_KEY"

# Find a category ID
curl "https://api.hginsights.com/data-api/v2/catalog/product_categories?name=CRM" \
  -H "Authorization: Bearer $HG_API_KEY"
```

Then pass the IDs in your filter:

```json
{
  "companies": {"domains": ["walmart.com"]},
  "fields": ["technographics"],
  "filters": {
    "technographics": {
      "vendors": {"ids": [316]},
      "categories": {"ids": ["63E88D6A88D45AB23B4CB4E71CB5A2E"]}
    }
  }
}
```

### Filter by Last Verified Date

Use the `last_verified` filter to only return technologies verified after a specific date. This is useful for identifying technologies that are still actively installed rather than stale detections.

```json
{
  "companies": {"domains": ["walmart.com"]},
  "fields": ["technographics"],
  "filters": {
    "technographics": {
      "last_verified": {"after": "2026-01-01"}
    }
  }
}
```

You can combine `last_verified` with other filters. For example, only Salesforce products verified in the last 90 days:

```json
{
  "companies": {"domains": ["walmart.com"]},
  "fields": ["technographics"],
  "filters": {
    "technographics": {
      "vendors": {"names": ["Salesforce"]},
      "last_verified": {"after": "2026-01-15"}
    }
  }
}
```