Skip to main content
POST
/
person-search
curl --request POST \
  --url https://api.tryhuntr.com/person-search \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "semantic_query": "VPs of Sales at cybersecurity companies",
  "filters": {
    "location": {
      "include": [
        "US"
      ]
    }
  },
  "pagination": {
    "size": 10
  }
}
'
{
  "success": true,
  "request_id": "req_1746123456_ps1x2y",
  "people": [
    {
      "name": "Patrick Collison",
      "linkedin_url": "https://www.linkedin.com/in/patrickcollison",
      "headline": "CEO at Stripe",
      "title": "CEO",
      "company": "Stripe",
      "website": "https://stripe.com",
      "location": "San Francisco, California, United States"
    }
  ],
  "total": 4,
  "resolved_query": {
    "currentJobTitle": {
      "include": [
        "VP Sales",
        "Vice President Sales"
      ]
    },
    "keyword": {
      "include": [
        "cybersecurity"
      ]
    },
    "location": {
      "include": [
        "US"
      ]
    }
  },
  "pagination": {
    "token": "eyJ...",
    "size": 1
  },
  "price": 0.0003,
  "credits_remaining": 4.9997
}

Authorizations

​
x-api-key
string
header
required

Your Huntr API key. Get one at tryhuntr.com. Pass as x-api-key header on all authenticated requests.

Body

application/json
​
query
object
required

At least one filter required. Combine multiple filters — all must match (AND). See each field for match rules. Use POST /person-search-count to preview total for free.

​
semantic_query
string

Natural-language description of the people to find. Mutually exclusive with query. The response includes resolved_query for deterministic pagination.

Maximum string length: 8000
​
filters
object

Optional hard constraints used only with semantic_query. Uses the same people filter fields and shapes as query. Explicit fields override generated fields.

​
pagination
object

One page per request (no auto-fetch). size: companies/people returned this call (default 100, max 200). token: copy from the previous response pagination.token to get the next page — keep the same query. Tokens expire; do not change the query between pages.

Response

Person search results.

​
success
boolean
​
request_id
string
​
people
object[]

Matching people.

​
total
integer

Total people matching the query in the database (not the length of people).

​
resolved_query
object

Final structured query generated for a semantic request, including explicit filters. Send this as query with the pagination token for later pages.

​
pagination
object

Upstream pagination cursor when more pages exist. Pass pagination.token back on the next request with the same query.

​
price
number

Cost in USD. $0.0003 × number of people returned.

​
credits_remaining
number