Data catalog · Search
Filter on job title, industry, location, company domain and headcount range, and get a paginated list of people back with their LinkedIn URLs. Priced per result returned, not per seat and not per search, so cost tracks the size of the page you ask for.
Last updated September 22, 2026
Describe the people you want (titles, industries, locations, company domains, headcount range) and `POST /people_search` returns a paginated list of them, each with a LinkedIn URL you can enrich further. **[Get 25 free credits — no card](https://app.richapi.ai)**
Five of them are **arrays**, not strings: `job_title`, `industry`, `location`, `domain` and `linkedin`. Pass `["VP Sales", "Head of Sales"]`, not `"VP Sales"`. Headcount is a pair of integers, `employee_size_start` and `employee_size_end`. And two fields are required on every request: `limit` (default 10) and `page`. `page` is **zero-based**. The first page is `0`. This is the field most likely to give you a duplicate-heavy list on your first run, because the other search endpoint in this catalog, [profile search](/api/linkedin-profile-search), paginates from 1. Two search endpoints, two conventions, and nothing in the response will warn you. The account-side filters — `domain`, `industry`, `employee_size_start`, `employee_size_end` — narrow by the company; `job_title`, `location` and `linkedin` narrow by the person. Combining both is what this endpoint is for: every VP of Engineering at a 51-to-200-person SaaS company in Germany is one request, not a saved search in a tool somebody has to buy a seat for.
This endpoint is **not** a multi-provider waterfall. Billing is on HTTP 2xx. A thin 2xx still bills. 4xx and 5xx bill nothing, on any endpoint. The miss-free rule on the email finder, phone finder and email verifier does not apply here.
**1. Get a key.** Sign up at [app.richapi.ai](https://app.richapi.ai). 25 free credits, no card. **2. POST your filters with a page size.** ```bash curl -X POST https://api.richapi.ai/api/v1/people_search \ -H "x-api-key: $RICHAPI_KEY" \ -H "Content-Type: application/json" \ -d '{ "job_title": ["VP of Engineering", "Head of Engineering"], "industry": ["Computer Software"], "location": ["Germany"], "employee_size_start": 51, "employee_size_end": 200, "limit": 25, "page": 0 }' ``` **3. Read the page, not just the results.** ```json { "content": [ { "firstname": "example", "lastname": "example", "headline": "example", "url": "example" } ], "totalElements": 1, "totalPages": 1, "numberOfElements": 1, "number": 0, "size": 10, "first": true, "last": true } ``` `numberOfElements` is how many results this page actually returned, and it is the field your bill is computed from. `totalPages` and `last` tell you when to stop looping. Loop on `last`, not on a page count you guessed. **4. Feed the URLs into enrichment.** Each result carries a `url`. Send it to [person enrichment](/api/person-enrichment) for the full record, or to [the email finder](/api/email-finder), which accepts a LinkedIn URL and bills nothing when nobody has the address. **5. Or search from your agent.** The [hosted MCP server](/integrations/claude) exposes `people_search` as a tool: ``` Find 25 heads of engineering at German software companies with 51-200 staff, then get work emails for the first 10. ``` Set a `limit` in the instruction. An agent that decides its own page size is deciding its own spend on a per-result endpoint.
| Field | Type | What it is | |---|---|---| | `content` | array | The results on this page | | `content[].firstname` / `.lastname` | string | Name, split | | `content[].headline` | string | The profile headline | | `content[].url` | string | LinkedIn profile URL, the key to every enrichment call | | `numberOfElements` | integer | Results on this page — the number you are billed on | | `size` | integer | The page size that was applied | | `number` | integer | Current page index, zero-based | | `totalElements` | integer | Total matches for the filter set | | `totalPages` | integer | Total pages available | | `first` / `last` | boolean | Whether this is the first or final page |
`people_search` bills `0.1 credits per result`, charged against `numberOfElements`. There is no flat call fee on top, and no cost example here means anything without a result count attached to it. | What you ask for | Results returned | Credits | |---|---|---| | One page, `limit: 10` | 10 | `1 credit` | | One page, `limit: 25` | 25 | `2.5 credits` | | Four pages of 25 | 100 | `10 credits` | | A 1,000-person list | 1,000 | `100 credits` | This is a per-result endpoint, not a waterfall. Do not treat a zero-result 2xx as the miss-free guarantee. Confirm a zero-result page on your own key before you budget around it. Do not read a zero-result page as the waterfall's zero-on-miss guarantee; that guarantee belongs to [the finders and the verifier](/api/email-verifier) and this is a different billing path. The per-credit rate varies by package tier, so the money figure comes from [the pricing page](/pricing), not from multiplying these numbers by a rate you remember.
**Building a list without buying a prospecting seat.** The sales-intelligence pricing model is per user per year, whether you pull 40 contacts or 40,000. This is per result returned, so a one-off list for a campaign costs what the list costs and nothing in the months you do not run one. There is no prospecting UI here — we are the API behind one. **Refreshing a segment on a schedule.** Run the same filter set monthly, diff it against what you have, and enrich only the new rows. Because you pay per result rather than per search, a narrow filter you run often is cheap and a broad filter you run once is where the money goes. **Agents that need candidates before they need records.** Search returns cheap, shallow rows — name, headline, URL. An agent can pull a page, judge which rows are worth the full record, and only then spend a per-call credit on [enrichment](/api/person-enrichment), so the deep calls only land on rows that survived a look.
- [LinkedIn profile search API](/api/linkedin-profile-search) — the other search endpoint, name-shaped and 1-based - [Person enrichment API](/api/person-enrichment) — turn a result URL into a full record - [Email finder API](/api/email-finder) — a work email from the result URL, zero-billed on a miss - [Company enrichment API](/api/company-enrichment) — the company behind the person - [All endpoints](/api) — the full catalog - [Pricing](/pricing) — credit packages and tier rates - [Search, find, verify — the chain](/use-cases/list-build-and-verify) - [Tech stack lookup](/api/tech-stack-lookup)
**What am I charged for?** Results. Billing is per result returned, measured on `numberOfElements`, on 2xx responses. A 4xx or 5xx bills nothing. This is not a waterfall endpoint, so the zero-on-miss rule does not apply here. **How do I control what a search costs?** With `limit`. It is the only lever, it defaults to 10, and on a per-result endpoint it is a spending control as much as a page size. Set it explicitly on every call, especially in code an agent drives. **Why is my second page returning what my first page did?** `page` is zero-based here. If you started at `1` you skipped a page; if you are porting code from [profile search](/api/linkedin-profile-search) you are off by one in the other direction. **Can I filter by company as well as by person?** Yes. `domain`, `industry`, `employee_size_start` and `employee_size_end` filter on the company, and they combine with the person filters in one request. `linkedin` takes company LinkedIn URLs. **Do the results include email addresses?** No. You get `firstname`, `lastname`, `headline` and `url`. Emails come from [the email finder](/api/email-finder) as a separate call, which is also why a miss there costs you nothing. **Is `totalElements` an exact count?** Treat it as the provider's count for your filter set at request time, and expect it to move between runs as the underlying data does. Page on `last`, not on an arithmetic assumption about `totalElements`. **Can I call this from Claude or Cursor (MCP)?** Yes, the hosted MCP server exposes `people_search` as a tool with no install. Pin `limit` in the instruction you give the agent, because on a per-result endpoint page size is the spending control and an agent will otherwise pick its own. **Do I need a credit card?** No. 25 free credits on signup, no card.
Run your first filtered search in two minutes. **[Get 25 free credits](https://app.richapi.ai)**