Skip to main content

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.

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.
1

Get your API key

Retrieve your API key from your account settings. You will include it as a Bearer token on every request.See Authentication for the full details on both credential formats and how to add project context.All examples below use the Authorization: Bearer method. Replace hog_live_xxxxxxxxxxxxxxxxxxxxxxxx with your actual key.
2

Search your first company

Call POST /api/companies/search with a natural-language query to find matching accounts. The response returns a ranked list of companies with firmographic and technographic details.
curl -X POST https://api.thehog.ai/api/companies/search \
  -H "Authorization: Bearer hog_live_xxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "Salesforce",
    "limit": 5
  }'
Sample response:
{
  "companies": [
    {
      "id": "cmp_01HZX1SALESFORCE000000001",
      "name": "Salesforce",
      "domain": "salesforce.com",
      "industry": "Software",
      "employee_count": 79000,
      "location": "San Francisco, CA",
      "tech_stack": ["Heroku", "MuleSoft", "Slack", "Tableau"],
      "is_hiring": false,
      "has_recent_funding": false,
      "growth_band": "high",
      "match_score": 0.97
    }
  ],
  "total": 1,
  "hasMore": false,
  "metering": {
    "creditsCharged": 1,
    "estimatedMaxCredits": 3
  },
  "meta": {
    "requestId": "01HZXAMPLE000000000000001",
    "cost": {
      "estimated": 1,
      "actual": 1
    }
  }
}
Copy the id of the company you want to explore — you will use it in the next step.
3

Find people at that company

Call POST /api/people/search with a natural-language query and the companyId from the previous step. The API returns ICP-ranked contacts matching your description.
curl -X POST https://api.thehog.ai/api/people/search \
  -H "Authorization: Bearer hog_live_xxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "VP of Sales",
    "companyId": "cmp_01HZX1SALESFORCE000000001",
    "maxResults": 10
  }'
Sample response:
{
  "data": [
    {
      "id": "prs_01HZXPERSON0000000000001",
      "fullName": "Alex Rivera",
      "title": "VP of Sales, North America",
      "companyName": "Salesforce",
      "location": "San Francisco, CA"
    }
  ],
  "meta": {
    "requestId": "01HZXAMPLE000000000000002",
    "cost": { "estimated": 1, "actual": null }
  }
}
Pass X-Project-Id on the request to rank results against your own ICP personas instead of the default scoring.
4

Enrich a contact

Call POST /api/people/enrich with one or more identity references — a LinkedIn URL, email address, or person ID — to retrieve verified contact information.
curl -X POST https://api.thehog.ai/api/people/enrich \
  -H "Authorization: Bearer hog_live_xxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "identities": [
      {
        "platform": "linkedin",
        "username": "alex-rivera-example"
      }
    ]
  }'
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://api.thehog.ai/api/operations/op_01HZXOPERATION00000000001",
  "meta": {
    "requestId": "01HZXAMPLE000000000000004",
    "estimatedCost": 5
  }
}
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://api.thehog.ai/api/operations/op_01HZXOPERATION00000000001 \
  -H "Authorization: Bearer hog_live_xxxxxxxxxxxxxxxxxxxxxxxx"
Sample completed response:
{
  "id": "op_01HZXOPERATION00000000001",
  "status": "succeeded",
  "progress": 100,
  "result": {
    "people": [
      {
        "id": "prs_01HZXPERSON0000000000001",
        "fullName": "Alex Rivera",
        "emailStatus": "available",
        "phoneStatus": "available",
        "emails": [
          { "email": "alex.rivera@salesforce.com", "emailType": "work", "isVerified": true }
        ],
        "phoneNumbers": [
          { "phoneNumber": "+14155550100", "phoneType": "direct", "isVerified": false }
        ],
        "fromCache": 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:

Detect signals

Surface buying signals like job changes, funding rounds, and hiring surges at your target accounts.

Generate content

Use project context to generate personalized outreach and social replies grounded in your messaging.

Run deep research

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

Add project context

Learn how passing X-Project-Id scopes every operation to your brand voice, personas, and competitive intel.