> ## Documentation Index
> Fetch the complete documentation index at: https://docs.outbound.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Find people

> Describe who you want, refine it with filters, count before you pay, and keep the search.

This guide takes a plain-language description of an audience to a page of people, then shows how to make the search precise, size it for free, page through it and keep it.

## Search with a description

Describe who you want in `query`. The search turns it into filters and answers with them:

```bash theme={null}
curl https://api.outbound.dev/v1/people/search \
  -H "Authorization: Bearer $OUTBOUND_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "operations directors at logistics companies in Portugal", "limit": 10}'
```

Read what came back besides the people:

* `filters`: what the search ran with. This is the search from now on.
* `unresolvedCriteria`: parts of the query that could not be turned into a filter. When it is not empty, the search is broader than the query.
* `closestCompanyMatches`: companies the query named that had several same-named matches, and the one the search chose.

A search takes exactly one of `query`, `filters`, `savedSearchId` or `savedSearchName`.

## Refine the filters

Once you have filters, edit them directly. `GET /v1/people/filters` lists every filter and the values it takes:

```bash theme={null}
curl "https://api.outbound.dev/v1/people/filters?field=job_title_levels" \
  -H "Authorization: Bearer $OUTBOUND_API_KEY"
```

```json theme={null}
{
  "fields": {
    "job_title_levels": {
      "valueShape": "term",
      "values": [
        { "label": "Director", "value": "director" },
        { "label": "VP", "value": "vp" }
      ]
    }
  }
}
```

Free-text filters, such as job titles, companies, schools and skills, have no fixed values. Their entry names the autocomplete query that suggests them:

```bash theme={null}
curl "https://api.outbound.dev/v1/people/autocomplete?field=title&q=head%20of%20operations" \
  -H "Authorization: Bearer $OUTBOUND_API_KEY"
```

Send a suggestion's `name` as the filter value. A value that matches nothing answers `422` with `filter_value_unresolved`, naming the filter in `param`.

## Count before you pay

Counting is free. Send the same filters to `POST /v1/people/count`:

```bash theme={null}
curl https://api.outbound.dev/v1/people/count \
  -H "Authorization: Bearer $OUTBOUND_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"filters": {"job_title_levels": ["director", "vp"], "job_title_role": ["operations"]}}'
```

A new count runs in the background. The first answer is `202` with `status` `pending`. Send the same request every few seconds until it answers `200`:

```json theme={null}
{ "status": "ready", "total": 1246019, "filters": { "job_title_levels": ["director", "vp"], "job_title_role": ["operations"] } }
```

A count takes up to about a minute and a half.

## Page through the results

Send the filters with the page's `nextCursor` as `cursor`. Only a missing `nextCursor` marks the end. Each page is charged for its own people, so `limit` sets what a page can cost: 25 people at most \$0.0025. See [Pagination](https://docs.outbound.dev/pagination.md).

## Look up one person

`linkedinUrl` finds one person by their LinkedIn profile, as a URL, `in/<slug>` or the bare slug. Send it alone, or with filters to check the person matches them:

```json theme={null}
{ "linkedinUrl": "linkedin.com/in/ana-ruiz-ops" }
```

## Keep the search

Save the filters under a title, then run them again whenever you need fresh results:

```bash theme={null}
curl https://api.outbound.dev/v1/saved-searches \
  -H "Authorization: Bearer $OUTBOUND_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"title": "Portugal freight ops", "filters": {"job_title_levels": ["director"], "job_title_role": ["operations"]}}'
```

```bash theme={null}
curl https://api.outbound.dev/v1/saved-searches/6a1f0c2b9d4e8a7f3c5b2e15/run \
  -H "Authorization: Bearer $OUTBOUND_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"limit": 25}'
```

A run is a people search: it pages and is charged the same way. Creating, changing and deleting a saved search need a key that can write.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.