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 enrichment endpoint finds verified email addresses and phone numbers for a batch of contacts by running each identity through a configurable multi-provider waterfall. For email, the waterfall queries up to 2 providers in sequence, stopping as soon as a verified result is found. For phone, up to 3 providers are tried. You can reduce both depths to control cost at the expense of coverage. By default the endpoint runs asynchronously — it returns a 202 immediately with an operation ID you can poll. To force a synchronous response, set asyncPreferred to false.

​
Request

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

​
Authentication

HeaderRequiredDescription
AuthorizationYesBearer <your-api-key>
X-Project-IdNoOptional project context.
Idempotency-KeyNoOptional. Submitting the same key twice within the same organization returns the existing queued operation rather than creating a duplicate.

​
Body Parameters

​
people
PersonIdentifier[]
List of contacts to enrich by their The Hog person ID. Use this when you already have IDs from a prior people search call.
​
identities
PlatformIdentity[]
List of platform handles to resolve into person records before enrichment. Useful when you have social handles but no The Hog person ID.
​
asyncPreferred
boolean
default:"true"
Controls response mode. When true (default), returns 202 Accepted with an operation ID to poll. When false, waits for enrichment to complete and returns 200 with results inline. Use false only for small batches where synchronous latency is acceptable.
​
projectId
string
Project context. Overrides the X-Project-Id header when set.
​
maxEmailProviderAttempts
number
default:"2"
Maximum number of email providers to query per contact. Range: 1–2. Setting to 1 reduces cost but may lower email hit rate.
​
maxPhoneProviderAttempts
number
default:"3"
Maximum number of phone providers to query per contact. Range: 1–3. Setting to 1 or 2 reduces cost but may lower phone hit rate.

​
Response

​
Sync response (asyncPreferred: false) — 200 OK

​
data
EnrichedPerson[]
One enriched contact object per input identity.
​
meta
object

​
Async response (asyncPreferred: true) — 202 Accepted

​
operationId
string
ID of the queued enrichment operation. Use this to poll for results.
​
status
string
Always "queued" on a 202 response.
​
pollUrl
string
The URL to poll for the operation’s status and results, e.g. /api/operations/op_01hx9k2m.
​
meta
object
To get a pre-flight cost estimate without committing to the enrichment, call POST /api/people/enrich/estimate first. That call is free.

​
Examples

curl -X POST https://api.thehog.ai/api/people/enrich \
  -H "Authorization: Bearer <your-api-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "people": [
      { "id": "per_01hx9k2m3n4p5q6r7s8t" }
    ],
    "asyncPreferred": false,
    "maxEmailProviderAttempts": 2,
    "maxPhoneProviderAttempts": 2
  }'