# HG Insights API

# Overview of the HG Insights API

The HG Insights API provides comprehensive, data-driven insights into global technology markets and company landscapes.  This API can be leveraged to seamlessly integrate HG’s firmographic and technographic data into platforms and internal processes.

Today, the API allows you to search our database of entities, understand our catalog of filters and products, and enrich firmographic and install data by HG ID.

# Summary of Endpoints

## Data Catalog API

This endpoint is to help make sure you have the correctly formatted inputs in other calls.  This is an important resource that should be used to make sure parameters of other endpoints lead to successful calls.

Closely review the ReDoc/Swagger before making these calls, as some require additional inputs in the query parameters.

This catalog will generate lists for the following areas of the product:
- Countries
- FAI Departments
- FAI Roles
- Industries
- Intent Buyers Journey
- Intent Context Types
- Intent Topics
- NAICS 2012
- Product Attributes
- Product Categories
- Products
- SIC
- Spend Categories
- States
- Vendors

[Data Catalog](/openapi/catalog)

## Company Match API

This endpoint allows you to find entities in our dataset by name, country and/or URL.

Some entities can return a number of records back due to areas of deep location granularity in our data set.  As a result, we allow you to return between 1 and 10 possible matches based on your input.

This endpoint will return the HG ID, Name and URL back to you for matching records.  HG ID will be an important parameter in firmographic and install endpoints.

[Company Match API](/openapi/company/find_companies)

## Company Search API

This endpoint allows you to find companies based on our wide variety of search criteria.

We’ll return back to you the count of companies that match your criteria, as well as an array of Name, Domain, Domain Normalized and HG ID.  The array will be limited based on the value set in the request.  HG ID will be an important parameter in firmographic and install endpoints.

Pay careful attention to the request body scheme to ensure a successful call.  We highly recommend consulting the data catalog endpoint for help exploring options and selecting the right syntax.

[Company Search API](/openapi/company/search_companies)

## Company Firmographics API

This endpoint allows the user to retrieve firmographic information about a company.  Response will cover all fields available in the Platform today, including firmographics for both the target company and the GHQ.

An HG ID must be included in the parameter for this call to be successful, and the call will return data for that single HG ID.

[Company Firmographics API](/openapi/company/company_info)

## Company Installs API

This endpoint allows the user to retrieve product install information about a company.

Filter your request by specific product datapoints relating to the id, name, vendor and category details, along with localization of the install.

An HG ID must be included in the parameter for this call to be successful, and the call will return data for that single HG ID.

[Company Installs API](/openapi/company/company_installs)

## Spend API

This endpoint allows the user to retrieve IT Spend Budget data about a company.

Requests can be filtered to only specific IT Spend Budget categories, or all categories can be returned in the call.

An HG ID must be included in the parameter for this call to be successful, and the call will return data for that single HG ID.

[Spend API](/openapi/company/company_spend)

## Functional Area Intelligence

HG Insights’ Functional Area Intelligence solution predicts where detected technologies are used on both a departmental and location-specific level within an organization. Given a product in a department, we will return top locations where a Decision Maker or Influencer is present.

An HG ID, product(s) and department(s) must be included in the parameter for this call to be successful, you may also optionally include roles to further target the returned data. The call will return data for that single HG ID.

[Functional Area Intelligence API](/openapi/company/company_fai)

## Intent API

HG Contextual Intent is a solution designed for companies looking to leverage the power of customer buying patterns. This intent data is then contextualized with each company’s technographic profile to provide refined insights that support laser-focused company targeting.

A HG ID must be included in the parameter for this call to be successful, and the call will return data for that single HG ID. Requests can be filtered to only specific Intent topics, or all provisioned topics can be returned in the call. Available intent topics are limited to those provisioned to your organization.

# API Structure + Base URL

The API is structured around REST commands with HTTPS response codes to indicate either successful calls or errors produced.  Responses are all JSON objects.

When making API requests in URL, you must do so over HTTPS - calls made over HTTP will fail.

# Note: Configuration for Large Data Transfer

Some endpoints, especially the ones inside our Data Catalog can return a lot of data. To reduce the data transfer and increase response time, the client should use the [Content-Encoding](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Encoding) header and specify a compression method, like gzip.

