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
}'
import os
import uuid
import requests
response = requests.post(
"https://api.avina.io/v1/people/search",
headers={"Authorization": f"Bearer {os.environ['AVINA_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json={
"query": "Heads of revenue operations at US fintech companies with 200 to 1,000 employees",
"limit": 25,
"enrich_emails": True
},
)
response.raise_for_status()
print(response.json())
const response = await fetch(`https://api.avina.io/v1/people/search`, {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.AVINA_API_KEY}`,
"Content-Type": "application/json",
"Idempotency-Key": crypto.randomUUID(),
},
body: JSON.stringify({
"query": "Heads of revenue operations at US fintech companies with 200 to 1,000 employees",
"limit": 25,
"enrich_emails": true
}),
});
const data = await response.json();
console.log(data);
{
"object": "people_search",
"id": "7c1d9a52-3e0b-4f6a-9d21-5b8e4a7c0f13",
"status": "queued",
"stop_reason": null,
"error": null,
"query": "Heads of revenue operations at US fintech companies with 200 to 1,000 employees",
"limit": 25,
"interpretation": null,
"assumptions": [],
"progress": {
"candidates": 0,
"accepted": 0,
"rejected": 0,
"unknown": 0,
"not_returned": 0,
"contacts_found": 0
},
"credits_charged": 0,
"cancel_requested": false,
"created_at": "2026-11-12T17:10:02Z",
"completed_at": null,
"expires_at": null,
"status_url": "https://api.avina.io/v1/people/search/7c1d9a52-3e0b-4f6a-9d21-5b8e4a7c0f13/status",
"results_url": "https://api.avina.io/v1/people/search/7c1d9a52-3e0b-4f6a-9d21-5b8e4a7c0f13/results"
}
{
"error": {
"code": "invalid_request",
"message": "filters.all.0: unknown field 'company.size'",
"request_id": "req_8f2a61c09d4e7b3a5f10c2d8",
"details": [
{
"field": "filters.all.0",
"message": "unknown field 'company.size'; supported fields are listed in the filter reference"
}
]
}
}
Start a people search
Starts a search for people that match a natural-language query, or structured filters and criteria.
POST
/
v1
/
people
/
search
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
}'
import os
import uuid
import requests
response = requests.post(
"https://api.avina.io/v1/people/search",
headers={"Authorization": f"Bearer {os.environ['AVINA_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json={
"query": "Heads of revenue operations at US fintech companies with 200 to 1,000 employees",
"limit": 25,
"enrich_emails": True
},
)
response.raise_for_status()
print(response.json())
const response = await fetch(`https://api.avina.io/v1/people/search`, {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.AVINA_API_KEY}`,
"Content-Type": "application/json",
"Idempotency-Key": crypto.randomUUID(),
},
body: JSON.stringify({
"query": "Heads of revenue operations at US fintech companies with 200 to 1,000 employees",
"limit": 25,
"enrich_emails": true
}),
});
const data = await response.json();
console.log(data);
{
"object": "people_search",
"id": "7c1d9a52-3e0b-4f6a-9d21-5b8e4a7c0f13",
"status": "queued",
"stop_reason": null,
"error": null,
"query": "Heads of revenue operations at US fintech companies with 200 to 1,000 employees",
"limit": 25,
"interpretation": null,
"assumptions": [],
"progress": {
"candidates": 0,
"accepted": 0,
"rejected": 0,
"unknown": 0,
"not_returned": 0,
"contacts_found": 0
},
"credits_charged": 0,
"cancel_requested": false,
"created_at": "2026-11-12T17:10:02Z",
"completed_at": null,
"expires_at": null,
"status_url": "https://api.avina.io/v1/people/search/7c1d9a52-3e0b-4f6a-9d21-5b8e4a7c0f13/status",
"results_url": "https://api.avina.io/v1/people/search/7c1d9a52-3e0b-4f6a-9d21-5b8e4a7c0f13/results"
}
{
"error": {
"code": "invalid_request",
"message": "filters.all.0: unknown field 'company.size'",
"request_id": "req_8f2a61c09d4e7b3a5f10c2d8",
"details": [
{
"field": "filters.all.0",
"message": "unknown field 'company.size'; supported fields are listed in the filter reference"
}
]
}
}
Returns
Every error uses the same shape. See Errors.
202 immediately with the search’s id; the search runs in the background.
Send either query, or filters and/or criteria. Conditions on person.* fields describe the person; conditions on company.* fields describe their current employer. Only people who match every requirement are returned.
A search returns names, titles and LinkedIn profiles. Email addresses and phone numbers are looked up only when you set enrich_emails or enrich_phones, and cost extra.
Poll GET /people/search/{search_id}/status and read people from GET /people/search/{search_id}/results as they are found.
Starting a search spends credits as people are found. Reading status and results is free. Set
max_credits to cap what one search can spend. See Pricing.Example bodies
{
"query": "Heads of revenue operations at US fintech companies with 200 to 1,000 employees",
"limit": 25,
"enrich_emails": true
}
{
"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,
"enrich_emails": true,
"max_credits": 20
}
Headers
string
A unique string for this request, 1 to 255 characters. Retrying with the same key and body returns the original response instead of starting new work. Reusing a key with a different body returns
409 idempotency_key_reused. Always send one when starting a search.Body
string
Who to find, in plain language. Required unless you send
filters or criteria. Cannot be combined with them.Maximum 1,000 characters.object | null
Structured conditions. A record must meet every condition in
all. null is treated the same as leaving filters out. See the filter reference for every field and operator.Show properties
Show properties
object[]
required
The conditions. A record must meet every one. Each item is a field condition (
field, operator, value) or a related condition.Show item properties
Show item properties
string
The field to test, such as
company.industry or person.title.string
How to compare. Which operators a field accepts depends on its type.Options:
in, matches, eq, gt, gte, lt, lte, between, within_last_days.any
The value to compare against. A list for
in, a two-item list for between, a {amount, currency} object for money fields, a number of days for within_last_days.object
A condition on records related to the company. All conditions in
where must be true of the same record, for example one job listing.Show properties
Show properties
string
required
open_jobs: the company has at least one open job that matches. new_hires: someone with a matching title joined the company within the window.object
required
Conditions on the related record.
Show properties
Show properties
object[]
required
Conditions on
title (in), posted_at (within_last_days, for open_jobs) or started_at (within_last_days, for new_hires).(string | object)[] | null
Free-text requirements, each checked against evidence for every candidate. Use them for anything the structured fields cannot express. Each item is a string, or an object with
text and kind.At most 10 items.Show item properties
Show item properties
string
required
The requirement, written as a statement that is true of a match.
string
default:"event"
attribute: a lasting fact the company’s own description could state, such as “sells to hospitals”. event: something that happened, such as “opened a location in Texas this year”; checked by web research.integer
default:"20"
The most people to return. The search stops when it has found this many.Range: 1 to 500.
boolean
default:"false"
Look up a work email address for each person found. Charged per person looked up. An email is not guaranteed.
boolean
default:"false"
Look up a phone number for each person found. Charged per person looked up, at a higher rate than email. A phone number is not guaranteed.
string[]
LinkedIn profile URLs to skip, for example people you already have.
number
The most credits this search may spend. 1 credit = $1.00. When the search reaches it, it stops with
stop_reason usage_limit_reached and keeps the results found so far. Defaults to your remaining balance.Response
202 The search was accepted and queued.
string
required
company_search or people_search.string
required
The search’s identifier. Use it to read status and results.
string
required
queued and running are in progress. completed, failed and cancelled are terminal. completed means this run finished, not that every matching record in the world was found.string | null
required
Why a finished search stopped.
null while it is in progress. Can also be null on a failed search; read error.Options: target_reached, sources_exhausted, usage_limit_reached, retrieval_limit_reached, query_needs_clarification, provider_failed, cancelled.string | null
required
A message when
status is failed. Results found before the failure stay readable.string | null
required
The natural-language request, when the search was started with
query.integer
required
The most results this search will return.
object | null
required
How a
query was read. null until the query has been interpreted, and for searches started with filters or criteria.Show properties
Show properties
object
Structured conditions. A record must meet every condition in
all. null is treated the same as leaving filters out. See the filter reference for every field and operator.Show properties
Show properties
object[]
required
The conditions. A record must meet every one. Each item is a field condition (
field, operator, value) or a related condition.Show item properties
Show item properties
string
The field to test, such as
company.industry or person.title.string
How to compare. Which operators a field accepts depends on its type.Options:
in, matches, eq, gt, gte, lt, lte, between, within_last_days.any
The value to compare against. A list for
in, a two-item list for between, a {amount, currency} object for money fields, a number of days for within_last_days.object
A condition on records related to the company. All conditions in
where must be true of the same record, for example one job listing.Show properties
Show properties
string
required
open_jobs: the company has at least one open job that matches. new_hires: someone with a matching title joined the company within the window.object
required
Conditions on the related record.
Show properties
Show properties
object[]
required
Conditions on
title (in), posted_at (within_last_days, for open_jobs) or started_at (within_last_days, for new_hires).object[]
Free-text requirements read from the query.
Show item properties
Show item properties
string[]
Requirements no public source can confirm, quoted from the query. A search cannot run while there are any.
object[]
required
object
required
Counts so far. They only increase.
Show properties
Show properties
integer
required
Candidates checked so far.
integer
required
Candidates that matched every requirement and were added to the results.
integer
required
Candidates that failed at least one requirement.
integer
required
Candidates whose evidence could not confirm every requirement. They are not returned.
integer
required
Candidates that matched every requirement but were not returned because
limit or a spend limit had already been reached.integer
required
Contacts found so far. For company searches with
persona_ids, and people searches with enrichment.number
required
Credits charged for this search so far. 1 credit = $1.00.
boolean
required
true after a cancel request, until the search reaches cancelled.string
required
When the search was started.
string | null
required
When the search reached a terminal status.
string | null
required
When the search and its results stop being readable.
null when no expiry is set.string
required
The URL of this search’s status.
string
required
The URL of this search’s results.
Errors
| Status | Code | When |
|---|---|---|
400 | invalid_request | The request is invalid. details names each problem. |
401 | invalid_api_key | The API key is missing, invalid or revoked. |
402 | usage_limit_reached | The workspace has no credits left. Nothing was started or charged. |
409 | idempotency_key_reused | The Idempotency-Key was already used with a different request, or its first request is still running. |
429 | rate_limited | Too many requests. Retry after Retry-After seconds. |
500 | internal_error | Something went wrong on our side. Retry with backoff, and with the same Idempotency-Key if you sent one. |
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
}'
import os
import uuid
import requests
response = requests.post(
"https://api.avina.io/v1/people/search",
headers={"Authorization": f"Bearer {os.environ['AVINA_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json={
"query": "Heads of revenue operations at US fintech companies with 200 to 1,000 employees",
"limit": 25,
"enrich_emails": True
},
)
response.raise_for_status()
print(response.json())
const response = await fetch(`https://api.avina.io/v1/people/search`, {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.AVINA_API_KEY}`,
"Content-Type": "application/json",
"Idempotency-Key": crypto.randomUUID(),
},
body: JSON.stringify({
"query": "Heads of revenue operations at US fintech companies with 200 to 1,000 employees",
"limit": 25,
"enrich_emails": true
}),
});
const data = await response.json();
console.log(data);
{
"object": "people_search",
"id": "7c1d9a52-3e0b-4f6a-9d21-5b8e4a7c0f13",
"status": "queued",
"stop_reason": null,
"error": null,
"query": "Heads of revenue operations at US fintech companies with 200 to 1,000 employees",
"limit": 25,
"interpretation": null,
"assumptions": [],
"progress": {
"candidates": 0,
"accepted": 0,
"rejected": 0,
"unknown": 0,
"not_returned": 0,
"contacts_found": 0
},
"credits_charged": 0,
"cancel_requested": false,
"created_at": "2026-11-12T17:10:02Z",
"completed_at": null,
"expires_at": null,
"status_url": "https://api.avina.io/v1/people/search/7c1d9a52-3e0b-4f6a-9d21-5b8e4a7c0f13/status",
"results_url": "https://api.avina.io/v1/people/search/7c1d9a52-3e0b-4f6a-9d21-5b8e4a7c0f13/results"
}
{
"error": {
"code": "invalid_request",
"message": "filters.all.0: unknown field 'company.size'",
"request_id": "req_8f2a61c09d4e7b3a5f10c2d8",
"details": [
{
"field": "filters.all.0",
"message": "unknown field 'company.size'; supported fields are listed in the filter reference"
}
]
}
}