People Search API: Filters, or a Prompt Instead?

Find VPs of Sales at 51 to 200 person companies, and see exactly which filters were used. Paste this into your agent:

Set up https://monid.ai/SKILL.md, and then use Monid to find VPs of Sales at companies with 51 to 200 employees, tell me how many people match in total, and list the filter values you sent.

One prompt runs the search and reports the filters. 1 min setup · 5-10 hrs saved.

You want a list of people by job title, seniority and company size, and you want to get it from an API instead of a web app. This guide shows the call, what comes back (we ran it live on 2026-10-16), and the part that costs people an afternoon: the same search with one wrong value returns zero, or six times too many. It also covers the other shape of people search, where you send a sentence instead of filters. Fair disclosure: you are on the Monid blog, Monid sells the endpoint we run, and Ploid is a content partner. Ploid is not in the Monid catalogue, and what we say about it comes from its public site. The search runs through Monid, the OpenRouter for agent tools: one key, one balance, every tool priced per call.

What is the easiest way to run a people search through an API?

Monid. Install it once, add a key, and your agent calls Apollo's people search with a title, a seniority and a company size, and gets matching people back as typed JSON. No web app login, no export button, no actor to configure.

• Pay per call. People search is free: it billed $0.00 on each of our runs (Verified 2026-10-16 on the people enrichment tools page). Revealing a contact later is a separate paid call. Buy calls as you need them: no monthly plan and no minimum top-up. Discovery and inspection are free; only a run bills.
• One install, every API. The same key and the same balance call this search and every other tool on Monid. When you want the company behind a person, it is another call on the same balance, not another vendor account.
• Lives inside your agent. Install the CLI, add your key, run the prompt above, and the tool is there whenever your agent needs a list, on demand, with nothing to keep running. Your agent reads SKILL.md and learns the rest, so setup is about a minute.

Searching 100 pages of results costs $0.00 on this endpoint (Verified 2026-10-16). The money starts only when you reveal an email or a phone number.

How do you search for people by title, seniority and company size?

Send the filters as query parameters to /mixed_people/api_search on the provider apollo. The endpoint summary describes a database of 230M plus people, and the filters include job title, seniority, location, employer, company size, revenue and the technologies a company uses.

Monid fits an agent because the filters are a schema it can read before it runs, so it does not have to guess a value.

For agents

Grab an API key at app.monid.ai, then paste this to your agent and hand it the key:

set up https://monid.ai/SKILL.md

It learns the whole discover, inspect, run workflow itself. More in the agent quickstart.

For humans

npm install -g @monid-ai/cli
monid keys add -k <your-api-key> -l main

More in the CLI quickstart.

Inspect, then run one

monid inspect -p apollo -e /mixed_people/api_search
monid run -p apollo -e /mixed_people/api_search \
  --query '{"person_titles[]":["VP of Sales"],"person_seniorities[]":["vp"],"organization_num_employees_ranges[]":["51,200"],"per_page":5}' \
  -w -o people.json

The inspect output is the part to read first. It lists the accepted seniority values (owner, founder, c_suite, partner, vp, head, director, manager, senior, entry, intern) and says that headcount ranges look like '1,10' or '250,500', with a comma.

Or hand the whole job to an agent

Can you build a people search yourself with Python?

Yes, if you have a data source to query. The Python is the small part: a requests loop over page and per_page, a dictionary of filters, a file to write. The hard part is the data behind it, which is a licence, a contract or a crawl that you own.

Two things are not small. The first is the paging ceiling: this endpoint serves at most 100 people per page and 500 pages, which is 50,000 records per query, so a broad query has to be split with more filters. The second is the vocabulary of the filters, which is different for every vendor and covered in the section on zeros below. You write that knowledge down once per vendor and it does not transfer.

The Monid route is the one for repeat work. The call is already wrapped, the schema is readable at run time, and a search costs $0.00 (Verified 2026-10-16). If you only want the data and your own Python is the goal, build the loop; if the list is the goal, skip it.

What does a people search return, and what can you build with it?

A people search returns a count and a page of previews, not contacts. We ran the search for VPs of Sales at companies sized 51,200 on 2026-10-16 with per_page set to 3, so the fields below are what came back.

The response

{ "total_entries": 28587,
  "people": [
    { "id": "60b9fda2c5ec450001a3f828",
      "first_name": "Avinash",
      "last_name_obfuscated": "So***i",
      "title": "VP Sales",
      "last_refreshed_at": "2026-10-13T22:35:38.867+00:00",
      "has_email": true, "has_city": true, "has_state": true, "has_country": true,
      "has_direct_phone": "Yes",
      "organization": { "name": "Fretron", "has_industry": true, "has_phone": true,
                        "has_employee_count": true, "has_revenue": false } } ] }

total_entries is how many people match, and it is the most useful number in the response. Each person has an Apollo id, a first name, a last name cut to its first two and last letters, a title and a last_refreshed_at date. The has_ flags say whether a field exists on the record without giving it to you. There is no email address and no phone number in the search response; for that the person's id goes to /people/match, which is a paid call.

What you can build with it

• A sized market. Read total_entries for a title and a headcount band before you buy anything. It answers "how many VPs of Sales are there at 51 to 200 person companies" in one free call.
• A shortlist to reveal. Page through the free search, keep the people you want, and pay to reveal contact data only for those. Exporting Apollo leads by API walks through that loop.
• A refresh job. last_refreshed_at is on every row, so a weekly run can skip people whose record has not moved.
• A comparison of vendors. Run the same filters against a second source and compare counts, and compare the counts.

