Getting started

The short version of how a search actually works.

Database & Work Mode

The API is live. Everything below is checked against the running service, and the frontend generates its types from the same OpenAPI schema.

Authentication

Authorization: Bearer sk_live_...

A key is scoped to the team it was created in, and acts as the account that created it. Most of the API takes a key. The endpoints marked Signed in are dashboard-only, because they manage the account itself (teams, invites, notifications, buying credits, creating more keys); a key gets 401 on those. Staff marks HuntPeople's own operator views.

Endpoints

Two families of route are deliberately left out of the table. /v1/auth/* is the dashboard's own sign-up, sign-in, verification, and account-settings surface, driven by the session cookie rather than a key. /v1/billing/webhook is Stripe calling us, not something you call. GET /healthz returns { "ok": true } and takes no credential, for uptime checks.

Preview a search

The UI never commits a search without a confirm-back step first: Natural Language shows what it parsed out of your sentence, a CSV upload shows its column mapping, before hundreds of searches fire. This endpoint is that same step, parse or map without starting anything.

curl -X POST https://api.huntpeople.ai/v1/search/preview \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{"query": "Jane Doe, works at Acme, find her email"}'

Returns:

{
  "known": [{ "type": "name", "value": "Jane Doe" }, { "type": "company", "value": "Acme" }],
  "want": [{ "type": "email" }],
  "nearUniqueWarning": true
}

Start a search

curl -X POST https://api.huntpeople.ai/v1/search \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{"email": "jane@example.com"}'

Every search costs credits at a price set before it runs: 1 for a quick search, 2 for a normal one, 7 for a deep one, and 5 to 52 for an exhaustive check depending on the model and how long you let it run. It never changes with how hard the search turned out to be. There is one balance for everything, so a search from the dashboard and a search through an API key come out of the same place. When the balance runs out, a search that would spend credits is refused with 402 until you add more or your plan renews. A search that fails on our side is never charged. Create keys and manage your credit balance together on the API keys page.

Get a result

Search is asynchronous: the POST returns an id right away and the run continues in the background, so poll this until status stops being running. status is one of running, done, failed, or cancelled. stopReason says why a finished run stopped: confidence-threshold, goals-met, diminishing-returns, budget-cap, cancelled, or error. Ids are 32-character hex strings, not prefixed.

curl https://api.huntpeople.ai/v1/investigations/9f2b6c41ad7e4f0e8b1c53d2a07e4c88 \
  -H "Authorization: Bearer sk_live_..."

Returns:

{
  "id": "9f2b6c41ad7e4f0e8b1c53d2a07e4c88",
  "status": "done",
  "stopReason": "confidence-threshold",
  "confidence": 92,
  "person": {
    "id": "c40a1e7b93d24f6ea5b8027cf1d63a19",
    "facts": [
      { "field": "email", "value": "jane@example.com", "confidence": 91, "subject": "person" }
    ]
  },
  "seeds": [{ "type": "phone", "value": "+1 704 555 0142" }],
  "wants": ["email"],
  "goals": [{ "field": "email", "status": "found", "value": "jane@example.com", "confidence": 91 }],
  "cost_usd": null,
  "createdAt": "2026-08-19T12:00:00Z",
  "sourcesChecked": 7, "signals": 4
}

Webhooks

A single search is fast enough to just poll. A batch of hundreds isn't, since completion time varies per person and polling every investigation wastes calls. Pass a callback_url on /v1/search, or once on /v1/searches/batch to cover every person in it, and HuntPeople posts to it as each investigation finishes, instead of a separate persistent webhook-subscription system to manage.

curl -X POST https://api.huntpeople.ai/v1/search \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{"email": "jane@example.com", "callback_url": "https://yourapp.com/hooks/huntpeople"}'

What lands on your endpoint:

POST https://yourapp.com/hooks/huntpeople

{ "investigation_id": "9f2b6c41ad7e4f0e8b1c53d2a07e4c88", "status": "done" }

The post carries the investigation id, nothing else worth acting on. Treat it as a nudge to read GET /v1/investigations/{id}, which is where the real outcome (done or failed, stop reason, facts) lives. Delivery is best effort and unsigned, so verify by reading the investigation rather than trusting the post. Only public web addresses are called; a loopback or private address is dropped.

FAQ