# Tokens & Authentication

To access our data, you will need a token - this is a small piece of code that verifies a user or application to access an API.  This token is needed for all API endpoints.

**Does the token rotate?:** This token will be refreshed periodically and should be used in the request header to authenticate the request.

**How to Obtain a Token:** This token will be supplied to you via your CSM.

**Security Best Practices:** Keep your API token confidential and regenerate tokens if compromised.  Use HTTPS for all API requests

# API Errors

## Error Codes

The API uses standard HTTP status codes to indicate the success or failure of a request.

| Code | Description | Notes |
|------|-------------|-------|
| 200  | OK          |       |
| 401  | Unauthorized | Probably a missing token or an invalid token |
| 404  | Not found | The requested resource was not found |
| 422 | Unprocessable Entity | Most likely the request body is invalid because of missing or invalid parameters validated by the Open API Spec |


## Error messages

The error messages follow always the same pattern for syntax errors:

```json
{
  "errors": [
    {
      "title": "Invalid request",
      "detail": "The request is invalid",
      "source": {
        "pointer": "/data/attributes/first-name"
      }
    }
  ]
}
```


License: HG Insights terms of service

## Servers

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

Variables:

## Security

### authorization

Type: apiKey
In: header
Name: Authorization

## Download OpenAPI description

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

## Catalog

