# Find Companies

The HG API offers two ways to find companies: **Match** and **Search**. Use the one that fits your situation.

## Match vs Search

|  | Match | Search |
|  --- | --- | --- |
| **Use when** | You have company names, domains, or countries and need to find their HG records | You want to discover companies based on criteria like industry, tech stack, or spend |
| **Input** | Up to 10 companies per request (name, domain, and/or country) | Filters (firmographics, installs, spend, intent) |
| **Output** | HG company records ranked by relevance | Paginated list of matching companies |
| **Credits** | No (requires positive balance) | No (requires positive balance) |
| **Endpoint** | `POST /companies/match` | `POST /companies/search` |


**Common workflow**: Use Match to resolve your existing company list into HG IDs, then use Enrich to pull their data. Use Search to discover new companies you don't already know about — Search returns minimal data (`id`, `name`, `domain`), so follow up with Enrich to get firmographics, technographics, or spend.

## Company Match

Resolve companies from partial information. Submit a company name, domain, and/or country, and get back ranked HG company matches.


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

### Request

Each company must include at least one of: `name`, `domain`, or `country`. The more fields you provide, the better the match quality.


```json
{
  "companies": [
    {
      "name": "Ford Motor Company",
      "domain": "ford.com",
      "country": "US"
    },
    {
      "domain": "google.com"
    },
    {
      "name": "Walmart",
      "country": "US"
    }
  ],
  "limit": 3
}
```

### Parameters

| Parameter | Type | Required | Description |
|  --- | --- | --- | --- |
| `companies` | array | Yes | Array of companies to match (1-10) |
| `companies[].name` | string | No* | Company name |
| `companies[].domain` | string | No* | Company domain (e.g., `ford.com`) |
| `companies[].country` | string | No* | Country name or ISO 3166 alpha-2 code (e.g., `US`) |
| `limit` | integer | No | Maximum matches per company (1-10, default: 1) |


*At least one of `name`, `domain`, or `country` is required per company.

### Response

Results are returned in the same order as the input, with matches sorted by relevance.


```json
{
  "companies": [
    {
      "name": "Ford Motor Company",
      "domain": "ford.com",
      "country": "US",
      "matches": [
        {
          "id": "E48EDEB162A5FBFDAF2DCF707079F8F",
          "name": "Ford Motor Company",
          "domain": "ford.com",
          "country": "US",
          "matched_on": ["name", "domain", "country"]
        }
      ]
    }
  ]
}
```

| Field | Description |
|  --- | --- |
| `id` | HG company ID — use this for enrichment |
| `name` | Matched company name |
| `domain` | Matched company domain |
| `country` | Matched company country |
| `matched_on` | Fields that contributed to the match (`name`, `domain`, `country`) |


### Match then Enrich

A common workflow is to match first, then enrich the results:


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

## Company Search

Find companies across the entire HG database using filters. You can filter by:

- **Firmographics** — country, employee count, revenue, industry, region, NAICS/SIC codes
- **Technology installs** — vendors, products, product categories
- **Spend** — spend categories with min/max range
- **Intent** — topics and signal score (LOW / MEDIUM / HIGH)
- **Corporate hierarchy** — global headquarters, domestic parent


All filter categories use AND logic — combine as many as you need.

Search returns minimal company data (`id`, `name`, `domain`). To get firmographics, technographics, or spend data for the results, pass the returned IDs to [`POST /companies/enrich`](/v2/guides/enrichment).


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

### Request

A search request requires `fields` (what to return) and `filters` (what to search for).


```json
{
  "fields": ["id", "name", "domain"],
  "filters": {
    "firmographics": {
      "country_codes": [
        {"ids": ["US"], "inclusion_method": "ANY_PRESENT"}
      ],
      "employees": {"min": 1000}
    }
  },
  "limit": 10
}
```

### Parameters

| Parameter | Type | Required | Description |
|  --- | --- | --- | --- |
| `fields` | array | Yes | Fields to return: `id`, `name`, `domain`, `domain_normalized` |
| `filters` | object | Yes | Filter criteria (see below) |
| `limit` | integer | No | Results per page (1-100, default: 10) |
| `offset` | integer | No | Skip results for pagination (default: 0) |
| `sorts` | array | No | Sort by `field` and `direction` (`ASC` or `DESC`) |


