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 people search endpoint accepts a natural language query and returns a ranked list of person cards from The Hog’s contact database. Results are ordered by semantic similarity to your query and, when a persona is specified, further ranked against your ICP definition. You can narrow results by title, location, or company, and optionally exclude contacts that have already been discovered in your project’s ledger. This endpoint is synchronous and returns immediately.

​
Request

POST https://api.thehog.ai/api/people/search

​
Authentication

HeaderRequiredDescription
AuthorizationYesBearer <your-api-key>
X-Project-IdNoOptional project context.

​
Body Parameters

​
query
string
required
Natural language search query. Describe the type of person you are looking for, e.g. "VP of Engineering at a Series B SaaS company". Maximum 256 characters.
​
titles
string[]
Explicit title filters applied in addition to the semantic query. Example: ["VP of Engineering", "Head of Engineering"].
​
locations
string[]
Location filters. Each entry is matched against the contact’s location field. Example: ["San Francisco", "New York"].
​
companyId
string
Restrict results to people associated with a specific company. Pass the company’s id as returned by the company search endpoint.
​
projectId
string
Project context. When set, overrides the X-Project-Id header and may apply persona-based ranking.
​
personaId
string
ICP persona ID. When provided, results are filtered and ranked against the persona definition using semantic similarity scoring.
​
maxResults
number
Maximum number of contacts to return. Range: 1–200.
​
similarityThreshold
number
Minimum semantic similarity score required for a contact to be included. Range: 0–1. Lower values return broader results; higher values return closer matches. Example: 0.51.
​
excludeLedger
boolean
When true, contacts that already appear in your project’s discovery ledger are excluded from results.

​
Response

The response is synchronous with a 200 status code.
​
data
PersonCard[]
Ranked list of matching person cards.
​
meta
object
Request metadata and cost information.

​
Example

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 Engineering at a B2B SaaS company",
    "titles": ["VP of Engineering", "Head of Engineering"],
    "locations": ["San Francisco", "New York"],
    "maxResults": 25,
    "similarityThreshold": 0.55,
    "excludeLedger": false
  }'