> ## Documentation Index
> Fetch the complete documentation index at: https://docs.thehog.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Get Started with The Hog API
> Make your first The Hog API call in minutes. Search companies, find people, and enrich contacts with step-by-step examples.
This guide walks you through the core The Hog workflow: find a company, discover people at that company, enrich a contact to get their email and phone number, and poll for results when the operation runs asynchronously. Each step builds on the previous one, so you can follow along end-to-end or jump to the section you need.
Building from Claude, Claude Code, Cursor, Codex, or another MCP client? See [Use The Hog with MCP](/guides/use-mcp) to connect through hosted remote MCP or install the local stdio MCP package.
Retrieve your API key and API secret from the Credentials page in your dashboard.
See [Authentication](/authentication) for the full header details.
All examples below send the API key as `X-Access-Key` and the API secret as `X-Secret-Key`.
Call `POST /api/v1/companies/search` with a natural-language query to find matching accounts. The endpoint returns `202 Accepted` with an operation ID; poll the operation to retrieve ranked companies.
```bash curl theme={null} theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl -X POST https://developer.thehog.ai/api/v1/companies/search \
-H "X-Access-Key: ak_xxxxxxxxxxxxxxxx" \
-H "X-Secret-Key: sk_xxxxxxxxxxxxxxxx" \
-H "Content-Type: application/json" \
-d '{
"query": "Salesforce",
"limit": 5
}'
```
```python Python theme={null} theme={"theme":{"light":"github-light","dark":"github-dark"}}
import httpx
response = httpx.post(
"https://developer.thehog.ai/api/v1/companies/search",
headers={
"X-Access-Key": "ak_xxxxxxxxxxxxxxxx",
"X-Secret-Key": "sk_xxxxxxxxxxxxxxxx",
},
json={"query": "Salesforce", "limit": 5},
)
data = response.json()
operation_id = data["operationId"]
```
```javascript Node.js theme={null} theme={"theme":{"light":"github-light","dark":"github-dark"}}
const response = await fetch("https://developer.thehog.ai/api/v1/companies/search", {
method: "POST",
headers: {
"X-Access-Key": "ak_xxxxxxxxxxxxxxxx",
"X-Secret-Key": "sk_xxxxxxxxxxxxxxxx",
"Content-Type": "application/json",
},
body: JSON.stringify({ query: "Salesforce", limit: 5 }),
});
const data = await response.json();
const operationId = data.operationId;
```
**Sample 202 response:**
```json theme={null} theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
"id": "op_01HZXCOMPANY000000000001",
"operationId": "op_01HZXCOMPANY000000000001",
"status": "queued",
"pollUrl": "/api/operations/op_01HZXCOMPANY000000000001"
}
```
Poll `GET /api/operations/:id` until the operation succeeds. Use the returned company domain or name in the next step.
Call `POST /api/v1/people/search` with a natural-language query and optional company filters from the previous step. This endpoint also returns `202 Accepted`; poll the operation for ICP-ranked contacts.
```bash curl theme={null} theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl -X POST https://developer.thehog.ai/api/v1/people/search \
-H "X-Access-Key: ak_xxxxxxxxxxxxxxxx" \
-H "X-Secret-Key: sk_xxxxxxxxxxxxxxxx" \
-H "Content-Type: application/json" \
-d '{
"query": "VP of Sales",
"filters": {
"company": { "domains": ["salesforce.com"] }
},
"limit": 10
}'
```
```python Python theme={null} theme={"theme":{"light":"github-light","dark":"github-dark"}}
response = httpx.post(
"https://developer.thehog.ai/api/v1/people/search",
headers={
"X-Access-Key": "ak_xxxxxxxxxxxxxxxx",
"X-Secret-Key": "sk_xxxxxxxxxxxxxxxx",
},
json={
"query": "VP of Sales",
"filters": {"company": {"domains": ["salesforce.com"]}},
"limit": 10,
},
)
operation_id = response.json()["operationId"]
```
```javascript Node.js theme={null} theme={"theme":{"light":"github-light","dark":"github-dark"}}
const response = await fetch("https://developer.thehog.ai/api/v1/people/search", {
method: "POST",
headers: {
"X-Access-Key": "ak_xxxxxxxxxxxxxxxx",
"X-Secret-Key": "sk_xxxxxxxxxxxxxxxx",
"Content-Type": "application/json",
},
body: JSON.stringify({
query: "VP of Sales",
filters: {
company: { domains: ["salesforce.com"] },
},
limit: 10,
}),
});
const { operationId } = await response.json();
```
**Sample 202 response:**
```json theme={null} theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
"id": "op_01HZXPEOPLE000000000001",
"operationId": "op_01HZXPEOPLE000000000001",
"status": "queued",
"pollUrl": "/api/operations/op_01HZXPEOPLE000000000001",
"meta": { "requestId": "01HZXAMPLE000000000000002" }
}
```
Call `POST /api/enrichments` with one or more identity references — a LinkedIn URL, email address, or person ID — to retrieve verified contact information.
```bash curl theme={null} theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl -X POST https://developer.thehog.ai/api/enrichments \
-H "X-Access-Key: ak_xxxxxxxxxxxxxxxx" \
-H "X-Secret-Key: sk_xxxxxxxxxxxxxxxx" \
-H "Content-Type: application/json" \
-d '{
"identifier": {
"linkedin_url": "https://www.linkedin.com/in/alex-rivera-example"
},
"fields": ["contact.email", "contact.phone"]
}'
```
```python Python theme={null} theme={"theme":{"light":"github-light","dark":"github-dark"}}
response = httpx.post(
"https://developer.thehog.ai/api/enrichments",
headers={
"X-Access-Key": "ak_xxxxxxxxxxxxxxxx",
"X-Secret-Key": "sk_xxxxxxxxxxxxxxxx",
},
json={
"identifier": {
"linkedin_url": "https://www.linkedin.com/in/alex-rivera-example",
},
"fields": ["contact.email", "contact.phone"],
},
)
result = response.json()
# 200 → enrichment complete; 202 → async, poll operationId
```
```javascript Node.js theme={null} theme={"theme":{"light":"github-light","dark":"github-dark"}}
const response = await fetch("https://developer.thehog.ai/api/enrichments", {
method: "POST",
headers: {
"X-Access-Key": "ak_xxxxxxxxxxxxxxxx",
"X-Secret-Key": "sk_xxxxxxxxxxxxxxxx",
"Content-Type": "application/json",
},
body: JSON.stringify({
identifier: {
linkedin_url: "https://www.linkedin.com/in/alex-rivera-example",
},
fields: ["contact.email", "contact.phone"],
}),
});
// Check response.status: 200 = done, 202 = async
```
The enrichment endpoint returns either a **200** or a **202** response depending on how quickly the data can be resolved:
| Status | Meaning | Next step |
| -------------- | ------------------------------------ | --------------------------------------------------------- |
| `200 OK` | Enrichment completed synchronously | The `data` field contains verified contact details. |
| `202 Accepted` | Enrichment is running asynchronously | Use the `operationId` and `pollUrl` to check for results. |
**Sample 200 response:**
```json theme={null} theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
"data": [
{
"id": "prs_01HZXPERSON0000000000001",
"canonicalPersonId": "prs_01HZXPERSON0000000000001",
"fullName": "Alex Rivera",
"title": "VP of Sales, North America",
"companyName": "Salesforce",
"location": "San Francisco, CA",
"emailStatus": "available",
"phoneStatus": "available",
"emails": [
{ "email": "alex.rivera@salesforce.com", "emailType": "work", "isVerified": true }
],
"phoneNumbers": [
{ "phoneNumber": "+14155550100", "phoneType": "direct", "isVerified": false }
],
"fromCache": false
}
],
"meta": {
"requestId": "01HZXAMPLE000000000000003",
"cost": { "estimated": 5, "actual": 4 }
}
}
```
**Sample 202 response:**
```json theme={null} theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
"operationId": "op_01HZXOPERATION00000000001",
"status": "queued",
"pollUrl": "https://developer.thehog.ai/api/operations/op_01HZXOPERATION00000000001",
"meta": {
"requestId": "01HZXAMPLE000000000000004"
}
}
```
If you receive a 202, proceed to the next step to poll for the result.
When an operation returns a 202, call `GET /api/operations/:id` periodically until the `status` field is `completed` or `failed`.
```bash curl theme={null} theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl https://developer.thehog.ai/api/operations/op_01HZXOPERATION00000000001 \
-H "X-Access-Key: ak_xxxxxxxxxxxxxxxx" \
-H "X-Secret-Key: sk_xxxxxxxxxxxxxxxx"
```
```python Python theme={null} theme={"theme":{"light":"github-light","dark":"github-dark"}}
import time
operation_id = "op_01HZXOPERATION00000000001"
while True:
resp = httpx.get(
f"https://developer.thehog.ai/api/operations/{operation_id}",
headers={
"X-Access-Key": "ak_xxxxxxxxxxxxxxxx",
"X-Secret-Key": "sk_xxxxxxxxxxxxxxxx",
},
)
op = resp.json()
if op["status"] in ("succeeded", "failed"):
break
time.sleep(2)
result = op.get("result")
```
```javascript Node.js theme={null} theme={"theme":{"light":"github-light","dark":"github-dark"}}
const operationId = "op_01HZXOPERATION00000000001";
async function poll(id) {
while (true) {
const res = await fetch(`https://developer.thehog.ai/api/operations/${id}`, {
headers: {
"X-Access-Key": "ak_xxxxxxxxxxxxxxxx",
"X-Secret-Key": "sk_xxxxxxxxxxxxxxxx",
},
});
const op = await res.json();
if (op.status === "succeeded" || op.status === "failed") return op;
await new Promise((r) => setTimeout(r, 2000));
}
}
const op = await poll(operationId);
```
**Sample completed response:**
```json theme={null} theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
"id": "op_01HZXOPERATION00000000001",
"status": "succeeded",
"progress": 100,
"result": {
"items": [
{
"identifier": {
"linkedin_url": "https://www.linkedin.com/in/alex-rivera-example"
},
"status": "success",
"data": {
"contact": {
"email": ["alex.rivera@salesforce.com"],
"phone": ["+14155550100"]
}
}
}
],
"partial": false
},
"error": null
}
```
Poll at a reasonable interval — every 2–5 seconds is sufficient for most enrichment jobs. Deep research operations may take longer; check the `progress` field to track how far along the job is.
## What's next
You have completed the core workflow. From here you can:
Search across the web, LinkedIn, X, Reddit, and TikTok with a single API call.
Create recurring monitors to track mentions, keywords, and profiles across social platforms.
Kick off LLM-powered research jobs that return structured data conforming to a JSON Schema you define.
Understand sync responses, async operation polling, request IDs, and common result formats.
Connect The Hog to an MCP client with hosted remote MCP or local stdio.