REST API / People

Search people

Find people who match your filters. Each record says why it matched, and each email says how and when it was verified.

POST/v1/people/searchMCP: search_people

Records

1 per record returned

Meters

records + requests / 5 hrs, records / week

Empty result

0 records · 1 request

Body parameters

titlestring[]

Job titles. Fuzzy-matched: "VP Sales" also finds "Vice President, Sales".

seniorityenum[]

c_level, vp, head, director, manager, ic

functionenum[]

revenue, marketing, engineering, product, ops, finance, hr

company_domainstring[]

Only people at these companies.

employeesstring

Range, e.g. "50-200".

industrystring[]

Leadsets industry slugs, e.g. "saas".

countrystring[]

ISO 3166-1 alpha-2.

has_verified_emailboolean

Only return people with a verified work email.

limitinteger

1–100. Default 25.

cursorstring

From next_cursor of the previous page.

Response

items (max limit), next_cursor for the next page, usage with what this call counted and what's left, and request_id.

Errors

Status	type	Meaning
`400`	`invalid_request`	A filter value isn't valid. The message names it.
`401`	`unauthorized`	Missing or revoked key.
`402`	`free_records_exhausted`	The 1,000 free records are used up.
`429`	`window_full`	A five-hour or weekly limit was reached. See Retry-After.
`429`	`too_many_concurrent`	Too many searches running at once for your plan.

cURLTypeScriptPython

curl https://api.leadsets.ai/v1/people/search \
  -H "Authorization: Bearer $LEADSETS_KEY" \
  -H "Idempotency-Key: 7c1e…" \
  -d '{
    "title": ["VP Sales"],
    "country": ["US"],
    "employees": "50-200",
    "has_verified_email": true,
    "limit": 25
  }'

Response200 OK

{
  "items": [{
    "person_id": "p_8Hk2",
    "full_name": "Maya Chen",
    "title": "VP Sales",
    "company": { "name": "Northwind Analytics", "domain": "northwind.io" },
    "email": { "address": "maya@northwind.io", "status": "verified",
               "checked_at": "2026-11-02" },
    "match_reasons": ["title", "size", "country"]
  }],
  "next_cursor": "c_9f2…",
  "usage": { "search_records_counted": 25, "search_records_left_5h": 475, "search_requests_left_5h": 2499 },
  "request_id": "req_abc123"
}