Skip to main content
POST
/
api
/
v1
/
people
/
search
/
estimate
Estimate people search
curl --request POST \
  --url https://developer.thehog.ai/api/v1/people/search/estimate \
  --header 'Content-Type: application/json' \
  --header 'X-Access-Key: <api-key>' \
  --header 'X-Secret-Key: <api-key>' \
  --data '
{
  "query": "VP Engineering at hiring B2B SaaS companies in SF",
  "limit": 25,
  "includeSignals": false,
  "includeContacts": false,
  "contactFields": [
    "email"
  ],
  "maxCredits": 2500,
  "filters": {
    "titles": [
      "<string>"
    ],
    "locations": [
      "<string>"
    ],
    "industries": [
      "<string>"
    ],
    "employeeCount": {
      "min": 1,
      "max": 1
    },
    "signals": [
      "<string>"
    ],
    "company": {
      "names": [
        "<string>"
      ],
      "domains": [
        "<string>"
      ],
      "linkedinUrls": [
        "<string>"
      ],
      "industries": [
        "<string>"
      ],
      "employeeCount": {
        "min": 1,
        "max": 1
      },
      "signals": [
        "<string>"
      ]
    }
  }
}
'
{
  "estimatedCredits": 123,
  "withinPlanLimits": true,
  "breakdown": {
    "baseSearchCredits": 123,
    "contactEnrichment": {
      "includeContacts": true,
      "fields": [],
      "maxPeople": 123,
      "contactAttemptsPerFieldPerPerson": 123,
      "estimatedCredits": 123
    }
  },
  "assumptions": {
    "mode": "conservative_preflight_ceiling",
    "description": "<string>"
  },
  "expectedLatencyRange": "30s-5m"
}

​
POST /api/v1/people/search/estimate

Estimate credits for async people search before queueing paid enrichment work.
Use this endpoint before POST /api/v1/people/search when you want to set maxCredits or show users the credit risk of requesting contact enrichment. The estimate is a conservative preflight ceiling. Actual settled credits are based on measured usage and can be lower. Discovery risk scales with requested result pages, so higher limit values can require a larger preflight ceiling even when includeContacts is false.

​
Example

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": 10,
    "includeContacts": true,
    "contactFields": ["email"]
  }'
The response includes the standard estimate fields plus a breakdown. The base people-search portion assumes one discovery charge per provider-result page currently modeled as up to 25 people. When includeContacts is true, omitted contactFields means both email and phone, matching the search endpoint.

Authorizations

​
X-Access-Key
string
header
required

The public API key from the Credentials page.

​
X-Secret-Key
string
header
required

The API secret shown when the credential is created.

Body

application/json
​
query
string
required
Maximum string length: 500
Example:

"VP Engineering at hiring B2B SaaS companies in SF"

​
limit
number
default:25
Required range: 1 <= x <= 100
​
includeSignals
boolean
default:false
​
includeContacts
boolean
default:false
​
contactFields
enum<string>[]

Contact fields to enrich when includeContacts is true. Omit to preserve legacy includeContacts=true behavior, which requests both email and phone.

Required array length: 1 - 2 elements
Available options:
email,
phone
Example:
["email"]
​
maxCredits
number

Maximum credits the people search operation may charge. When omitted, normal account limits apply.

Required range: x >= 0
Example:

2500

​
filters
object

Response

Conservative people search preflight estimate and contact enrichment breakdown.

​
estimatedCredits
number
required

Estimated credits to be consumed

​
likelySyncOrAsync
enum<string>
required

Whether the real request will return 200 or 202

Available options:
sync,
async
​
withinPlanLimits
boolean
required
​
breakdown
object
required
​
assumptions
object
required
​
expectedLatencyRange
string
Example:

"30s-5m"