API Reference › Search › Search for people

Phase 2 / planned endpoint

POST/search_people

Search for people

Search the planned FetchSet contact dataset by name, role, company, country, seniority, industry, or department. Results are ranked by match strength and returned in the shared FetchSet envelope.

Request body

JSON object

Bearer auth required

querystring

Free-text search across person name, company name, title, and headline.

Example: Account Executive

company_domainstring

Exact company-domain filter without a protocol.

Example: northstar.dev

countrystring

Exact full English country name.

Example: United States

seniorityenum

Exact seniority filter.

EntrySeniorManagerDirectorVPHeadC SuiteOwner

departmentenum

Exact department filter.

SalesMarketingEngineeringFinanceOperations

limitinteger

Number of results to return. Draft range: 1–25.

Example: Default: 10

Response

200 · Processed

application/json

A processed request returns status: "ok". The nested result may be empty; in that case tokens_charged remains zero.

results.results[]

Ranked person records that matched the query and filters.

results.total

Total matching records available for pagination.

metadata.tokens_charged

Credits charged for the returned result. Zero for a miss.

metadata.fair_use

Remaining records and reset timestamps for applicable plan windows.

Errors

400

Malformed request body

401

Missing or invalid API key

422

Unsupported filter value

429

Rate limit exceeded