How to build a B2B prospect list from title, industry and location filters

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 100 free credits — no card

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, 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 waterfall endpoints. 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. 100 free credits, no card.

2. POST your filters with a page size.

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.

{
  "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 for the full record, or to the 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 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.

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.

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 and this is a different billing path.

The per-credit rate varies by package tier, so the money figure comes from the pricing page, 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, so the deep calls only land on rows that survived a look.

• LinkedIn profile search API — the other search endpoint, name-shaped and 1-based
• Person enrichment API — turn a result URL into a full record
• Email finder API — a work email from the result URL, zero-billed on a miss
• Company enrichment API — the company behind the person
• All endpoints — the full catalog
• Pricing — credit packages and tier rates
• Search, find, verify — the chain
• 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 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 as a separate call, which is also why a miss there costs you nothing.

Is totalElements an exact count?
Treat it as the source'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. 100 free credits on signup, no card.

Run your first filtered search in two minutes. Get 100 free credits