POST

api

people

Search people

curl --request POST \
  --url https://developer.thehog.ai/api/v1/people/search \
  --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', 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"

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)

{
  "id": "<string>",
  "operationId": "<string>",
  "status": "queued",
  "pollUrl": "<string>",
  "meta": {}
}

{
  "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": 402,
  "error": "Payment Required",
  "message": "Insufficient credits.",
  "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

Search for people by role, seniority, company, and more. Async.

Discover people matching your ICP using natural-language queries or structured filters. This is an async endpoint — returns 202 Accepted with a poll URL. Use POST /api/v1/people/search/estimate before queueing the search to inspect the conservative preflight credit ceiling, especially when requesting includeContacts. If you pass maxCredits to this endpoint and it is below the preflight ceiling, the request fails with 402 Payment Required before paid people or contact enrichment work starts.

Example

curl -X POST https://developer.thehog.ai/api/v1/people/search \
  -H "X-Access-Key: ak_xxxxxxxxxxxxxxxx" \
  -H "X-Secret-Key: sk_xxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "VP of Engineering at fintech startups in NYC",
    "limit": 10,
    "maxCredits": 1250
  }'

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.

Headers

Idempotency-Key

string

Optional. Reusing the same key for the same organization returns the existing queued operation.

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

People search accepted. Poll the returned URL for results.

string

required

operationId

string

required

status

enum<string>

required

Available options:

queued

pollUrl

string

required

meta

object

required

Search companies

Estimate people search

⌘I

Search people

curl --request POST \
  --url https://developer.thehog.ai/api/v1/people/search \
  --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', 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"

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)

{
  "id": "<string>",
  "operationId": "<string>",
  "status": "queued",
  "pollUrl": "<string>",
  "meta": {}
}

{
  "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": 402,
  "error": "Payment Required",
  "message": "Insufficient credits.",
  "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

Search people

POST /api/v1/people/search

Example

Authorizations

Headers

Body

Response

​POST /api/v1/people/search

​Example

Authorizations

Headers

Body

Response

POST /api/v1/people/search

Example