POST

api

people

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>"
      ]
    }
  },
  "confirm": true
}
'

const options = {
  method: 'POST',
  headers: {
    'X-Access-Key': '<api-key>',
    'X-Secret-Key': '<api-key>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    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>']
      }
    },
    confirm: true
  })
};

fetch('https://developer.thehog.ai/api/v1/people/search/estimate', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://developer.thehog.ai/api/v1/people/search/estimate"

payload = {
    "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>"]
        }
    },
    "confirm": True
}
headers = {
    "X-Access-Key": "<api-key>",
    "X-Secret-Key": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

{
  "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"
}

{
  "statusCode": 400,
  "error": "Bad Request",
  "message": "Validation failed",
  "path": "/api/v1/search",
  "timestamp": "2026-05-21T09:08:10.000Z",
  "requestId": "506af9b3-01a9-43be-9eb4-8458fe3e4f5b",
  "errors": [
    {
      "property": "body.query",
      "message": "query must be a string",
      "constraints": {
        "isString": "query must be a string"
      }
    }
  ]
}

{
  "statusCode": 401,
  "error": "Unauthorized",
  "message": "Authentication is required.",
  "path": "/api/v1/search",
  "timestamp": "2026-05-21T09:08:10.000Z",
  "requestId": "506af9b3-01a9-43be-9eb4-8458fe3e4f5b"
}

{
  "statusCode": 500,
  "error": "Internal Server Error",
  "message": "An unexpected error occurred.",
  "path": "/api/v1/search",
  "timestamp": "2026-05-21T09:08:10.000Z",
  "requestId": "506af9b3-01a9-43be-9eb4-8458fe3e4f5b"
}

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

Show child attributes

confirm

boolean

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

Show child attributes

assumptions

object

required

Show child attributes

expectedLatencyRange

string

Example:

"30s-5m"

⌘I

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>"
      ]
    }
  },
  "confirm": true
}
'

const options = {
  method: 'POST',
  headers: {
    'X-Access-Key': '<api-key>',
    'X-Secret-Key': '<api-key>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    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>']
      }
    },
    confirm: true
  })
};

fetch('https://developer.thehog.ai/api/v1/people/search/estimate', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://developer.thehog.ai/api/v1/people/search/estimate"

payload = {
    "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>"]
        }
    },
    "confirm": True
}
headers = {
    "X-Access-Key": "<api-key>",
    "X-Secret-Key": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

{
  "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"
}

{
  "statusCode": 400,
  "error": "Bad Request",
  "message": "Validation failed",
  "path": "/api/v1/search",
  "timestamp": "2026-05-21T09:08:10.000Z",
  "requestId": "506af9b3-01a9-43be-9eb4-8458fe3e4f5b",
  "errors": [
    {
      "property": "body.query",
      "message": "query must be a string",
      "constraints": {
        "isString": "query must be a string"
      }
    }
  ]
}

{
  "statusCode": 401,
  "error": "Unauthorized",
  "message": "Authentication is required.",
  "path": "/api/v1/search",
  "timestamp": "2026-05-21T09:08:10.000Z",
  "requestId": "506af9b3-01a9-43be-9eb4-8458fe3e4f5b"
}

{
  "statusCode": 500,
  "error": "Internal Server Error",
  "message": "An unexpected error occurred.",
  "path": "/api/v1/search",
  "timestamp": "2026-05-21T09:08:10.000Z",
  "requestId": "506af9b3-01a9-43be-9eb4-8458fe3e4f5b"
}

Overview

Companies

People

Research

Enrichments

Monitors

Search

LinkedIn

X

Instagram

TikTok

Facebook

YouTube

Web

SEO

Image

Operations

Estimate people search

POST /api/v1/people/search/estimate

Example

Authorizations

Body

Response

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

​Example

Authorizations

Body

Response

POST /api/v1/people/search/estimate

Example