### List countries

 - [GET /data-api/v1/catalog/countries](https://data-docs.hginsights.com/openapi/geography/list_countries.md): List all countries

### List states

 - [GET /data-api/v1/catalog/states](https://data-docs.hginsights.com/openapi/geography/list_states.md): List all states

### List industries

 - [GET /data-api/v1/catalog/industries](https://data-docs.hginsights.com/openapi/industry/list_industries.md): List all industries

### List NAICS 2012

 - [GET /data-api/v1/catalog/naics2012](https://data-docs.hginsights.com/openapi/industry/list_naics2012.md): List all NAICS 2012

### List SIC US 1987

 - [GET /data-api/v1/catalog/sicus1987](https://data-docs.hginsights.com/openapi/industry/list_sicus1987.md): List all SIC US 1987

### List products attributes

 - [GET /data-api/v1/catalog/product_attributes](https://data-docs.hginsights.com/openapi/technographic/list_product_attributes.md): List all products attributes

### List product categories

 - [GET /data-api/v1/catalog/product_categories](https://data-docs.hginsights.com/openapi/technographic/list_product_categories.md): List all product categories

### List products

 - [GET /data-api/v1/catalog/products](https://data-docs.hginsights.com/openapi/technographic/list_products.md): List all products

### List vendors

 - [GET /data-api/v1/catalog/vendors](https://data-docs.hginsights.com/openapi/technographic/list_vendors.md): List vendors by search term

### List intent buyers journey

 - [GET /data-api/v1/catalog/intent_buyers_journey](https://data-docs.hginsights.com/openapi/intent/list_intent_buyers_journey.md): List all intent buyers journey

### List intent context types

 - [GET /data-api/v1/catalog/intent_context_types](https://data-docs.hginsights.com/openapi/intent/list_intent_context_types.md): List all intent context types

### List intent topics

 - [GET /data-api/v1/catalog/intent_topics](https://data-docs.hginsights.com/openapi/intent/list_intent_topics.md): List all intent topics

### List provisioned intent topics

 - [GET /data-api/v1/catalog/provisioned_intent_topics](https://data-docs.hginsights.com/openapi/intent/list_provisioned_intent_topics.md): List all intent topics which are provisioned for the user's organization

### List FAI departments

 - [GET /data-api/v1/catalog/fai_departments](https://data-docs.hginsights.com/openapi/fai/list_fai_departments.md): List all FAI departments

### List spend categories

 - [GET /data-api/v1/catalog/spend_categories](https://data-docs.hginsights.com/openapi/spend/list_spend_categories.md): List all spend categories

### List countries

 - [GET /data-api/v1/catalog/countries](https://data-docs.hginsights.com/openapi/catalog/list_countries.md): List all countries

### List FAI departments

 - [GET /data-api/v1/catalog/fai_departments](https://data-docs.hginsights.com/openapi/catalog/list_fai_departments.md): List all FAI departments

### List industries

 - [GET /data-api/v1/catalog/industries](https://data-docs.hginsights.com/openapi/catalog/list_industries.md): List all industries

### List intent buyers journey

 - [GET /data-api/v1/catalog/intent_buyers_journey](https://data-docs.hginsights.com/openapi/catalog/list_intent_buyers_journey.md): List all intent buyers journey

### List intent context types

 - [GET /data-api/v1/catalog/intent_context_types](https://data-docs.hginsights.com/openapi/catalog/list_intent_context_types.md): List all intent context types

### List intent topics

 - [GET /data-api/v1/catalog/intent_topics](https://data-docs.hginsights.com/openapi/catalog/list_intent_topics.md): List all intent topics

### List NAICS 2012

 - [GET /data-api/v1/catalog/naics2012](https://data-docs.hginsights.com/openapi/catalog/list_naics2012.md): List all NAICS 2012

### List products attributes

 - [GET /data-api/v1/catalog/product_attributes](https://data-docs.hginsights.com/openapi/catalog/list_product_attributes.md): List all products attributes

### List product categories

 - [GET /data-api/v1/catalog/product_categories](https://data-docs.hginsights.com/openapi/catalog/list_product_categories.md): List all product categories

### List products

 - [GET /data-api/v1/catalog/products](https://data-docs.hginsights.com/openapi/catalog/list_products.md): List all products

### List provisioned intent topics

 - [GET /data-api/v1/catalog/provisioned_intent_topics](https://data-docs.hginsights.com/openapi/catalog/list_provisioned_intent_topics.md): List all intent topics which are provisioned for the user's organization

### List SIC US 1987

 - [GET /data-api/v1/catalog/sicus1987](https://data-docs.hginsights.com/openapi/catalog/list_sicus1987.md): List all SIC US 1987

### List spend categories

 - [GET /data-api/v1/catalog/spend_categories](https://data-docs.hginsights.com/openapi/catalog/list_spend_categories.md): List all spend categories

### List states

 - [GET /data-api/v1/catalog/states](https://data-docs.hginsights.com/openapi/catalog/list_states.md): List all states

### List vendors

 - [GET /data-api/v1/catalog/vendors](https://data-docs.hginsights.com/openapi/catalog/list_vendors.md): List vendors by search term

## Geography

### List countries

 - [GET /data-api/v1/catalog/countries](https://data-docs.hginsights.com/openapi/geography/list_countries.md): List all countries

### List states

 - [GET /data-api/v1/catalog/states](https://data-docs.hginsights.com/openapi/geography/list_states.md): List all states

### List countries

 - [GET /data-api/v1/catalog/countries](https://data-docs.hginsights.com/openapi/catalog/list_countries.md): List all countries

### List states

 - [GET /data-api/v1/catalog/states](https://data-docs.hginsights.com/openapi/catalog/list_states.md): List all states

## Industry

### List industries

 - [GET /data-api/v1/catalog/industries](https://data-docs.hginsights.com/openapi/industry/list_industries.md): List all industries

### List NAICS 2012

 - [GET /data-api/v1/catalog/naics2012](https://data-docs.hginsights.com/openapi/industry/list_naics2012.md): List all NAICS 2012

### List SIC US 1987

 - [GET /data-api/v1/catalog/sicus1987](https://data-docs.hginsights.com/openapi/industry/list_sicus1987.md): List all SIC US 1987

### List industries

 - [GET /data-api/v1/catalog/industries](https://data-docs.hginsights.com/openapi/catalog/list_industries.md): List all industries

### List NAICS 2012

 - [GET /data-api/v1/catalog/naics2012](https://data-docs.hginsights.com/openapi/catalog/list_naics2012.md): List all NAICS 2012

### List SIC US 1987

 - [GET /data-api/v1/catalog/sicus1987](https://data-docs.hginsights.com/openapi/catalog/list_sicus1987.md): List all SIC US 1987

## Technographic

### List products attributes

 - [GET /data-api/v1/catalog/product_attributes](https://data-docs.hginsights.com/openapi/technographic/list_product_attributes.md): List all products attributes

### List product categories

 - [GET /data-api/v1/catalog/product_categories](https://data-docs.hginsights.com/openapi/technographic/list_product_categories.md): List all product categories

### List products

 - [GET /data-api/v1/catalog/products](https://data-docs.hginsights.com/openapi/technographic/list_products.md): List all products

### List vendors

 - [GET /data-api/v1/catalog/vendors](https://data-docs.hginsights.com/openapi/technographic/list_vendors.md): List vendors by search term

### Product installs

 - [POST /data-api/v1/company/installs](https://data-docs.hginsights.com/openapi/technographic/company_installs.md): Retrieve a list of technologies (and corresponding details) which a company has been detected to have used or 'installed'.

It's also possible to specify what fields from the API should be returned. By default, only some fields are returned.

### List products attributes

 - [GET /data-api/v1/catalog/product_attributes](https://data-docs.hginsights.com/openapi/catalog/list_product_attributes.md): List all products attributes

### List product categories

 - [GET /data-api/v1/catalog/product_categories](https://data-docs.hginsights.com/openapi/catalog/list_product_categories.md): List all product categories

### List products

 - [GET /data-api/v1/catalog/products](https://data-docs.hginsights.com/openapi/catalog/list_products.md): List all products

### List vendors

 - [GET /data-api/v1/catalog/vendors](https://data-docs.hginsights.com/openapi/catalog/list_vendors.md): List vendors by search term

### Product installs

 - [POST /data-api/v1/company/installs](https://data-docs.hginsights.com/openapi/company/company_installs.md): Retrieve a list of technologies (and corresponding details) which a company has been detected to have used or 'installed'.

It's also possible to specify what fields from the API should be returned. By default, only some fields are returned.

## Company

### Product installs

 - [POST /data-api/v1/company/installs](https://data-docs.hginsights.com/openapi/technographic/company_installs.md): Retrieve a list of technologies (and corresponding details) which a company has been detected to have used or 'installed'.

It's also possible to specify what fields from the API should be returned. By default, only some fields are returned.

### Company Intent

 - [POST /data-api/v1/company/intent](https://data-docs.hginsights.com/openapi/intent/company_intent.md): Returns intent data about the specified company.

It's also possible to specify what fields from the API should be returned. By default, only some fields are returned.

### Functional Area Intelligence

 - [POST /data-api/v1/company/functional_area_intelligence](https://data-docs.hginsights.com/openapi/fai/company_fai.md): Lookup functional area intelligence data for a company based on a company's ID, products, departments, and roles.

Results have an internal limit of 10.

It's also possible to specify what fields from the API should be returned. By default, only some fields are returned.

### Firmographic

 - [POST /data-api/v1/company/firmographic](https://data-docs.hginsights.com/openapi/companies/company_info.md): Returns detailed information about the specified company, including firmographics, installed technologies, and more.

Results are internally sorted by revenue (descending).

It's also possible to specify what fields from the API should be returned. By default, only some fields are returned.

### Firmographics

 - [POST /data-api/v1/company/firmographics](https://data-docs.hginsights.com/openapi/companies/companies_info.md): Returns detailed information about the specified companies, including firmographics, installed technologies, and more.

Results are internally sorted by revenue (descending).

It's also possible to specify what fields from the API should be returned. By default, only some fields are returned.

### Match Companies

 - [GET /data-api/v1/company/match](https://data-docs.hginsights.com/openapi/companies/find_companies.md): Match to HG companies by company name, country code and/or domain URL.

Limited to maximum of 10 companies and sorted by relevance and revenue.

### Search & Filter Companies

 - [POST /data-api/v1/company/search](https://data-docs.hginsights.com/openapi/companies/search_companies.md): Retrieve a list of companies and their corresponding details.

### Spend

 - [POST /data-api/v1/company/spend](https://data-docs.hginsights.com/openapi/spend/company_spend.md): Returns spend data about the specified company.

It's also possible to specify what fields from the API should be returned. By default, only some fields are returned.

### Firmographic

 - [POST /data-api/v1/company/firmographic](https://data-docs.hginsights.com/openapi/company/company_info.md): Returns detailed information about the specified company, including firmographics, installed technologies, and more.

Results are internally sorted by revenue (descending).

It's also possible to specify what fields from the API should be returned. By default, only some fields are returned.

### Firmographics

 - [POST /data-api/v1/company/firmographics](https://data-docs.hginsights.com/openapi/company/companies_info.md): Returns detailed information about the specified companies, including firmographics, installed technologies, and more.

Results are internally sorted by revenue (descending).

It's also possible to specify what fields from the API should be returned. By default, only some fields are returned.

### Functional Area Intelligence

 - [POST /data-api/v1/company/functional_area_intelligence](https://data-docs.hginsights.com/openapi/company/company_fai.md): Lookup functional area intelligence data for a company based on a company's ID, products, departments, and roles.

Results have an internal limit of 10.

It's also possible to specify what fields from the API should be returned. By default, only some fields are returned.

### Product installs

 - [POST /data-api/v1/company/installs](https://data-docs.hginsights.com/openapi/company/company_installs.md): Retrieve a list of technologies (and corresponding details) which a company has been detected to have used or 'installed'.

It's also possible to specify what fields from the API should be returned. By default, only some fields are returned.

### Company Intent

 - [POST /data-api/v1/company/intent](https://data-docs.hginsights.com/openapi/company/company_intent.md): Returns intent data about the specified company.

It's also possible to specify what fields from the API should be returned. By default, only some fields are returned.

### Match Companies

 - [GET /data-api/v1/company/match](https://data-docs.hginsights.com/openapi/company/find_companies.md): Match to HG companies by company name, country code and/or domain URL.

Limited to maximum of 10 companies and sorted by relevance and revenue.

### Search & Filter Companies

 - [POST /data-api/v1/company/search](https://data-docs.hginsights.com/openapi/company/search_companies.md): Retrieve a list of companies and their corresponding details.

### Spend

 - [POST /data-api/v1/company/spend](https://data-docs.hginsights.com/openapi/company/company_spend.md): Returns spend data about the specified company.

It's also possible to specify what fields from the API should be returned. By default, only some fields are returned.

## Intent

### List intent buyers journey

 - [GET /data-api/v1/catalog/intent_buyers_journey](https://data-docs.hginsights.com/openapi/intent/list_intent_buyers_journey.md): List all intent buyers journey

### List intent context types

 - [GET /data-api/v1/catalog/intent_context_types](https://data-docs.hginsights.com/openapi/intent/list_intent_context_types.md): List all intent context types

### List intent topics

 - [GET /data-api/v1/catalog/intent_topics](https://data-docs.hginsights.com/openapi/intent/list_intent_topics.md): List all intent topics

### List provisioned intent topics

 - [GET /data-api/v1/catalog/provisioned_intent_topics](https://data-docs.hginsights.com/openapi/intent/list_provisioned_intent_topics.md): List all intent topics which are provisioned for the user's organization

### Company Intent

 - [POST /data-api/v1/company/intent](https://data-docs.hginsights.com/openapi/intent/company_intent.md): Returns intent data about the specified company.

It's also possible to specify what fields from the API should be returned. By default, only some fields are returned.

### List intent buyers journey

 - [GET /data-api/v1/catalog/intent_buyers_journey](https://data-docs.hginsights.com/openapi/catalog/list_intent_buyers_journey.md): List all intent buyers journey

### List intent context types

 - [GET /data-api/v1/catalog/intent_context_types](https://data-docs.hginsights.com/openapi/catalog/list_intent_context_types.md): List all intent context types

### List intent topics

 - [GET /data-api/v1/catalog/intent_topics](https://data-docs.hginsights.com/openapi/catalog/list_intent_topics.md): List all intent topics

### List provisioned intent topics

 - [GET /data-api/v1/catalog/provisioned_intent_topics](https://data-docs.hginsights.com/openapi/catalog/list_provisioned_intent_topics.md): List all intent topics which are provisioned for the user's organization

### Company Intent

 - [POST /data-api/v1/company/intent](https://data-docs.hginsights.com/openapi/company/company_intent.md): Returns intent data about the specified company.

It's also possible to specify what fields from the API should be returned. By default, only some fields are returned.

## FAI

### List FAI departments

 - [GET /data-api/v1/catalog/fai_departments](https://data-docs.hginsights.com/openapi/fai/list_fai_departments.md): List all FAI departments

### Functional Area Intelligence

 - [POST /data-api/v1/company/functional_area_intelligence](https://data-docs.hginsights.com/openapi/fai/company_fai.md): Lookup functional area intelligence data for a company based on a company's ID, products, departments, and roles.

Results have an internal limit of 10.

It's also possible to specify what fields from the API should be returned. By default, only some fields are returned.

### List FAI departments

 - [GET /data-api/v1/catalog/fai_departments](https://data-docs.hginsights.com/openapi/catalog/list_fai_departments.md): List all FAI departments

### Functional Area Intelligence

 - [POST /data-api/v1/company/functional_area_intelligence](https://data-docs.hginsights.com/openapi/company/company_fai.md): Lookup functional area intelligence data for a company based on a company's ID, products, departments, and roles.

Results have an internal limit of 10.

It's also possible to specify what fields from the API should be returned. By default, only some fields are returned.

## Companies

### Firmographic

 - [POST /data-api/v1/company/firmographic](https://data-docs.hginsights.com/openapi/companies/company_info.md): Returns detailed information about the specified company, including firmographics, installed technologies, and more.

Results are internally sorted by revenue (descending).

It's also possible to specify what fields from the API should be returned. By default, only some fields are returned.

### Firmographics

 - [POST /data-api/v1/company/firmographics](https://data-docs.hginsights.com/openapi/companies/companies_info.md): Returns detailed information about the specified companies, including firmographics, installed technologies, and more.

Results are internally sorted by revenue (descending).

It's also possible to specify what fields from the API should be returned. By default, only some fields are returned.

### Match Companies

 - [GET /data-api/v1/company/match](https://data-docs.hginsights.com/openapi/companies/find_companies.md): Match to HG companies by company name, country code and/or domain URL.

Limited to maximum of 10 companies and sorted by relevance and revenue.

### Search & Filter Companies

 - [POST /data-api/v1/company/search](https://data-docs.hginsights.com/openapi/companies/search_companies.md): Retrieve a list of companies and their corresponding details.

### Firmographic

 - [POST /data-api/v1/company/firmographic](https://data-docs.hginsights.com/openapi/company/company_info.md): Returns detailed information about the specified company, including firmographics, installed technologies, and more.

Results are internally sorted by revenue (descending).

It's also possible to specify what fields from the API should be returned. By default, only some fields are returned.

### Firmographics

 - [POST /data-api/v1/company/firmographics](https://data-docs.hginsights.com/openapi/company/companies_info.md): Returns detailed information about the specified companies, including firmographics, installed technologies, and more.

Results are internally sorted by revenue (descending).

It's also possible to specify what fields from the API should be returned. By default, only some fields are returned.

### Match Companies

 - [GET /data-api/v1/company/match](https://data-docs.hginsights.com/openapi/company/find_companies.md): Match to HG companies by company name, country code and/or domain URL.

Limited to maximum of 10 companies and sorted by relevance and revenue.

### Search & Filter Companies

 - [POST /data-api/v1/company/search](https://data-docs.hginsights.com/openapi/company/search_companies.md): Retrieve a list of companies and their corresponding details.

## Spend

### List spend categories

 - [GET /data-api/v1/catalog/spend_categories](https://data-docs.hginsights.com/openapi/spend/list_spend_categories.md): List all spend categories

### Spend

 - [POST /data-api/v1/company/spend](https://data-docs.hginsights.com/openapi/spend/company_spend.md): Returns spend data about the specified company.

It's also possible to specify what fields from the API should be returned. By default, only some fields are returned.

### List spend categories

 - [GET /data-api/v1/catalog/spend_categories](https://data-docs.hginsights.com/openapi/catalog/list_spend_categories.md): List all spend categories

### Spend

 - [POST /data-api/v1/company/spend](https://data-docs.hginsights.com/openapi/company/company_spend.md): Returns spend data about the specified company.

It's also possible to specify what fields from the API should be returned. By default, only some fields are returned.