# People search API: find professionals by title, company and location

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

Source page: https://descovo.com/people-search-api
Updated: November 20, 2026

## 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:

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

Python:

```python
import os, requests

r = requests.post(
    "https://api.descovo.com/v1/people/search",
    headers={"Authorization": f"Bearer {os.environ['DESCOVO_API_KEY']}"},
    json={
        "searchParams": {
            "jobTitleV3": {"anyOf": [{"type": "plain", "term": "Account Executive"}]},
        },
        "currentCompanies": [{"domain": "ramp.com"}],
        "pageSize": 10,
    },
    timeout=60,
)
body = r.json()
print(len(body["data"]["data"]), "people,", body["credits"]["charged"], "credits")
```

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.

Ask:

```bash
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](https://descovo.com/contact-enrichment-api) for one person, or to the [bulk email finder](https://descovo.com/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](https://descovo.com/developers).

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

## Next

- [Get an API key](https://descovo.com/sign-up)
- [REST reference](https://descovo.com/docs/rest)
- [Contact enrichment API: email and phone for a person](https://descovo.com/contact-enrichment-api)
- [Bulk email finder](https://descovo.com/bulk-email-finder)
- [REST API reference](https://descovo.com/docs/rest)
