// PEOPLE SEARCH API
People search API: find professionals by title, company and location
Updated November 20, 2026
A people search API lets software find professionals by attributes instead of by name. Descovo's searches 700M+ profiles by title, company, seniority, function, industry and location, or from a plain-English description. Each person returned costs 1 credit, counting matches is free, and the same key works over REST and MCP.
Search people with structured filters
Post filters to https://api.descovo.com/v1/people/search. This request finds Account Executives who hold that title at one company: the company goes in top-level currentCompanies, so the title has to hold at that same job and not at a previous one.
curl -X POST https://api.descovo.com/v1/people/search \
-H "Authorization: Bearer $DESCOVO_API_KEY" \
-H "Content-Type: application/json" \
-d '{"searchParams":{"jobTitleV3":{"anyOf":[{"type":"plain","term":"Account Executive"}]}},"currentCompanies":[{"domain":"ramp.com"}],"pageSize":10}'Results come back a page at a time. Pass the cursor from one response to get the next page; set pageSize to the number of people you will actually look at, because each person returned is charged.
Count the matches for free before you search
Send the same filters to https://api.descovo.com/v1/people/count to learn how many people match without loading any of them. Counting costs nothing, so you can widen or narrow the filters until the number fits your budget, and only then run the search.
Or describe who you want in plain English
https://api.descovo.com/v1/people/ask takes a sentence instead of filters, turns it into filters and runs the search. It costs 2 credits to read the question plus 1 per person returned.
curl -X POST https://api.descovo.com/v1/people/ask \
-H "Authorization: Bearer $DESCOVO_API_KEY" \
-H "Content-Type: application/json" \
-d '{"query":"Heads of data at fintech companies in New York","pageSize":10}'What each search route costs
| Route | What it does | Cost |
|---|---|---|
| /people/search | People by filters | 1 credit per person returned |
| /people/count | How many people match | Free |
| /people/ask | People from a plain-English question | 2 credits + 1 per result |
| /companies/search | Companies by name, domain, headcount, industry, location and technology | 1 credit per company returned |
| /companies/count | How many companies match | Free |
| /jobs/search | Open roles by title, company and location | 1 credit per posting returned |
Search costs 1 credit per profile, company, or job returned; count queries are free.
From a search result to an email or phone
Search returns who a person is and where they work. Contact details are a separate, optional step: build the profile URL from a result's primary_slug (https://www.linkedin.com/in/<slug>) and pass it to the contact enrichment API for one person, or to the bulk email finder for a list. You pay for contact details only for the people you choose.
The same search, from an AI agent
The API key that calls REST also works on the hosted MCP server at https://mcp.descovo.com/mcp. An agent in Claude Code or Cursor can count, search and narrow in a conversation, spending the same credits. Connect it in one command.
What a people search API will not do
- It will not return contact details in search results. Emails and phones come from a reveal, which you run only for the people you want.
- It will not guess filter values. Unknown fields in a request are rejected and not charged, so a misspelled filter cannot silently become a broader, more expensive search.
- It will not include people who have asked to be removed.
Frequently asked questions
- What is a people search API?
- An API that returns professional profiles matching attributes you specify, such as job title, employer, seniority and location, so software can build lists of people without a person searching by hand.
- How many people can Descovo search?
- 700M+ professional profiles and 50M+ companies.
- How much does a people search cost?
- 1 credit for each person returned. Count queries are free. Plans start free with 500 credits, then $99 a month for 5,000 credits.
- Can I search without knowing the filter syntax?
- Yes. The ask route accepts a plain-English description such as "Heads of data at fintech companies in New York" and builds the filters for you, for 2 credits plus 1 per result.
- Does a search result include the person's email?
- No. Search returns the profile. Email and phone come from a separate reveal, charged only when a field is found.
- Is there a free tier?
- Yes. A new account gets 500 credits once, with no card required, on the same API as paid plans.
TRY IT
Run a count, then your first search.
A new account starts with 500 credits and no card. That is enough to find 250 work emails, or 100 people with both a work email and a direct phone.