# Use the Catalog

The Catalog is HG's reference data: vendors, products, categories, attributes, and industry taxonomy codes. You'll mostly use it to look up the `ids` and `names` you pass into filters on [Enrich Companies](/v2/guides/enrichment#filtering-technographics), [Search or Match Companies](/v2/guides/find-companies), and [Score Companies](/v2/guides/scoring). None of these endpoints consume credits.

There are two ways to query it, and they're not interchangeable:

|  | `GET /catalog/*` | `POST /products/*/search`, `GET /industries/search` |
|  --- | --- | --- |
| **Use when** | You know roughly what you're looking for and just need an ID | You need to filter by more than one field at once, or get relevance-ranked results |
| **Filtering** | One partial-name match (`?name=`) | Multiple fields, AND-combined (name + vendor + category + attribute, etc.) |
| **Ranking** | None, results come back in no particular relevance order | Vendor and product search rank by relevance (exact > prefix > substring match) |
| **Pagination** | `limit` / `offset` query params | `limit` / `offset` in the request body, plus `sort` |


## Simple Lookups: `GET /catalog/*`

Every `/catalog/*` endpoint follows the same shape: `limit` (default 10), `offset` (default 0), and `name` for a case-insensitive partial match.

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

```json
{
  "data": [
    {"id": "376", "name": "Salesforce.com, Inc.", "domain": "https://salesforce.com"}
  ]
}
```

Available `/catalog/*` endpoints: `vendors`, `products`, `product_categories`, `product_attributes`, `industries`, `spend_categories`, `countries`, `states`, `naics2012`, `sicus1987`, `fai_departments`, `job_functions`, `job_seniorities`, `intent_topics`, `intent_context_types`, `intent_buyers_journey`.

Use these for a quick one-off lookup, like "what's the ID for Salesforce?", before passing the result into an enrich or search filter. See [Filter by ID](/v2/guides/enrichment#filter-by-id) for that workflow.

## Multi-Field Search: Products, Vendors, Categories, Attributes

When you need to filter by more than one field, or want relevance ranking, use the dedicated search endpoints instead. They're POST requests with a `filters` object, not a single query param.

### Search Products

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

```json
{
  "filters": {
    "product_name": "Salesforce",
    "category_name": "CRM",
    "has_install": true
  },
  "limit": 50,
  "sort": [{"field": "relevance"}]
}
```

| Filter | Description |
|  --- | --- |
| `product_name` | Partial match on product name |
| `product_description` | Partial match on product description |
| `vendor_id` / `vendor_ids` | Exact match on one vendor, or any of several. Mutually exclusive with each other. |
| `vendor_name` | Partial match on vendor name |
| `category_id` / `category_ids` | Exact match on one category, or any of several. Mutually exclusive with each other. |
| `category_name` | Partial match on category name |
| `attribute_ids` | Matches products with any of the given attribute IDs |
| `attribute_name` | Partial match on attribute name |
| `has_install` | Restrict to products with at least one company install |


All filters are AND-combined. Sort by `relevance`, `product_name`, `vendor_name`, `category_name`, or `last_verified_at`.

```json
{
  "count": 1,
  "products": [
    {
      "product_id": 22,
      "product_name": "Salesforce CRM",
      "product_description": "Salesforce CRM is a customer relationship platform...",
      "vendor_id": 376,
      "vendor_name": "Salesforce.com, Inc.",
      "category_id": "368B0C2D14F47CC1A7DB3BB7C2B41C7E",
      "category_name": "Customer Relationship Management Applications"
    }
  ]
}
```

### Search Vendors

```
POST /data-api/v2/products/vendors/search
```

```json
{
  "filters": {
    "vendor_name": "Salesforce",
    "has_products_with_installs": true
  },
  "include_products": true,
  "products_limit": 10
}
```

| Filter | Description |
|  --- | --- |
| `vendor_name` | Substring match, relevance-ranked (exact > prefix > substring) |
| `description` | Substring match on `vendor_company_description` |
| `vendor_id` | Exact match |
| `has_products_with_installs` | Restrict to vendors with at least one installed product |


Set `include_products: true` to get each vendor's top products (by install presence) attached inline, up to `products_limit` per vendor, instead of making a separate product search per vendor.

```json
{
  "count": 1,
  "data": [
    {
      "vendor_id": 376,
      "vendor_name": "Salesforce.com, Inc.",
      "vendor_company_id": "...",
      "vendor_company_description": "...",
      "vendor_url": "https://salesforce.com",
      "vendor_parent_id": 0,
      "product_count": 42,
      "products": [
        {"product_id": 22, "product_name": "Salesforce CRM"}
      ]
    }
  ]
}
```

`vendor_parent_id` is `0` for a top-level vendor, or the parent vendor's ID for a subsidiary brand.

### Search Categories

```
POST /data-api/v2/products/categories/search
```

```json
{
  "filters": {
    "category_name": "Customer Relationship",
    "has_category_installs": true
  }
}
```

| Filter | Description |
|  --- | --- |
| `category_name` | Partial match |
| `category_code` | Exact match |
| `tree_contains` | Partial match against the category's full tree path |
| `has_category_installs` | Restrict to categories with at least one install |


```json
{
  "count": 1,
  "categories": [
    {
      "category_id": "1B45A740FC4C3958BDF5957F142D6A7E",
      "category_name": "Customer Relationship Management Applications",
      "category_code": "SW049",
      "category_parent_id": "148EC4B995226416EBC8BE44C24D65E8",
      "category_name_tree": ["Software", "Enterprise Applications", "Enterprise Resource Planning Applications", "Customer Relationship Management Applications"],
      "category_id_tree": ["319D067B229178F03BCFA1DA4AC4DEDE", "0450D8C9CB5523C08C3684C31BF161C4", "148EC4B995226416EBC8BE44C24D65E8", "1B45A740FC4C3958BDF5957F142D6A7E"],
      "product_count": 1821
    }
  ]
}
```

`category_name_tree` and `category_id_tree` give you the full path from root category down to the matched one, useful for breadcrumbs or rolling up to a parent category.

### Search Attributes

```
POST /data-api/v2/products/attributes/search
```

```json
{
  "filters": {
    "attribute_name": "Cloud Computing"
  }
}
```

| Filter | Description |
|  --- | --- |
| `attribute_ids` | Matches any of the given IDs |
| `attribute_name` | Partial match |


## Industry Taxonomy: `GET /industries/search`

A separate endpoint for a separate kind of lookup: the crosswalk between HG's 23 industry buckets, NAICS 2012 (~2,200 codes), and SIC 1987 (~1,500 codes). Free text, exact codes, or both, across one taxonomy or all three at once.

```
GET /data-api/v2/industries/search
```

```bash
curl "https://api.hginsights.com/data-api/v2/industries/search?q=fintech&taxonomy=naics" \
  -H "Authorization: Bearer $HG_API_KEY"
```

| Parameter | Description |
|  --- | --- |
| `q` | Free-text search (min 2 chars). All-digit queries prefix-match codes. Comma-separated terms run as OR. Colloquial terms like "fintech" or "saas" are auto-expanded to the matching taxonomy terms. |
| `taxonomy` | Scope to `industry`, `naics`, or `sic`. Omit to search all three. |
| `limit` | Page size, 1-500 (default 50) |
| `offset` | Page offset, 0-10000 |
| `naics_leaf_only` | Only applies when `taxonomy=naics`. When true, returns only 6-digit leaf codes (the most specific level) instead of rollup codes. |


Every result row returns the full crosswalk, not just the taxonomy you searched:

```json
{
  "results": [
    {
      "matched_on": "naics",
      "industry": {"industry_id": 16, "industry_name": "Financial Services"},
      "naics": {"naics_code": "522110", "naics_name": "Commercial Banking", "hierarchy_level": "national_industry", "is_leaf": true},
      "sic": {"sic_code": "I6021", "sic_standard_code": "6021", "sic_name": "National Commercial Banks", "is_hg_extension": true}
    }
  ],
  "pagination": {"total": 1, "limit": 50, "offset": 0, "has_more": false, "offset_exceeds_total": false},
  "alias_expansions": [{"term": "fintech", "expanded_to": ["financial technology", "fintech"]}]
}
```

**Watch for HG-extended SIC codes.** `sic_code` can be a letter-prefixed HG extension (e.g. `I6021`) rather than a standard 4-digit SIC code. Use `sic_standard_code` (e.g. `6021`) when you need the real SIC-1987 code for a downstream system.

If a text query gets zero results, the response includes `suggestions`, up to 5 closest taxonomy names by spelling distance, instead of an empty array with nothing to go on.