Why does a people search return zero, or far too many people?

Because the filter was accepted and then matched nothing, or was dropped. We ran four searches on 2026-10-16 that differed by one field each, and none of them raised an error.

seniority "vp",             size "51,200"  ->  28,587 people
seniority "vice_president", size "51,200"  ->       0 people
seniority "vp",             size "51-200"  ->  159,903 people
seniority "vp",             no size filter ->  159,903 people

Why did a reasonable value return zero?

Because vice_president is not in the enum. Both strings are fair English for the same idea, only vp is accepted, and the API returned a clean empty set with a 200 status. An empty result looks exactly like "nobody matches." The accepted values are printed by monid inspect, and reading them there is free.

Why did the count jump to 159,903?

Because the size filter was written as 51-200 and the endpoint wants 51,200. The hyphenated run returned the same 159,903 as the run with no size filter at all, and the same three people on the first page (two of them swapped places). That equality is the evidence that the constraint was discarded rather than reinterpreted. You asked about mid-sized companies and received every VP of Sales.

A plausible number that answers a different question is the dangerous one. A crash you notice and a zero you investigate. A count six times too large reaches a spreadsheet and then a campaign.

How do you catch it?

Three habits, all free on a free endpoint.

• Predict the magnitude first. Say how many people you expect before reading a row. Tens of thousands of VPs of Sales at mid-sized companies is plausible; zero and 159,903 are not the same answer to the same question.
• Probe by removal. When a count surprises you, delete one field and run again. If the count does not move, that field was doing nothing.
• Read the enums from the schema. A schema you can read at run time turns a vocabulary problem into a lookup, which is why an agent should call inspect before run. Wiring a whole prospect search the same way is in the B2B prospecting tool guide.

Does the same query return the same people?

The same set, not always the same order. Our hyphenated run and the no-size run returned the same three people with the second and third swapped. Page by id, and do not rely on position.

What is a people search API that takes a prompt instead of filters?

It is an API where you send a sentence and the service works out the query. Ploid is one example, and it is a content partner of ours. Everything here comes from its public documentation and OpenAPI spec, read on 2026-10-16; we did not run it.

Ploid's base URL is https://api.ploid.com/v1, authenticated with a bearer token. Its POST /v1/search takes a query string of up to 4,000 characters that the spec calls a semantic query, a type of instant, fast, auto or deep, a num_results count, and optional filters for title, company, location and seniority. A criteria field takes up to five plain-English conditions. Up to 150 results come back inline, and larger requests run as a background set. Around search it lists datasets, a contacts API, monitors and a per-person report.

Spend is controlled in a different place than with a per-call endpoint. Credits are read from GET /v1/account/credits, and spending caps are set per API key rather than per request. With a filter API you know the price of a page before you send it. With a prompt-shaped one the service decides how much work the sentence needs, so a cap on the key is how you bound the bill.

The failure modes differ. A filter API fails at the edge, where your word meets its enum, as the four runs above show. A prompt-shaped API fails in the middle, where its reading of your sentence meets its index, and you find that by checking the people it returned. Neither is better in general. If you cannot state the query as a filter, a sentence is doing real work for you. If you can, the interpretation layer sits between you and a query you already knew how to write.

For an agent the two meet in the middle. It reads the schema with inspect, picks the values, and reports which ones it sent, which is what the prompt at the top of this post asks for. That keeps a query you can show someone afterwards, and the vocabulary lookup is done for you.

Which endpoint should I use for which job?

Prices Verified 2026-10-16 with monid inspect and monid_discover. Search first, which costs nothing, and reveal only the people you keep. A mobile number is a separate, higher tier on /people/match, so inspect it before a batch.

See also: Apollo email finder API for what the reveal step returns.

When is another route a better fit?

You need the same rows twice. A filter is a specification you can store and run again. A sentence is an instruction, and nothing guarantees the same breakdown next time. Anything that feeds a report or a diff wants the filter.

Your query is already exact. "Everyone at these 40 domains" is not a request that gains from interpretation. The q_organization_domains_list[] filter takes up to 1,000 domains per request, and a sentence adds only a chance of being misread.

You are exploring. If you do not yet know the right title or the right industry word, a prompt-shaped search is faster than learning a taxonomy first. This is where Ploid-style search earns its place.

You need a whole market, not a list. One query is capped at 50,000 records. A bought dataset covers a full segment.

And the disclosure again: we resell the filter-shaped endpoint, so weigh that list accordingly. The habit that pays off whichever you use is checking the count against a number you expected before trusting a row.

Conclusion

The easiest way to run a people search through an API is to call the free search through Monid: $0.00 a search (Verified 2026-10-16), one key for this and every other tool, about a minute to set up, and ready inside your agent whenever you need it. Contact reveals are the only paid step, at $0.026 each.

Two things matter more than the tool. A wrong filter value does not raise an error: it returns zero or it is dropped, so predict the count first and probe by removal when it surprises you. And read the accepted values from the schema, not from memory.

How we estimated the time saved: reading one vendor's filter taxonomy and writing the paging client is roughly 3 to 6 hours, and tracking down silent zeros and dropped filters is another 2 to 4 hours. That is 5 to 10 hours. The 1 minute is the install, key and first call once you already have a Monid key.

Free next step: run monid inspect -p apollo -e /mixed_people/api_search, then make one call with a seniority and a size band you know and compare total_entries with the number you expected. Start at monid.ai.

FAQ

Published August 2026.