People

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.

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

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

About the person

person.title, person.seniority, person.department, and where the person is located.

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

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

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.

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.

Start

POST /people/search returns a search id.

Watch

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

Read

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

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.

Get started

Concepts

Capabilities

Guides

Two kinds of condition

About the person

About their employer

Contact details are opt-in

Email verification

People search or personas?

The workflow

Good to know

Next steps

Start a people search

Contacts with personas

​Two kinds of condition

About the person

About their employer

​Contact details are opt-in

​Email verification

​People search or personas?

​The workflow

​Good to know

​Next steps

Start a people search

Contacts with personas

Two kinds of condition

Contact details are opt-in

Email verification

People search or personas?

The workflow

Good to know

Next steps