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

# People

> Find people by role, seniority and employer, and get verified work emails when you need them.

People search finds individual people. Describe the role you are looking for and the kind of company they work at. Each result is one person, with their current job title, employer and LinkedIn profile.

```bash Request theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl -X POST https://api.avina.io/v1/people/search \
  -H "Authorization: Bearer $AVINA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "query": "Heads of revenue operations at US fintech companies with 200 to 1,000 employees",
    "limit": 25,
    "enrich_emails": true,
    "max_credits": 20
  }'
```

```json One result (matched_criteria shortened) theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "object": "person_search_result",
  "result_id": "res_4Hn7Xc2pL9",
  "name": "Jordan Avery",
  "title": "Head of Revenue Operations",
  "seniority": "head",
  "department": "operations",
  "linkedin_url": "https://www.linkedin.com/in/jordan-avery-example",
  "location": { "country": "US", "state": "New York", "city": "New York" },
  "email": "jordan.avery@northwindpay.example",
  "email_status": "valid",
  "phone": null,
  "company": {
    "name": "Northwind Pay",
    "domain": "northwindpay.example",
    "industries": ["Financial Services"],
    "employee_count": { "low": 201, "high": 500 }
  },
  "matched_criteria": [
    { "criterion": "person.title", "verdict": "matched",
      "evidence": { "summary": "Current title: Head of Revenue Operations",
        "sources": ["https://www.linkedin.com/in/jordan-avery-example"], "items": [] } }
  ],
  "found_at": "2026-11-12T17:11:05Z"
}
```

## Two kinds of condition

A people search combines conditions about the person with conditions about their employer.

> [card] About the person
>
> `person.title`, `person.seniority`, `person.department`, and where the person is located.

> [card] About their employer
>
> Every `company.*` field from company search: industry, size, funding, location, technologies and more.

Both kinds apply to the person's **current** job. Someone who used to work at a fintech and now has a sales title elsewhere is not a "sales leader at a fintech".

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "filters": {
    "all": [
      { "field": "person.title", "operator": "in", "value": ["VP Sales", "Head of Sales", "Chief Revenue Officer"] },
      { "field": "person.location.country", "operator": "in", "value": ["US"] },
      { "field": "company.industry", "operator": "in", "value": ["Software Development"] },
      { "field": "company.employee_count", "operator": "between", "value": [50, 500] }
    ]
  },
  "limit": 25
}
```

The person fields are listed in the [filter reference](https://docs.data.avina.io/guides/structured-filters.md#person-fields).

## Contact details are opt-in

A people search finds who the people are. It looks up email addresses and phone numbers only when you ask, because each lookup is charged.

| Field | Default | When set |
| - | - | - |
| `enrich_emails` | `false` | Looks up a work email for each person found, and checks whether it is deliverable. |
| `enrich_phones` | `false` | Looks up a phone number for each person found. Costs more than email. |

Lookups are charged per person looked up. A lookup that finds nothing still returns the person, with `email` or `phone` set to `null`. Nothing is invented.

### Email verification

When an email is returned, `email_status` tells you how far to trust it:

| `email_status` | Meaning |
| - | - |
| `valid` | The mailbox exists and accepts mail. |
| `catch_all` | The company's mail server accepts mail for any address at its domain, so this particular mailbox cannot be confirmed. |
| `unknown` | Verification was inconclusive. |

> [!TIP]
>
> Search without enrichment first to check you are getting the right people, then run it again with `enrich_emails` once the list looks right.

## People search or personas?

Both return people. They start from different places.

| | People search | Company search with `persona_ids` |
| - | - | - |
| You start from | A role: "heads of RevOps at fintechs" | A company profile: "Series B fintechs hiring" |
| Returns | People, each with their company | Companies, each with a few contacts |
| How many per company | As many as match, up to `limit` overall | `contacts_per_company` per persona |
| Best for | Building a contact list for one role | Building a company list with the relevant people attached to each company |

## The workflow

People search uses the same asynchronous flow as company search.

**1. Start**

`POST /people/search` returns a search `id`.

**2. Watch**

`GET /people/search/{search_id}/status` shows progress and spend.

**3. Read**

`GET /people/search/{search_id}/results` returns people as they are found.

**4. Stop early (optional)**

`POST /people/search/{search_id}/cancel`.

## Good to know

* **One result per person.** People are deduplicated across providers.
* **Location is the person's.** `person.location` is where the person is. `company.headquarters` is where the company is. A US company can employ someone in Berlin.
* **Skip people you have.** Pass LinkedIn URLs in `exclude_linkedin_urls`.
* **Use the data responsibly.** You are responsible for contacting people in line with the laws that apply to you, such as GDPR, CAN-SPAM and CASL.

## Next steps

> [card] [Start a people search](https://docs.data.avina.io/api-reference/people/search.md)
>
> Endpoint reference with every field.

> [card] [Contacts with personas](https://docs.data.avina.io/guides/contacts-with-personas.md)
>
> Get contacts attached to company results instead.


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