- How do I authenticate and generate API tokens?
- Is my API key tied to my user account or my org?
- Do I need a subscription to use the API?
- Can I test the API before writing any code?
- Why am I getting a 401 on a field group?
- Where can I view detailed API documentation, field lists, and example requests/responses?
- What data fields and objects are available for export through the API?
- How many companies can I enrich in one request?
- Is bulk export supported? What's the maximum batch size?
- What's the difference between Company Search and Company Match?
- Can I preview the cost of a request before running it?
- Are there best practices for handling large data sets and optimizing data pulls via the API?
- What are the rate limits (requests per minute/hour/day) for the API?
- Are there timeouts or restrictions on consecutive API batch pulls?
- What happens if I exceed the rate limit?
- What does this error mean?
- Why am I getting a 422?
- Why am I getting a 402?
- Why is a company returning no data?
- Can segments created in the UI be accessed and exported programmatically via the API?
- Is there a difference in API capabilities or limits between the main platform and MCP?
- Can I ask Claude to help me write the right API request?
- Who can I contact for support if I encounter issues or need higher volume access?
Log in to admin.hginsights.com as an admin, go to Settings > API Keys, and click Create API Key. API keys start with hg_v2_. To authenticate, include your key in the Authorization header of every request as a Bearer token: Authorization: Bearer YOUR_API_KEY. See Authentication.
Your org, not an individual user. API access is API-key based and managed at the org level — so if the person who created the key leaves, the key stays active and doesn't get deactivated.
Yes. You need an active subscription to HG Insights with credits included. If you don't have one, contact your account manager or reach out at hginsights.com.
Yes — use the Try it button on any endpoint in the API Reference, or follow the Quickstart to make your first call with curl in under two minutes.
The data returned by /companies/enrich depends on your plan's entitlements — you can only request field groups included in your subscription. Contact your account manager to add access, or remove the restricted field group from your request. See Error Handling.
Credits are based on what data is returned, not the number of requests. You're only charged the first time you enrich a company within your 12-month contract period — re-enriching the same company is free, with one exception: /intent/enrich charges credits on every call since intent data changes frequently. See Credits and Usage.
No. Since credits are based on what data is returned, if a request finds nothing for a company, you're not charged for it. See Credits and Usage.
Call GET /data-api/v2/credits, or check the Credit Dashboard in the HG Admin Portal under Settings > Credits Usage. See Credits and Usage.
The full API Reference documents every endpoint, parameter, and response schema, with a live Try-it console and example requests/responses on each operation.
/companies/enrich returns firmographics, technographics, spend, AI spend, AI maturity, cloud maturity, contracts, mentions, statistics, and market benchmarks — request only the field groups you need. Intent signals, corporate hierarchy, functional area intelligence, contracts, and contacts are available through their own dedicated endpoints. See Understanding HG Data for what each category contains, or the full field group table in Enrich Companies.
Up to 25 per call to /companies/enrich or /companies/score. For larger datasets, batch in groups of 25 — see Bulk Enrich Companies.
Yes. /companies/enrich and /companies/score accept up to 25 companies per request. For larger lists, split into batches of 25 — see Bulk Enrich Companies.
Match resolves companies you already know (by name, domain, or country) into HG IDs — up to 10 per request. Search discovers companies you don't already know using filters like industry, tech stack, or spend. See Search or Match Companies.
Yes. Most endpoints that consume credits have a matching /estimate endpoint — send the same request body and get back the credit cost without consuming credits or returning data. See Credits and Usage.
Batch requests — /companies/enrich and /companies/score accept up to 25 companies per call, and batching counts as a single request against the rate limit regardless of how many companies you include. For datasets larger than 25, split into batches — see Bulk Enrich Companies. Preview credit cost with the /estimate endpoints before running large jobs, and implement backoff on 429 responses — see Rate Limiting.
It depends on your plan: Sandbox is 2 requests/second and 1,000/day, Standard is 25 requests/second and 50,000/day, and Enterprise is 200 requests/second with no daily cap. See Rate Limiting.
There's no separate timeout or cooldown on consecutive batch pulls — your plan's per-second limit applies continuously, and the rate limit is per request, not per company. An endpoint that accepts multiple companies per call (e.g., /companies/enrich with up to 25 companies) counts as one request, so batching is the most efficient way to run consecutive pulls without hitting the limit. The one fair use limit to know: /companies/search caps results at 25,000 per query — use filters to segment larger pulls into multiple queries. See Rate Limiting and Search or Match Companies.
You'll get a 429 Too Many Requests response. Check the x-ratelimit-reset header to see how long to wait before retrying. See Rate Limiting.
All errors follow a consistent structure with a title, detail, and optional source.pointer identifying the problem field. See the full list of HTTP status codes and common error scenarios in Error Handling.
422 means request validation failed — usually a missing required parameter, an invalid value, or an array exceeding its max size (like more than 25 company IDs). Check source.pointer in the error response to find the exact field. See Error Handling.
402 means your organization has no credits available — they're exhausted, your contract has expired, or there's no active credit allocation. No credits are consumed by the rejected request. Check your balance and contract dates with GET /credits, then contact your account manager to add credits. See Error Handling.
Either the company isn't tracked in HG's database, or your filters are too strict. Try loosening your filters, or check your entitlements if you're missing an entire field group. See the Quickstart troubleshooting section.
Not directly today. Recreate the same filters you'd use in the Platform with POST /companies/search, then pass the matching companies to POST /companies/enrich for the data you need. Credit cost works the same as it does in the Platform. See Search or Match Companies and Enrich Companies.
No — MCP is a wrapper on top of the HG API. When you invoke an MCP tool, it makes the corresponding API request under the hood. The API offers the same search and enrich capabilities available in the Platform. See Explore the API.
Yes. Give Claude (or any LLM) the docs URL or the OpenAPI spec directly, describe what you're trying to do, and it will generate the correct JSON body, curl command, or code in your language. See Explore the API.
Email customersupport@hginsights.com for support issues, feedback, or data gaps — include the exact request and response so we can reproduce the issue. For higher rate limits or volume needs, contact your HG Insights account manager.