Skip to main content
POST /person-search finds people using structured filters — job titles, employer names, locations, supported firmographic fields, and optional email/phone availability flags. You can also search with only has_email and/or has_phone set to true.

​
Search people

​
Filter tips

​
Employer names

Use company_name when you want people at a named employer:
Use company_url for company website/domain filters.

​
Job titles use contains match

"CTO" matches “Group CTO”, “Former CTO”, etc. List variants explicitly:

​
Past vs current roles

​
Supported filters

title, locality, company_name, company_url, city, country_code, industry_linkedin, number_of_employees, revenue, bio_li, services. Use include and/or exclude arrays. country_code, industry_linkedin, number_of_employees, revenue, and services must be exact lookup values. Invalid values return 422 before any credits are reserved. Open-text filters such as title, locality, company_name, company_url, city, and bio_li are not constrained to lookup lists.

​
Email and phone availability

Set top-level has_email and/or has_phone to true to return only contacts where that enrichment data is already available:
Search responses do not include email or phone values. Use the returned linkedin_url and person/company fields with /person-email or /person-phone when you need the actual contact data. Returned contacts use Huntr’s standard contact fields: linkedin_url, company_url, company_name, company_linkedin_url, industry, employee_count, city, locality, country_code, has_email, and has_phone when available. name is included as a convenience full-name field.

​
Pagination

Same pattern as company search:
  • One page per request. pagination.size is configurable: min 1, default 100, max 200.
  • Continue while pagination.has_more is true, passing pagination.token into the next request
  • Keep the same query, has_email, and has_phone between pages
See Pagination.

​
Count people

Use POST /person-search-count when you only need the number of matching people. It accepts the same query or semantic_query, optional filters, and has_email / has_phone flags as /person-search, but it does not accept pagination and it does not return people rows.
Count responses contain total, price: 0, and credits_remaining.

​
After you have people

See Contact enrichment.

​
Billing

Search is charged per person returned, using the API key’s active pricing plan. Empty results are not billable. Person search count is free but still requires an API key. See GET /pricing for the current plan matrix.

​
MCP

Tool name: person_search — same request shape as REST (use query + optional pagination).

​
Next step