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.
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:
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.
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.
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.
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.
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.
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.
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.
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.
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 header and specify a compression method, like gzip.
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
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 |
Company Info Request
A unique hexadecimal identifier for the desired field.
A unique hexadecimal identifier for the desired field.
A unique hexadecimal identifier for the desired field.
A list of data points to be returned in the API response.
curl -i -X POST \
https://api.hginsights.com/data-api/v1/company/firmographic \
-H 'Authorization: YOUR_API_KEY_HERE' \
-H 'Content-Type: application/json' \
-d '{
"company_id": "1698C53EBC888758570396E0334965C1",
"fields": [
"company_id",
"company_name",
"domain_name",
"domain_name_normalized",
"company_level",
"city_name",
"state_name",
"postal_code",
"country_name",
"country_code",
"continent_name",
"subcontinent_name",
"geopolitical_name",
"industry_id",
"industry_name",
"naics_code",
"naics_name",
"sic_codes",
"sic_names",
"revenue_total",
"revenue_band",
"employees_total",
"employees_band",
"it_spend",
"forbes_2000_rank",
"fortune_500_rank",
"global_hq_company_name",
"global_hq_domain_name",
"global_hq_domain_name_normalized",
"global_hq_hg_id",
"global_hq_city_name",
"global_hq_state_name",
"global_hq_postal_code",
"global_hq_country_name",
"global_hq_country_code",
"global_hq_subcontinent_name",
"global_hq_continent_name",
"global_hq_geopolitical_name",
"global_hq_employees_band",
"global_hq_revenue_band",
"global_hq_industry_id",
"global_hq_industry_name",
"global_hq_naics_code",
"global_hq_naics_name",
"global_hq_sic_codes",
"global_hq_sic_names",
"global_hq_forbes_2000_rank",
"global_hq_fortune_500_rank"
]
}'{ "company_name": "string", "domain_name": "string", "domain_name_normalized": "string", "hg_id": "string", "naics_name": "string", "global_hq_sic_codes": [ "string" ], "global_hq_country_code": "string", "naics_code": "string", "revenue_total": 0, "fortune_500_rank": 1, "global_hq_country_name": "string", "global_hq_industry_name": "string", "global_hq_city_name": "string", "subcontinent_name": "string", "state_name": "string", "company_level": "string", "country_code": "string", "global_hq_continent_name": "string", "global_hq_domain_name": "string", "employees_band": "string", "global_hq_employees_band": "string", "global_hq_revenue_band": "string", "sic_codes": [ "string" ], "global_hq_state_name": "string", "industry_id": 0, "global_hq_fortune_500_rank": 1, "industry_name": "string", "global_hq_naics_name": "string", "postal_code": "string", "global_hq_geopolitical_name": "string", "employees_total": 0, "geopolitical_name": "string", "global_hq_hg_id": "string", "global_hq_industry_id": 0, "global_hq_subcontinent_name": "string", "revenue_band": "string", "country_name": "string", "forbes_2000_rank": 1, "global_hq_domain_name_normalized": "string", "it_spend": 0, "global_hq_sic_names": [ "string" ], "global_hq_forbes_2000_rank": 1, "global_hq_company_name": "string", "continent_name": "string", "sic_names": [ "string" ], "global_hq_naics_code": "string", "global_hq_postal_code": 0, "city_name": "string" }
Company FAI Request
List of fields to be selected.
Filters to be used to narrow down the functional area intelligence data to return.
A unique hexadecimal identifier for the desired field.
A unique hexadecimal identifier for the desired field.
A unique hexadecimal identifier for the desired field.
Return functional area intelligence records which are based on the provided department ids.
A unique hexadecimal identifier for the desired field.
A unique hexadecimal identifier for the desired field.
Return functional area intelligence records which are based on the provided product ids.
Return functional area intelligence records which are based on the provided department role ids.
curl -i -X POST \
https://api.hginsights.com/data-api/v1/company/functional_area_intelligence \
-H 'Authorization: YOUR_API_KEY_HERE' \
-H 'Content-Type: application/json' \
-d '{
"fields": [
"company_id",
"product_name",
"department_name",
"role_name"
],
"filters": {
"company_id": "0252985AFE13886BC6FFA5CEBD75F4FA",
"departments": [
"0D32106BCB6DE321930CF34574EA388C",
"3D4C638DA5F85D025963F99FE90B1B1A",
"2C329EF27D7F8CB49D656D5502B9E939"
],
"products": [
1150,
805,
25421,
826,
814,
562
],
"roles": [
"2AB3F09BBBA80FF82B8FD5916954C46A",
"2E6BAB5FC1C661EDD7A863D4DCA3415B",
"21C896AFCD34E446180844D91359246E",
"39FD56FC1455D4D872DB14F656225740"
]
}
}'{ "count": 0, "data": [ { … } ] }
Company Installs Request
List of fields to be selected.
Filter Product Installs by various criteria
A unique hexadecimal identifier for the desired field.
A unique hexadecimal identifier for the desired field.
A unique hexadecimal identifier for the desired field.
Inclusion filter object (using string names as IDs)
Inclusion filter object using integer IDs. Can filter ids by ANY_PRESENT or NONE_PRESENT inclusion methods
Inclusion filter object for use with hex encoded IDs. Can filter ids by ANY_PRESENT or NONE_PRESENT inclusion methods
Inclusion filter object using integer IDs. Can filter ids by ANY_PRESENT or NONE_PRESENT inclusion methods
curl -i -X POST \
https://api.hginsights.com/data-api/v1/company/installs \
-H 'Authorization: YOUR_API_KEY_HERE' \
-H 'Content-Type: application/json' \
-d '{
"fields": [
"product_id",
"product_name",
"vendor_name",
"product_last_verified_date",
"product_intensity",
"country_code"
],
"filters": {
"company_id": "1698C53EBC888758570396E0334965C1",
"country_codes": {
"ids": [
"US"
],
"inclusion_method": "ANY_PRESENT"
},
"product_attributes": {
"ids": [
222
],
"inclusion_method": "ANY_PRESENT"
},
"product_categories": {
"ids": [
"319D067B229178F03BCFA1DA4AC4DEDE"
],
"inclusion_method": "ANY_PRESENT"
},
"products": {
"ids": [
814
],
"inclusion_method": "ANY_PRESENT"
},
"vendors": {
"ids": [
316
],
"inclusion_method": "ANY_PRESENT",
"product_count": {
"max": 10,
"min": 1
}
}
},
"limit": 10,
"offset": 0,
"sorts": [
{
"direction": "DESC",
"field": "product_intensity"
}
]
}'{ "count": 0, "data": [ { … } ] }