Find People with The Hog

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

Endpoint	Method	What it does
`/api/v1/people/search/estimate`	POST	Estimate people search and contact-enrichment risk
`/api/v1/people/search`	POST	Find ICP-matched people via NL query
`/api/enrichments`	POST	Enrich selected contacts

People search

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

Run POST /api/v1/people/search/estimate with the same body first when you want to size maxCredits. The estimate response returns the standard estimate fields plus a breakdown of the base people search credits and contact enrichment risk. The base people-search estimate scales with requested provider-result pages, so larger limit values can raise the preflight ceiling even without contact enrichment.

Request fields

Field	Type	Required	Description
`query`	string	Yes	Natural language description, e.g. `"VP of Sales at a Series B SaaS company"`
`limit`	number	No	Maximum contacts to return; between 1 and 100
`includeSignals`	boolean	No	Include signal context in results
`includeContacts`	boolean	No	Include contact fields when available. When `contactFields` is omitted, this requests email + phone.
`contactFields`	string[]	No	Contact fields to enrich when `includeContacts` is true. Allowed values: `"email"` and `"phone"`.
`maxCredits`	number	No	Maximum credits the operation may charge after metered usage is priced.
`filters.titles`	string[]	No	Exact or partial title filters (e.g. `["VP Sales", "Head of Revenue"]`)
`filters.locations`	string[]	No	Location filters (e.g. `["New York", "London"]`)
`filters.company`	object	No	Company filters such as `names`, `domains`, `industries`, or `employeeCount`

Contact enrichment spend controls

Set includeContacts: true only when you want people search to run contact enrichment as part of the search job. Use contactFields to request email-only, phone-only, or both. For backward compatibility, includeContacts: true without contactFields requests both email and phone. Use maxCredits to cap the final customer charge for the operation. The API also checks the conservative preflight estimate before paid people or contact enrichment work starts. If maxCredits is lower than that preflight ceiling, the request fails with 402 Payment Required and no paid people/contact work starts. Actual billing is based on measured usage and can be lower than the cap.

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 platform handle rather than the canonical account identity. When a search is scoped to target accounts, poll GET /api/operations/:id and inspect result.meta:

Field	Meaning
`targetAccountSearchMode`	`linkedin_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 search path.
`targetAccountOutcome`	Explains the LinkedIn company-handle path: supplied, verified, unavailable/conflicting, or unresolved. Use `targetAccountSearchMode` to see how people were actually matched.
`message`	Human-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
  }'

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": "revenue leader",
    "filters": {
      "titles": ["VP Sales", "Chief Revenue Officer", "Head of Sales"],
      "locations": ["United States", "Canada"],
      "company": { "domains": ["salesforce.com"] }
    },
    "limit": 10
  }'

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": "growth-focused marketing leader",
    "filters": {
      "titles": ["VP Marketing", "Head of Growth"]
    },
    "includeSignals": true,
    "limit": 50
}'

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 Engineering at B2B SaaS companies",
    "limit": 25,
    "includeContacts": true,
    "contactFields": ["email"],
    "maxCredits": 63750
  }'

curl -X POST https://developer.thehog.ai/api/v1/people/search/estimate \
  -H "X-Access-Key: ak_xxxxxxxxxxxxxxxx" \
  -H "X-Secret-Key: sk_xxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "VP Engineering at B2B SaaS companies",
    "limit": 25,
    "includeContacts": true,
    "contactFields": ["email"]
  }'

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

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.

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.

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.

Get Started

Core Concepts

Guides

Reference

Find People with The Hog

Endpoint overview

People search

Request fields

Contact enrichment spend controls

Target account matching

Examples

Response

Typical workflow

​Endpoint overview

​People search

​Request fields

​Contact enrichment spend controls

​Target account matching

​Examples

​Response

​Typical workflow

Endpoint overview

People search

Request fields

Contact enrichment spend controls

Target account matching

Examples

Response

Typical workflow