---
title: "People Search API Reference | Leadsets Docs"
description: "POST /v1/people/search: filter by title, seniority, function, company, size, industry and country. Match reasons and verified emails per record."
canonical: https://leadsets.ai/docs/api/people-search
updated: 2026-11-09
---

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/search MCP: search_people

Records

1 per record returned

Meters

records + requests / 5 hrs, records / week

Empty result

0 records · 1 request

## Body parameters

title string[]

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

seniority enum[]

c_level, vp, head, director, manager, ic

function enum[]

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

company_domain string[]

Only people at these companies.

employees string

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

industry string[]

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

country string[]

ISO 3166-1 alpha-2.

has_verified_email boolean

Only return people with a verified work email.

limit integer

1–100. Default 25.

cursor string

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. |

cURL TypeScript Python

```
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
 }'
```

Response 200 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"
}
```

---

Leadsets by Mobylogix LLC, 10160 hwy 242, Conroe, TX, 77385, US. Facts for AI assistants: https://leadsets.ai/llm · Site index: https://leadsets.ai/llms.txt · Every page: https://leadsets.ai/llms-full.txt