# HG Insights API

# HG Insights API v2

The v2 API provides company enrichment with firmographics, spend, and technographics data.

## Authentication

All API requests require authentication using an API token.

### Getting Your Token

Contact your HG Insights account manager to obtain an API token.

### Using Your Token

Include your token in the `Authorization` header:

```bash
curl -X POST "https://api.hginsights.com/data-api/api/v2/companies/enrich" \
  -H "Authorization: YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"companies": {"ids": ["COMPANY_ID"]}}'
```

**Important:** Do not include "Bearer" prefix. Use the token directly.

### Token Format

v2 tokens start with `hg_v2_` followed by a random string.

Example: `hg_v2_K3WnkKrSyVD8yOoGTu1oqujB0f37eJuen1wvV2Ptg0`

---

## Company Enrichment

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

### Request Example

```json
{
  "companies": {
    "ids": ["1698C53EBC888758570396E0334965C1"]
  },
  "fields": ["firmographics", "spend", "technographics"]
}
```

### Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `companies.ids` | array | Yes | Company IDs (hex format, max 50) |
| `fields` | array | No | Data categories to return |

### Field Groups

- **firmographics** - Company info, location, revenue, employees
- **spend** - IT spend by category
- **technographics** - Technology installs

### Response Example

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

### Filtering Technographics

Filter installs by vendor, product, or category:

```json
{
  "companies": {"ids": ["..."]},
  "fields": ["technographics"],
  "filters": {
    "technographics": {
      "vendors": {"ids": [316]},
      "products": {"ids": [814]}
    }
  }
}
```

---

## Entitlements

Your API token includes entitlements that determine which data you can access.

### Basic Tier

**Firmographics:** Company name, URL, country, industry

**Spend:** Absolute spend amounts only

**Technographics:** Not included

### Full Tier

**Firmographics:** All 48 fields including revenue, employees, HQ info, rankings

**Spend:** Full details with category name, description, country

**Technographics:** Full install data with product, vendor, intensity, dates, categories

### Checking Your Entitlements

Make a request and check which fields are returned. Fields outside your entitlements will be omitted from the response.

### Upgrading

Contact your HG Insights account manager to upgrade your entitlements.


License: HG Insights terms of service

## Servers

```
https://api.hginsights.com
```

## Security

### authorization

Type: apiKey
In: header
Name: Authorization

## Download OpenAPI description

[HG Insights API](https://data-docs.hginsights.com/_bundle/v2/openapi.yaml)

## Companies

### Enrich Companies

 - [POST /data-api/v2/companies/enrich](https://data-docs.hginsights.com/v2/openapi/companies/enrich_companies.md): Unified endpoint to enrich company data with firmographics, spend, and technographics.

Select which data categories to include using the fields parameter. By default, all categories are included.
Filter technographics by categories, vendors, or products using the filters parameter.
Control pagination for both companies and nested technographics data.