curl -X POST https://api.avina.io/v1/personas \
-H "Authorization: Bearer $AVINA_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{
"name": "Sales leaders",
"job_titles": ["VP Sales", "CRO", "Head of Sales"],
"contacts_per_company": 2,
"enrich_emails": true,
"enrich_phones": false,
"contact_countries": ["US", "CA"]
}'
import os
import uuid
import requests
response = requests.post(
"https://api.avina.io/v1/personas",
headers={"Authorization": f"Bearer {os.environ['AVINA_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json={
"name": "Sales leaders",
"job_titles": ["VP Sales", "CRO", "Head of Sales"],
"contacts_per_company": 2,
"enrich_emails": True,
"enrich_phones": False,
"contact_countries": ["US", "CA"]
},
)
response.raise_for_status()
print(response.json())
const response = await fetch(`https://api.avina.io/v1/personas`, {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.AVINA_API_KEY}`,
"Content-Type": "application/json",
"Idempotency-Key": crypto.randomUUID(),
},
body: JSON.stringify({
"name": "Sales leaders",
"job_titles": ["VP Sales", "CRO", "Head of Sales"],
"contacts_per_company": 2,
"enrich_emails": true,
"enrich_phones": false,
"contact_countries": ["US", "CA"]
}),
});
const data = await response.json();
console.log(data);
{
"object": "persona",
"id": "c92d77d7-cc85-4a62-bcec-518b1d7d6260",
"name": "Sales leaders",
"job_titles": ["VP Sales", "CRO", "Head of Sales"],
"contacts_per_company": 2,
"enrich_emails": true,
"enrich_phones": false,
"contact_countries": ["US", "CA"],
"created_at": "2026-10-05T17:02:11Z",
"updated_at": "2026-10-05T17:02:11Z"
}
{
"error": {
"code": "invalid_request",
"message": "job_titles: must contain at least one title",
"request_id": "req_8f2a61c09d4e7b3a5f10c2d8",
"details": [
{
"field": "job_titles",
"message": "must contain at least one title"
}
]
}
}
Create a persona
Creates a persona.
POST
/
v1
/
personas
curl -X POST https://api.avina.io/v1/personas \
-H "Authorization: Bearer $AVINA_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{
"name": "Sales leaders",
"job_titles": ["VP Sales", "CRO", "Head of Sales"],
"contacts_per_company": 2,
"enrich_emails": true,
"enrich_phones": false,
"contact_countries": ["US", "CA"]
}'
import os
import uuid
import requests
response = requests.post(
"https://api.avina.io/v1/personas",
headers={"Authorization": f"Bearer {os.environ['AVINA_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json={
"name": "Sales leaders",
"job_titles": ["VP Sales", "CRO", "Head of Sales"],
"contacts_per_company": 2,
"enrich_emails": True,
"enrich_phones": False,
"contact_countries": ["US", "CA"]
},
)
response.raise_for_status()
print(response.json())
const response = await fetch(`https://api.avina.io/v1/personas`, {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.AVINA_API_KEY}`,
"Content-Type": "application/json",
"Idempotency-Key": crypto.randomUUID(),
},
body: JSON.stringify({
"name": "Sales leaders",
"job_titles": ["VP Sales", "CRO", "Head of Sales"],
"contacts_per_company": 2,
"enrich_emails": true,
"enrich_phones": false,
"contact_countries": ["US", "CA"]
}),
});
const data = await response.json();
console.log(data);
{
"object": "persona",
"id": "c92d77d7-cc85-4a62-bcec-518b1d7d6260",
"name": "Sales leaders",
"job_titles": ["VP Sales", "CRO", "Head of Sales"],
"contacts_per_company": 2,
"enrich_emails": true,
"enrich_phones": false,
"contact_countries": ["US", "CA"],
"created_at": "2026-10-05T17:02:11Z",
"updated_at": "2026-10-05T17:02:11Z"
}
{
"error": {
"code": "invalid_request",
"message": "job_titles: must contain at least one title",
"request_id": "req_8f2a61c09d4e7b3a5f10c2d8",
"details": [
{
"field": "job_titles",
"message": "must contain at least one title"
}
]
}
}
Creating a persona does not search for contacts or spend credits. A workspace can have up to 10 personas; creating an eleventh returns
Every error uses the same shape. See Errors.
400 invalid_request.
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
A label for the persona.Maximum 191 characters.
string[]
required
The job titles to look for at each company.
integer
default:"1"
How many contacts to find per company for this persona.Range: 1 to 100.
boolean
default:"true"
Look up an email address for each contact.
boolean
default:"false"
Look up a phone number for each contact. Costs more than email.
string[]
Where the contacts are located, as ISO 3166-1 alpha-2 codes. Omit for worldwide.
Response
201 The persona was created.
string
required
Always
persona.string
required
The persona’s identifier. Use it in
persona_ids.string | null
A label for the persona.
string[]
required
The job titles to look for at each company.
integer
required
How many contacts to find per company for this persona.
boolean
required
Whether to look up email addresses.
boolean
required
Whether to look up phone numbers.
string[] | null
Where the contacts are located, as ISO 3166-1 alpha-2 codes. This is the person’s location, not the company’s headquarters.
null or empty means worldwide.string
required
When the persona was created.
string
required
When the persona was last changed.
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. |
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/personas \
-H "Authorization: Bearer $AVINA_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{
"name": "Sales leaders",
"job_titles": ["VP Sales", "CRO", "Head of Sales"],
"contacts_per_company": 2,
"enrich_emails": true,
"enrich_phones": false,
"contact_countries": ["US", "CA"]
}'
import os
import uuid
import requests
response = requests.post(
"https://api.avina.io/v1/personas",
headers={"Authorization": f"Bearer {os.environ['AVINA_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json={
"name": "Sales leaders",
"job_titles": ["VP Sales", "CRO", "Head of Sales"],
"contacts_per_company": 2,
"enrich_emails": True,
"enrich_phones": False,
"contact_countries": ["US", "CA"]
},
)
response.raise_for_status()
print(response.json())
const response = await fetch(`https://api.avina.io/v1/personas`, {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.AVINA_API_KEY}`,
"Content-Type": "application/json",
"Idempotency-Key": crypto.randomUUID(),
},
body: JSON.stringify({
"name": "Sales leaders",
"job_titles": ["VP Sales", "CRO", "Head of Sales"],
"contacts_per_company": 2,
"enrich_emails": true,
"enrich_phones": false,
"contact_countries": ["US", "CA"]
}),
});
const data = await response.json();
console.log(data);
{
"object": "persona",
"id": "c92d77d7-cc85-4a62-bcec-518b1d7d6260",
"name": "Sales leaders",
"job_titles": ["VP Sales", "CRO", "Head of Sales"],
"contacts_per_company": 2,
"enrich_emails": true,
"enrich_phones": false,
"contact_countries": ["US", "CA"],
"created_at": "2026-10-05T17:02:11Z",
"updated_at": "2026-10-05T17:02:11Z"
}
{
"error": {
"code": "invalid_request",
"message": "job_titles: must contain at least one title",
"request_id": "req_8f2a61c09d4e7b3a5f10c2d8",
"details": [
{
"field": "job_titles",
"message": "must contain at least one title"
}
]
}
}