curl -X POST https://api.avina.io/v1/people/search/parse \
-H "Authorization: Bearer $AVINA_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{
"query": "VPs of sales at Series B software companies in the US"
}'
import os
import uuid
import requests
response = requests.post(
"https://api.avina.io/v1/people/search/parse",
headers={"Authorization": f"Bearer {os.environ['AVINA_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json={
"query": "VPs of sales at Series B software companies in the US"
},
)
response.raise_for_status()
print(response.json())
const response = await fetch(`https://api.avina.io/v1/people/search/parse`, {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.AVINA_API_KEY}`,
"Content-Type": "application/json",
"Idempotency-Key": crypto.randomUUID(),
},
body: JSON.stringify({
"query": "VPs of sales at Series B software companies in the US"
}),
});
const data = await response.json();
console.log(data);
{
"object": "people_search_parse",
"query": "VPs of sales at Series B software companies in the US",
"filters": {
"all": [
{
"field": "person.title",
"operator": "in",
"value": ["VP Sales", "Vice President of Sales"]
},
{
"field": "company.industry",
"operator": "in",
"value": ["Software Development"]
},
{
"field": "company.last_funding_round",
"operator": "in",
"value": ["series_b"]
},
{
"field": "company.headquarters.country",
"operator": "in",
"value": ["US"]
}
]
},
"criteria": [],
"unsupported_criteria": [],
"assumptions": [
{
"text": "in the US",
"assumed": "The company is headquartered in the US",
"alternatives": ["The person is located in the US"]
}
],
"errors": [],
"search_request": {
"filters": {
"all": [
{
"field": "person.title",
"operator": "in",
"value": ["VP Sales", "Vice President of Sales"]
},
{
"field": "company.industry",
"operator": "in",
"value": ["Software Development"]
},
{
"field": "company.last_funding_round",
"operator": "in",
"value": ["series_b"]
},
{
"field": "company.headquarters.country",
"operator": "in",
"value": ["US"]
}
]
},
"criteria": null
}
}
{
"error": {
"code": "invalid_request",
"message": "query: must be at most 1000 characters",
"request_id": "req_8f2a61c09d4e7b3a5f10c2d8",
"details": [
{ "field": "query", "message": "must be at most 1000 characters" }
]
}
}
Parse a people query
Turns a natural-language request into the structured filters and criteria a people search takes, without searching.
POST
/
v1
/
people
/
search
/
parse
curl -X POST https://api.avina.io/v1/people/search/parse \
-H "Authorization: Bearer $AVINA_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{
"query": "VPs of sales at Series B software companies in the US"
}'
import os
import uuid
import requests
response = requests.post(
"https://api.avina.io/v1/people/search/parse",
headers={"Authorization": f"Bearer {os.environ['AVINA_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json={
"query": "VPs of sales at Series B software companies in the US"
},
)
response.raise_for_status()
print(response.json())
const response = await fetch(`https://api.avina.io/v1/people/search/parse`, {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.AVINA_API_KEY}`,
"Content-Type": "application/json",
"Idempotency-Key": crypto.randomUUID(),
},
body: JSON.stringify({
"query": "VPs of sales at Series B software companies in the US"
}),
});
const data = await response.json();
console.log(data);
{
"object": "people_search_parse",
"query": "VPs of sales at Series B software companies in the US",
"filters": {
"all": [
{
"field": "person.title",
"operator": "in",
"value": ["VP Sales", "Vice President of Sales"]
},
{
"field": "company.industry",
"operator": "in",
"value": ["Software Development"]
},
{
"field": "company.last_funding_round",
"operator": "in",
"value": ["series_b"]
},
{
"field": "company.headquarters.country",
"operator": "in",
"value": ["US"]
}
]
},
"criteria": [],
"unsupported_criteria": [],
"assumptions": [
{
"text": "in the US",
"assumed": "The company is headquartered in the US",
"alternatives": ["The person is located in the US"]
}
],
"errors": [],
"search_request": {
"filters": {
"all": [
{
"field": "person.title",
"operator": "in",
"value": ["VP Sales", "Vice President of Sales"]
},
{
"field": "company.industry",
"operator": "in",
"value": ["Software Development"]
},
{
"field": "company.last_funding_round",
"operator": "in",
"value": ["series_b"]
},
{
"field": "company.headquarters.country",
"operator": "in",
"value": ["US"]
}
]
},
"criteria": null
}
}
{
"error": {
"code": "invalid_request",
"message": "query: must be at most 1000 characters",
"request_id": "req_8f2a61c09d4e7b3a5f10c2d8",
"details": [
{ "field": "query", "message": "must be at most 1000 characters" }
]
}
}
Free.
Use Parse to show users how their request was understood, let them edit it, or build a filter UI on top of natural language.
When nothing blocks the search,
Every error uses the same shape. See Errors.
search_request is a ready body for POST /people/search: send it as-is, or edit it first. Otherwise search_request is null, and unsupported_criteria or errors say what to change.
Parse runs no search and spends no credits.
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
required
The request to parse, from one sentence to a pasted paragraph of requirements.Maximum 1,000 characters.
Response
200 How the query was read.
string
required
company_search_parse or people_search_parse.string
required
The original text.
object | null
required
The structured reading of the query.
null when nothing in the query maps to a structured field.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[]
required
Requirements that will be checked against evidence for each candidate.
Show item properties
Show item properties
string[]
required
Requirements no public source can confirm, quoted from the query, such as visits to your own website or subjective quality. The search cannot run while there are any.
object[]
required
object[]
required
object | null
required
A ready request body for the matching search endpoint.
null when unsupported_criteria or errors is not empty, or the query gave nothing to search on.Show properties
Show properties
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).object[] | null
Show item properties
Show item properties
Errors
| Status | Code | When |
|---|---|---|
400 | invalid_request | The request is invalid, for example a missing query or one longer than 1,000 characters. |
401 | invalid_api_key | The API key is missing, invalid or revoked. |
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/parse \
-H "Authorization: Bearer $AVINA_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{
"query": "VPs of sales at Series B software companies in the US"
}'
import os
import uuid
import requests
response = requests.post(
"https://api.avina.io/v1/people/search/parse",
headers={"Authorization": f"Bearer {os.environ['AVINA_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json={
"query": "VPs of sales at Series B software companies in the US"
},
)
response.raise_for_status()
print(response.json())
const response = await fetch(`https://api.avina.io/v1/people/search/parse`, {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.AVINA_API_KEY}`,
"Content-Type": "application/json",
"Idempotency-Key": crypto.randomUUID(),
},
body: JSON.stringify({
"query": "VPs of sales at Series B software companies in the US"
}),
});
const data = await response.json();
console.log(data);
{
"object": "people_search_parse",
"query": "VPs of sales at Series B software companies in the US",
"filters": {
"all": [
{
"field": "person.title",
"operator": "in",
"value": ["VP Sales", "Vice President of Sales"]
},
{
"field": "company.industry",
"operator": "in",
"value": ["Software Development"]
},
{
"field": "company.last_funding_round",
"operator": "in",
"value": ["series_b"]
},
{
"field": "company.headquarters.country",
"operator": "in",
"value": ["US"]
}
]
},
"criteria": [],
"unsupported_criteria": [],
"assumptions": [
{
"text": "in the US",
"assumed": "The company is headquartered in the US",
"alternatives": ["The person is located in the US"]
}
],
"errors": [],
"search_request": {
"filters": {
"all": [
{
"field": "person.title",
"operator": "in",
"value": ["VP Sales", "Vice President of Sales"]
},
{
"field": "company.industry",
"operator": "in",
"value": ["Software Development"]
},
{
"field": "company.last_funding_round",
"operator": "in",
"value": ["series_b"]
},
{
"field": "company.headquarters.country",
"operator": "in",
"value": ["US"]
}
]
},
"criteria": null
}
}
{
"error": {
"code": "invalid_request",
"message": "query: must be at most 1000 characters",
"request_id": "req_8f2a61c09d4e7b3a5f10c2d8",
"details": [
{ "field": "query", "message": "must be at most 1000 characters" }
]
}
}