> ## Documentation Index
> Fetch the complete documentation index at: https://docs.data.avina.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Find contacts with personas

> Attach the right people, with emails and phone numbers, to every company a search finds.

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.

> [!NOTE]
>
> **You need**
>
> * An API key. See the [quickstart](https://docs.data.avina.io/quickstart.md).
> * 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

```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
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"]
  }'
```

```json Response theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "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`](https://docs.data.avina.io/api-reference/personas/list).

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

```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
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](https://docs.data.avina.io/guides/poll-and-paginate.md).

## 3. Read the contacts

Each company result now has `contacts` and a `contact_status`:

```json One result (shortened) theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "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

> [accordion] List the titles people actually use
>
> Include common variants of the same role: `["VP Sales", "Vice President of Sales", "Head of Sales"]`.

> [accordion] 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`.

> [accordion] 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.

> [accordion] 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](mailto: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 |

## Related

* [People search](https://docs.data.avina.io/capabilities/people.md): start from a role instead of a company profile
* [Personas API reference](https://docs.data.avina.io/api-reference/personas/list.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.