API Reference

People

The people at your activated accounts: rosters, decision-maker search, verified emails, phones, lists, and CRM push. Data is unlimited on every plan, so none of these endpoints draw down a credit balance.

People come from two places. When you activate an account, Hunch loads its full employee roster automatically (source employee). When you run a Find People search, matched decision makers are saved with their match tier (source waterfall). Both land in the same collection and dedupe by LinkedIn profile per account.

List people

GET/people

Returns people newest first, paginated. Supports filters:

Query parameters

account_idstringoptional

Only people at this account.

job_levelstringoptional

C-Team, VP, Director, Manager, or Staff.

country_codestringoptional

ISO 2-letter country code, e.g. US.

sourcestringoptional

employee (roster sync) or waterfall (Find People match).

has_emailbooleanoptional

true for only people with a verified email; false for people without one.

list_idstringoptional

Only people saved to this list.

searchstringoptional

Substring match on name, title, or headline.

sortstringoptional

created_at (default) or full_name.

orderstringoptional

asc or desc. Default desc.

pageintegeroptional

Page number. Default 1.

per_pageintegeroptional

Max 100. Default 50.

Request

curl "https://usehunch.co/api/v1/people?job_level=VP&has_email=true&per_page=25" \
  -H "Authorization: Bearer hunch_YOUR_KEY"

Response

{
  "data": [
    {
      "id": "...",
      "account_id": "...",
      "full_name": "Lena Tran",
      "title": "Head of Revenue Operations",
      "headline": "RevOps at Fielder",
      "linkedin_url": "https://www.linkedin.com/in/lenatran",
      "email": "lena@fielder.app",
      "email_checked_at": "2026-07-06T...",
      "phone": null,
      "phone_checked_at": null,
      "location": "Denver, US",
      "country_code": "US",
      "connections_count": 500,
      "profile_picture_url": "...",
      "job_level": "Director",
      "source": "waterfall",
      "icp_tier": 2,
      "ranking": 1,
      "created_at": "2026-07-06T..."
    }
  ],
  "pagination": { "total": 128, "page": 1, "per_page": 25, "has_more": true }
}

Get a person

GET/people/:id

Returns the full person record plus list_ids, the ids of every list they are saved to.

Find people

POST/people/find

Describe who you want in plain English. Hunch compiles it into a prioritized title cascade (the ideal role first, adjacent roles behind it, a sensible fallback last), runs it at each activated account, and attaches a verified work email to every hit. Matches are saved to People and returned in the response.

Body fields

querystringrequired

Who you want, in plain English. e.g. "The demand generation leader. If none, whoever runs marketing. Skip agencies and consultants."

account_idsstring[]optional

Specific activated accounts to search. Defaults to the most recent activated accounts.

max_accountsintegeroptional

How many accounts one call sweeps. Default 20, max 50. For bigger rosters, call again with account_ids batches.

Request

curl -X POST https://usehunch.co/api/v1/people/find \
  -H "Authorization: Bearer hunch_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "VP of Sales or CRO in the US. If neither, whoever runs revenue operations.",
    "account_ids": ["acc_123"]
  }'

Response

{
  "data": {
    "found": 3,
    "accountsSearched": 1,
    "tiers": 3,
    "cascade": [ ... ],
    "contacts": [ { "id": "...", "full_name": "...", "email": "...", "icp_tier": 1, ... } ]
  }
}

icp_tier on each match tells you which tier matched: 1 is the ideal role, higher numbers are fallbacks. Searches can take a minute or two for many accounts since lookups are paced for reliability.

Load an account's roster

POST/people/sync

Loads (or refreshes) the full employee roster for an activated account into People. This runs automatically when an account is activated, so you only need it for accounts activated before rosters existed or to refresh one.

Body fields

account_idstringrequired

An ACTIVE account id.

Response

{ "data": { "account_id": "...", "synced": 43 } }

Reveal a work email

POST/people/:id/email

Returns the verified work email for a person and stores it on the record. Idempotent: if the email is already known it is returned without a new lookup. email is null when no verified address exists.

Response

{ "data": { "id": "...", "email": "lena@fielder.app" } }

Reveal a phone number

POST/people/:id/phone

Returns a mobile or direct phone for a person and stores it. Coverage is focused on the US;phone is null when none is found.

Push people to your CRM

POST/people/crm-push

Pushes people to the connected CRMs as Contacts. Each person's company record is created or updated first (with its signal context), so contacts always land linked to an account. People need a verified email first: email is the dedupe key in both CRMs, and people without one are skipped and counted in skippedNoEmail.

Body fields

contact_idsstring[]required

Person ids to push (max 100 per call).

providerstringoptional

hubspot or salesforce. Omit to push to every connected CRM.

Response

{
  "data": {
    "pushed": 4,
    "failed": 0,
    "skippedNoEmail": 1,
    "providers": ["hubspot"],
    "results": [ { "contactId": "...", "provider": "hubspot", "ok": true, "created": true } ]
  }
}

People lists

GET/people/lists

Lists every saved people list with member counts.

POST/people/lists

Body fields

namestringrequired

List name, e.g. "Q3 outreach - RevOps leaders". Creating an existing name returns that list.

DELETE/people/lists/:id

Deletes a list. The people in it are kept.

POST/people/lists/:id/members

Body fields

addstring[]optional

Person ids to add (max 500 per call).

removestring[]optional

Person ids to remove.

Response

{ "data": { "list_id": "...", "added": 12, "removed": 0 } }

Enrich an account

POST/accounts/:id/enrich

Runs enrichment for an ACTIVE account on demand: full company profile, workforce breakdown by department and country, and the employee roster into People. This is the same pipeline that runs automatically on activation, so you only need it to refresh or backfill. Returns the updated account.

PreviousAccounts Next Signals