### Filters

Combine any of the following. All filter categories use AND logic.

#### Firmographics


```json
{
  "filters": {
    "firmographics": {
      "country_codes": [
        {"ids": ["US", "GB"], "inclusion_method": "ANY_PRESENT"}
      ],
      "employees": {"min": 1000, "max": 50000},
      "revenue": {"min": 100000000},
      "industries": [
        {"ids": [16], "inclusion_method": "ANY_PRESENT"}
      ]
    }
  }
}
```

You can also filter by `region_names`, `naics_codes`, and `sic_codes`.

#### Technology Installs


```json
{
  "filters": {
    "installs": {
      "vendors": [
        {"ids": [316], "inclusion_method": "ANY_PRESENT"}
      ],
      "products": [
        {"ids": [814], "inclusion_method": "ANY_PRESENT"}
      ],
      "product_categories": {
        "ids": ["63E88D6A88D45AB23B4CB4E71CB5A2E"],
        "inclusion_method": "ANY_PRESENT"
      }
    }
  }
}
```

#### Spend


```json
{
  "filters": {
    "spend": [
      {
        "categories": {
          "ids": ["3B36D42E7F8E60BE58BA4356B6AF40C"],
          "inclusion_method": "ANY_PRESENT"
        },
        "range": {"min": 1000000}
      }
    ]
  }
}
```

#### Intent

Available for all topics regardless of your plan.


```json
{
  "filters": {
    "intent": {
      "topics": {
        "ids": ["19861D3AC60455102792F87A33AF533F"],
        "inclusion_method": "ANY_PRESENT"
      },
      "signal_score": "MEDIUM"
    }
  }
}
```

Signal score values: `LOW`, `MEDIUM`, `HIGH`.

#### Corporate Hierarchy


```json
{
  "filters": {
    "corporate_hierarchy": {
      "is_global_headquarters": true,
      "is_domestic_parent": true
    }
  }
}
```

### Inclusion Methods

| Method | Description |
|  --- | --- |
| `ANY_PRESENT` | Matches if **any** of the specified IDs are present |
| `ALL_PRESENT` | Matches only if **all** specified IDs are present |
| `NONE_PRESENT` | Matches only if **none** of the specified IDs are present |


### Response


```json
{
  "companies": [
    {
      "id": "1698C53EBC888758570396E0334965C1",
      "name": "Walmart Inc.",
      "domain": "walmart.com"
    }
  ],
  "count": 1,
  "total": 4523
}
```

### Pagination

Use `limit` and `offset` to page through results. For the next page, increment `offset` by `limit`.

> **25,000 record limit:** To protect performance for all users, each search query returns at most 25,000 records (100 per page × 250 pages). The `total` in the response reflects the true match count — if it exceeds 25,000, add filters to retrieve targeted segments. Combine firmographic, install, and intent filters to stay under the limit. Company Search does not consume credits, but requires a positive balance — see [Credits and Usage](/v2/guides/credits-and-usage).



```json
{
  "fields": ["id", "name", "domain"],
  "filters": { ... },
  "limit": 100,
  "offset": 100
}
```

### Full Example

US companies with 5,000+ employees that use Salesforce:


```json
{
  "fields": ["id", "name", "domain"],
  "filters": {
    "firmographics": {
      "country_codes": [
        {"ids": ["US"], "inclusion_method": "ANY_PRESENT"}
      ],
      "employees": {"min": 5000}
    },
    "installs": {
      "vendors": [
        {"ids": [316], "inclusion_method": "ANY_PRESENT"}
      ]
    }
  },
  "sorts": [{"field": "name", "direction": "ASC"}],
  "limit": 25
}
```

## Tips

- Use the **Catalog API** to look up IDs for vendors, products, categories, industries, and intent topics
- Neither **Match** nor **Search** consumes credits, but both require a positive balance
- Provide more fields to Match for better accuracy — name + country is more precise than name alone
- Start Search with broad filters and narrow down — the `total` field tells you how many companies match