Find contacts with personas

A persona is a saved description of who you want to reach at a company: which job titles, how many people, and whether to look up their email and phone. Pass personas to a company search and every matching company comes back with those people attached.

You need

An API key. See the quickstart.
Credits. Creating personas is free. A search with personas is charged for the company search and for each contact lookup. Set max_credits to cap it.

1. Create a persona

cURL

curl -X POST https://api.avina.io/v1/personas \
  -H "Authorization: Bearer $AVINA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: persona-sales-leaders" \
  -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"]
  }'

Response

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

Keep the id. Personas are shared with the Avina dashboard: the ones you create here appear under Settings → Personas, and the ones created there are returned by GET /personas.

Persona settings

Field	Default	What it controls
`job_titles`	(required)	The titles to look for.
`contacts_per_company`	1	How many people to find per company for this persona, 1 to 100.
`enrich_emails`	`true`	Look up and verify a work email for each contact.
`enrich_phones`	`false`	Look up a phone number for each contact. Costs more than email.
`contact_countries`	worldwide	Where the person is located, as ISO country codes. Not the company’s headquarters.

A workspace can have up to 10 personas.

2. Search with the persona

Add the persona’s id to persona_ids. You can send up to 10.

cURL

curl -X POST https://api.avina.io/v1/companies/search \
  -H "Authorization: Bearer $AVINA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "query": "Series B fintech companies in New York",
    "limit": 10,
    "persona_ids": ["c92d77d7-cc85-4a62-bcec-518b1d7d6260"],
    "max_credits": 25
  }'

Poll and read results as usual. See Poll and paginate.

3. Read the contacts

Each company result now has contacts and a contact_status:

One result (shortened)

{
  "object": "company_search_result",
  "name": "Northwind Pay",
  "domain": "northwindpay.example",
  "contacts": [
    {
      "name": "Riley Chen",
      "title": "VP Sales",
      "linkedin_url": "https://www.linkedin.com/in/riley-chen-example",
      "email": "riley.chen@northwindpay.example",
      "email_status": "valid",
      "phone": null,
      "persona_ids": ["c92d77d7-cc85-4a62-bcec-518b1d7d6260"]
    },
    {
      "name": "Sam Okafor",
      "title": "Chief Revenue Officer",
      "linkedin_url": "https://www.linkedin.com/in/sam-okafor-example",
      "email": null,
      "email_status": null,
      "phone": null,
      "persona_ids": ["c92d77d7-cc85-4a62-bcec-518b1d7d6260"]
    }
  ],
  "contact_status": "complete"
}

`contact_status`

Value	Meaning
`not_requested`	The search had no `persona_ids`.
`complete`	Every lookup finished. This includes lookups that found nobody: `contacts` can be empty and still be complete.
`partial`	Some lookups finished and others failed or were stopped, for example by cancellation or a spend limit. The contacts that were found are returned.
`failed`	No lookup could finish. The company is still returned.

A missing email is not a failure. In the example above, Sam Okafor was found but no email was, so email is null and the status is still complete. Fields are never guessed.

How personas behave

Personas choose people, not companies. Adding a persona never changes which companies match. A company with no one in the persona’s titles is still returned, with an empty contacts list.
No personas, no contact charges. Omit persona_ids and no contact lookup happens. Personas are never applied by default.
One person, once. If someone matches two personas, they appear once with both IDs in persona_ids.
Settings are fixed when the search starts. A search uses each persona as it was when the search started. Editing or deleting a persona does not affect a running search.
A company appears in results only when its contact lookups have finished. You never have to come back later for its people.

Tips for good contacts

List the titles people actually use

Include common variants of the same role: ["VP Sales", "Vice President of Sales", "Head of Sales"].

One persona per role involved in the purchase

Create one persona for the person who approves the budget, one for the person who would use your product day to day, and one for the technical reviewer. Send all three in persona_ids, each with its own contacts_per_company.

Look up phone numbers only for the people you call

Phone lookups cost more than email lookups. Turn enrich_phones on only for personas your team contacts by phone.

Verify before you send

Send to addresses with email_status: "valid". Be careful with catch_all and unknown: those addresses could not be confirmed, so they are more likely to bounce.

Troubleshooting

Symptom	Likely cause	Fix
`400 invalid_request` naming `persona_ids`	An ID is not a persona in this workspace, or more than 10 were sent	List personas with `GET /personas` and use those IDs
`403 permission_denied` with reason `contact_search_disabled`	Contact search is turned off for the workspace	Contact support@avina.io
`contacts` is empty and status is `complete`	Nobody at the company matched the persona’s titles or countries	Broaden `job_titles`, or remove `contact_countries`
Contacts have no `email`	The persona has `enrich_emails: false`, or no address was found	Check the persona’s settings
`contact_status` is `partial`	The search was cancelled or reached `max_credits` during lookups	Raise `max_credits` and search again

People search: start from a role instead of a company profile
Personas API reference

Get started

Concepts

Capabilities

Guides

Find contacts with personas

1. Create a persona

Persona settings

2. Search with the persona

3. Read the contacts

`contact_status`

How personas behave

Tips for good contacts

Troubleshooting

​1. Create a persona

​Persona settings

​2. Search with the persona

​3. Read the contacts

​contact_status

​How personas behave

​Tips for good contacts

​Troubleshooting

​Related

1. Create a persona

Persona settings

2. Search with the persona

3. Read the contacts

`contact_status`

How personas behave

Tips for good contacts

Troubleshooting

Related