Skip to main content
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 to connect through hosted remote MCP or install the local stdio MCP package.
1

Get your API key and secret

Retrieve your API key and API secret from the Credentials page in your dashboard.See 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.
2

Search your first company

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.
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
  }'
Sample 202 response:
{
  "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.
3

Find people at that company

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.
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
  }'
Sample 202 response:
{
  "id": "op_01HZXPEOPLE000000000001",
  "operationId": "op_01HZXPEOPLE000000000001",
  "status": "queued",
  "pollUrl": "/api/operations/op_01HZXPEOPLE000000000001",
  "meta": { "requestId": "01HZXAMPLE000000000000002" }
}
4

Enrich a contact

Call POST /api/enrichments with one or more identity references — a LinkedIn URL, email address, or person ID — to retrieve verified contact information.
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"]
  }'
The enrichment endpoint returns either a 200 or a 202 response depending on how quickly the data can be resolved:
StatusMeaningNext step
200 OKEnrichment completed synchronouslyThe data field contains verified contact details.
202 AcceptedEnrichment is running asynchronouslyUse the operationId and pollUrl to check for results.
Sample 200 response:
{
  "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:
{
  "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.
5

Poll for async results

When an operation returns a 202, call GET /api/operations/:id periodically until the status field is completed or failed.
curl https://developer.thehog.ai/api/operations/op_01HZXOPERATION00000000001 \
  -H "X-Access-Key: ak_xxxxxxxxxxxxxxxx" \
  -H "X-Secret-Key: sk_xxxxxxxxxxxxxxxx"
Sample completed response:
{
  "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:

Run searches

Search across the web, LinkedIn, X, Reddit, and TikTok with a single API call.

Set up monitors

Create recurring monitors to track mentions, keywords, and profiles across social platforms.

Run deep research

Kick off LLM-powered research jobs that return structured data conforming to a JSON Schema you define.

Review response shapes

Understand sync responses, async operation polling, request IDs, and common result formats.

Use with MCP

Connect The Hog to an MCP client with hosted remote MCP or local stdio.