# Explore the API

There are several ways to explore and test the HG API — from AI-powered tools to visual clients. Pick the one that fits your workflow.

## Try-it Console

The fastest way to test. Every endpoint in these docs has a built-in **Try-it** console on the right side of the page.

1. Navigate to any endpoint (e.g., Enrich Companies)
2. Click **Try it**
3. Enter your API key in the Authorization header
4. Edit the request body
5. Click **Send**


You'll see the response right in the browser — no setup needed. Great for quick tests and verifying filter syntax.

## Claude Code

[Claude Code](https://claude.ai/claude-code) is an AI coding assistant that runs in your terminal. It can call the HG API directly, iterate on requests, and help you build integrations.

### Setup

Add your API key as an environment variable:


```bash
export HG_API_KEY="your_api_key_here"
```

### Example prompts

Once Claude Code is running, you can ask it to explore the API conversationally:

- "Call the HG API to enrich walmart.com with firmographics and technographics"
- "Search for US companies with 1000+ employees using Salesforce"
- "Look up the vendor ID for Microsoft in the HG catalog"
- "Match these company names to HG records: Ford, Google, Walmart"
- "Write a Python script that enriches a list of domains from a CSV file"


Claude Code will make the API calls, show you the responses, and help you refine your queries — all from the terminal.

### Building integrations

Claude Code is especially useful for prototyping:


```
> "Write a Python script that reads domains from domains.csv, 
   enriches each one with firmographics via the HG API, 
   and writes the results to enriched.csv"
```

It will generate working code, test it against the API, and iterate until it works.

## Claude with MCP

The [Model Context Protocol (MCP)](https://modelcontextprotocol.io) lets Claude call the HG API as a tool directly in conversation. Instead of copying and pasting API responses, Claude can query HG data on demand.

### HG Official MCP Server

HG Insights offers an official MCP server with full access to HG data. It's currently in early access — [request access here](https://phoenix.hginsights.com/contact).

### Build Your Own MCP Server

If you prefer to build your own, you can wrap the HG API endpoints as MCP tools. This is a lightweight DIY approach using your existing API key. The example below shows how to set one up.

Once configured, Claude can query HG data naturally:

- "What's Walmart's tech stack?" → Claude calls Enrich with technographics
- "Find companies using AWS with $1M+ in cloud spend" → Claude calls Search
- "Who is the parent company of Google?" → Claude calls Enrich with firmographics


### Setting up a custom MCP server

A custom MCP server for HG API is a small script (~100 lines) that exposes the API endpoints as tools:


```python
from mcp.server import Server
from mcp.types import Tool
import requests
import os

server = Server("hg-insights")
API_KEY = os.environ["HG_API_KEY"]
BASE_URL = "https://api.hginsights.com/data-api/v2"
HEADERS = {
    "Authorization": f"Bearer {API_KEY}",
    "Content-Type": "application/json"
}

@server.tool()
async def enrich_company(
    domains: list[str],
    fields: list[str] = ["firmographics", "technographics", "spend"]
) -> dict:
    """Enrich companies with firmographics, technographics, and spend data."""
    response = requests.post(
        f"{BASE_URL}/companies/enrich",
        headers=HEADERS,
        json={"companies": {"domains": domains}, "fields": fields}
    )
    return response.json()

@server.tool()
async def match_companies(
    companies: list[dict]
) -> dict:
    """Match companies by name, domain, and/or country to find their HG records."""
    response = requests.post(
        f"{BASE_URL}/companies/match",
        headers=HEADERS,
        json={"companies": companies, "limit": 3}
    )
    return response.json()

@server.tool()
async def search_companies(
    filters: dict,
    limit: int = 10
) -> dict:
    """Search for companies using firmographic, technographic, spend, and intent filters."""
    response = requests.post(
        f"{BASE_URL}/companies/search",
        headers=HEADERS,
        json={
            "fields": ["id", "name", "domain"],
            "filters": filters,
            "limit": limit
        }
    )
    return response.json()

@server.tool()
async def lookup_catalog(
    catalog_type: str,
    name: str
) -> dict:
    """Look up vendors, products, categories, or other taxonomy data by name."""
    response = requests.get(
        f"{BASE_URL}/catalog/{catalog_type}",
        headers=HEADERS,
        params={"name": name, "limit": 10}
    )
    return response.json()
```

### Connecting to Claude Desktop

Add the server to your Claude Desktop config (`claude_desktop_config.json`):


```json
{
  "mcpServers": {
    "hg-insights": {
      "command": "python",
      "args": ["path/to/hg_mcp_server.py"],
      "env": {
        "HG_API_KEY": "your_api_key_here"
      }
    }
  }
}
```

Restart Claude Desktop and you can start asking questions about any company's data.

## ChatGPT and Other LLMs

You can use any LLM to help you explore the API and generate requests, even without MCP.

### Share the docs

Give the LLM the URL to these docs or paste the relevant guide content:


```
Here is the HG Insights API documentation: https://data-docs.hginsights.com

I want to find all US companies with 500+ employees that use Salesforce. 
Help me build the API request.
```

### Share the OpenAPI spec

For more precise help, share the OpenAPI spec directly:


```
Here is the HG API OpenAPI spec. Help me build a request to enrich 
google.com with firmographics and technographics filtered by Salesforce products.
```

The LLM will generate the correct JSON body, curl command, or code in your preferred language.

### Tips for better results

- Be specific about what you want: "enrich walmart.com" vs "find companies using AWS"
- Mention which endpoint to use if you know it
- Ask the LLM to include all available filter options so you can remove what you don't need
- Ask it to generate code in your language (Python, Node.js, etc.)


## Postman

If you prefer a visual API client, import the OpenAPI spec to get all endpoints pre-configured.

1. Open Postman and click **Import**
2. Select **Link** and paste: `https://data-docs.hginsights.com/v2/openapi.yaml`
3. Postman creates a collection with all endpoints ready to use
4. Set your API key in the collection's Authorization tab (Bearer Token)
5. Start making requests


### Tips

- Set the API key once at the collection level so it applies to all requests
- Save example requests for common queries you run often
- Use environment variables for different API keys (dev, prod)