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.

The Hog gives you two complementary ways to work with people data. First, use the people search endpoint to find contacts using a natural language query — optionally scoped to a specific company or filtered by title and location. Then, for any contact you want to understand more deeply, use the people research endpoint to pull a cross-platform dossier using their social handles.

​
Endpoint overview

EndpointMethodWhat it does
/api/people/searchPOSTFind ICP-matched people via NL query
/api/people/researchesPOSTBuild a deep dossier via identity resolution
Use this endpoint to discover contacts that match a natural language description. Results are semantically ranked by ICP fit. 
POST https://api.thehog.ai/api/people/search

​
Request fields

FieldTypeRequiredDescription
querystringYesNatural language description, e.g. "VP of Sales at a Series B SaaS company"
titlesstring[]NoExact or partial title filters (e.g. ["VP Sales", "Head of Revenue"])
locationsstring[]NoLocation filters (e.g. ["New York", "London"])
companyIdstringNoScope results to a specific company by its ID from company search
personaIdstringNoPersona ID for semantic ICP matching
projectIdstringNoProject context (can also be set via X-Project-Id header)
maxResultsnumberNoMaximum contacts to return; between 1 and 200
similarityThresholdnumberNoSemantic match cutoff between 0 and 1; higher values return closer matches only

​
Examples

curl -X POST https://api.thehog.ai/api/people/search \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "VP of Sales at a B2B SaaS company",
    "maxResults": 25
  }'

​
Response

The search returns HTTP 200 with a data array of PersonCard objects. 
{
  "data": [
    {
      "id": "p_01habc",
      "fullName": "Jordan Rivera",
      "title": "VP of Sales",
      "companyName": "Acme Corp",
      "location": "San Francisco, CA"
    }
  ],
  "meta": {
    "requestId": "req_01hxyz",
    "cost": { "estimated": 1, "actual": null }
  }
}

​
People research

Once you have specific individuals in mind, use the research endpoint to build a richer cross-platform dossier. You supply one or more platform identities (LinkedIn, X, GitHub, etc.) and The Hog resolves them into a unified profile. 
POST https://api.thehog.ai/api/people/researches
This endpoint is synchronous but involves real-time data gathering, so expect response times of 2–30 seconds depending on how many identities are provided and which platforms are queried.

​
Request fields

FieldTypeRequiredDescription
identitiesPlatformIdentity[]YesOne or more platform handles to resolve
Each PlatformIdentity object has:
FieldTypeValues
platformstring"linkedin", "x", "reddit", "github", "instagram", "tiktok"
usernamestringThe platform handle or username

​
Examples

curl -X POST https://api.thehog.ai/api/people/researches \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "identities": [
      { "platform": "linkedin", "username": "jordan-rivera" }
    ]
  }'

​
Typical workflow

1

Search for target companies

Use POST /api/companies/search with firmographic and signal filters to build your target account list. Note the id of each company you want to prospect.
2

Find contacts at each account

Pass the company id as companyId to POST /api/people/search along with a role-based query (e.g. "Head of Engineering") to surface relevant contacts.
3

Research high-priority individuals

For contacts you want to engage, collect their social handles and send them to POST /api/people/researches to get a cross-platform dossier.
4

Enrich with contact data

Pass the person id from search results to POST /api/people/enrich to retrieve verified email addresses and phone numbers.
Use companyId from company search results to scope people search to a specific account — this significantly improves relevance compared to a global search with the same query.