Skip to main content
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 submit selected contacts to the enrichment endpoint to retrieve verified contact data.

​
Endpoint overview

EndpointMethodWhat it does
/api/v1/people/searchPOSTFind ICP-matched people via NL query
/api/enrichmentsPOSTEnrich selected contacts
Use this endpoint to queue a contact discovery job from a natural language description. The API returns 202 Accepted immediately; poll the returned URL to retrieve semantically ranked results. 
POST https://developer.thehog.ai/api/v1/people/search

​
Request fields

FieldTypeRequiredDescription
querystringYesNatural language description, e.g. "VP of Sales at a Series B SaaS company"
limitnumberNoMaximum contacts to return; between 1 and 100
includeSignalsbooleanNoInclude signal context in results
includeContactsbooleanNoInclude contact fields when available
filters.titlesstring[]NoExact or partial title filters (e.g. ["VP Sales", "Head of Revenue"])
filters.locationsstring[]NoLocation filters (e.g. ["New York", "London"])
filters.companyobjectNoCompany filters such as names, domains, industries, or employeeCount

​
Target account matching

Use filters.company.domains or filters.company.names for target-account search. These fields represent the company you asked for. A filters.company.linkedinUrls value can help when you already know the exact company page, but it is treated as a provider handle rather than the canonical account identity. When a search is scoped to target accounts, poll GET /api/operations/:id and inspect result.meta:
FieldMeaning
targetAccountSearchModelinkedin_company_page means results were constrained by a LinkedIn company page. profile_current_company means results were matched against current profile company text. unavailable means The Hog could not confidently search the requested account with the available provider path.
targetAccountOutcomeExplains the LinkedIn company-handle path: supplied, verified, unavailable/conflicting, or unresolved. Use targetAccountSearchMode to see how people were actually matched.
messageHuman-readable guidance for empty or unavailable results.
Each returned person may include companyMatchEvidence with company_page or profile_current_job, so you can tell why the person matched the account.

​
Examples

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 at a B2B SaaS company",
    "limit": 25
  }'

​
Response

The search returns HTTP 202 with an operation ID and poll URL. 
{
  "id": "op_01hxyz",
  "operationId": "op_01hxyz",
  "status": "queued",
  "pollUrl": "/api/operations/op_01hxyz",
  "meta": {
    "requestId": "req_01hxyz"
  }
}

​
Typical workflow

1

Search for target companies

Use POST /api/v1/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 company constraints in filters.company along with a role-based query (e.g. "Head of Engineering") to surface relevant contacts.
3

Enrich with contact data

Pass the person id from search results to POST /api/enrichments to retrieve verified email addresses and phone numbers.
Use filters.company.domains or filters.company.names to scope people search to specific accounts — this significantly improves relevance compared to a global search with the same query.