The Hog uses two response patterns depending on how long an operation takes. Fast operations return data immediately in the response body with a 200 status. Operations that require more processing time — like enriching large contact lists or running deep research — return a 202 Accepted response with an operation ID you can poll until the work is done. Knowing which pattern to expect helps you design your integration correctly from the start.
Sync operations (200)
These calls complete quickly and return data directly in the response. You don’t need to do anything after the initial request.
Async operations (202)
These calls kick off background work and return immediately with a poll URL. You retrieve the result by polling GET /api/operations/:id until the status reaches succeeded or failed.
| Endpoint | Async trigger |
|---|
POST /api/v1/companies/search | Always async — company discovery |
POST /api/v1/people/search | Always async — people discovery |
POST /api/enrichments | Batch enrichments and signal enrichments |
POST /api/v1/search | Search jobs submitted for background processing |
POST /api/deep-research | Always async — LLM-powered deep research |
POST /api/v1/platform/scrapers/web/crawl | Website crawl jobs |
POST /api/v1/platform/scrapers/web/scrape/batch | Multiple page scrapes |
POST /api/v1/platform/scrapers/web/scrape/jobs | Deep scrape for long or dynamic pages |
Sync response (200)
Async accepted (202)
Polling response (200)
Data is available immediately in the data field.{
"data": [
{
"id": "comp_xyz789",
"name": "Acme Corp",
"industry": "Software",
"employee_count": 220,
"is_hiring": true
}
],
"meta": {
"requestId": "req_aabbccdd"
}
}
The response contains an operation ID and a URL to poll. No result data yet.{
"id": "op_99887766",
"operationId": "op_99887766",
"status": "queued",
"pollUrl": "/api/operations/op_99887766",
"meta": {
"requestId": "req_11223344"
}
}
Call GET /api/operations/:id to check progress. When status is succeeded, result contains the full output.{
"id": "op_99887766",
"status": "succeeded",
"progress": 100,
"result": {
"email": "jane.doe@acme.com",
"phone": "+1-555-0100",
"emailVerified": true
},
"error": null
}
How to poll
Once you have an operationId, call GET /api/operations/:id on a schedule until the status is terminal.
curl https://developer.thehog.ai/api/operations/op_99887766 \
-H "X-Access-Key: ak_xxxxxxxxxxxxxxxx" \
-H "X-Secret-Key: sk_xxxxxxxxxxxxxxxx"
Operation status values
| Status | Meaning |
|---|
queued | Work is waiting to start |
processing | Work is in progress — check progress for a 0–100 estimate |
succeeded | Work is complete — read the result field |
failed | Work failed — read the error field for details |
partial_success | Some results were returned; check both result and error |
cancelled | The operation was cancelled before completion |
Don’t poll more aggressively than once per second. The operations endpoint has a dedicated rate limit. If you exceed it, you’ll receive a 429 response.
Recommended polling strategy
# Simple polling loop — wait 2 seconds between checks
while true; do
RESPONSE=$(curl -s https://developer.thehog.ai/api/operations/op_99887766 \
-H "X-Access-Key: ak_xxxxxxxxxxxxxxxx" \
-H "X-Secret-Key: sk_xxxxxxxxxxxxxxxx")
STATUS=$(echo $RESPONSE | jq -r '.status')
echo "Status: $STATUS"
if [ "$STATUS" = "succeeded" ] || [ "$STATUS" = "failed" ]; then
echo $RESPONSE | jq '.result // .error'
break
fi
sleep 2
done
{
"data": {
"estimatedCredits": 5,
"likelySyncOrAsync": "async",
"expectedLatencyRange": "10–30s",
"expectedLookupDepth": 2,
"withinPlanLimits": true
},
"meta": {
"requestId": "req_estimate001"
}
}
Idempotency
For async POST requests, you can supply an Idempotency-Key header. If you retry the same request with the same key within the idempotency window, the API returns the original response rather than creating a duplicate operation.
This example uses a batch enrichment request, which is always asynchronous.
curl -X POST https://developer.thehog.ai/api/enrichments \
-H "X-Access-Key: ak_xxxxxxxxxxxxxxxx" \
-H "X-Secret-Key: sk_xxxxxxxxxxxxxxxx" \
-H "Idempotency-Key: enrich-jane-doe-20260506" \
-H "Content-Type: application/json" \
-d '{
"identifiers": [
{ "linkedin_url": "https://www.linkedin.com/in/jane-doe-example" },
{ "email": "jane@example.com" }
],
"fields": ["contact.email", "contact.phone"]
}'
Use a deterministic idempotency key — such as a hash of the request payload or a stable record ID — so that retries after a network failure are safe and don’t double-charge credits.
