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

# Create a persona

> Creates a persona.

Creating a persona does not search for contacts or spend credits. A workspace can have up to 10 personas; creating an eleventh returns `400 invalid_request`.

### Headers

**Idempotency-Key** `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

**name** `string`

A label for the persona.

Maximum 191 characters.

**job\_titles** `string[]` *required*

The job titles to look for at each company.

**contacts\_per\_company** `integer` (default: 1)

How many contacts to find per company for this persona.

Range: 1 to 100.

**enrich\_emails** `boolean` (default: true)

Look up an email address for each contact.

**enrich\_phones** `boolean` (default: false)

Look up a phone number for each contact. Costs more than email.

**contact\_countries** `string[]`

Where the contacts are located, as ISO 3166-1 alpha-2 codes. Omit for worldwide.

### Response

**`201`** The persona was created.

**object** `string` *required*

Always `persona`.

**id** `string` *required*

The persona's identifier. Use it in `persona_ids`.

**name** `string | null`

A label for the persona.

**job\_titles** `string[]` *required*

The job titles to look for at each company.

**contacts\_per\_company** `integer` *required*

How many contacts to find per company for this persona.

**enrich\_emails** `boolean` *required*

Whether to look up email addresses.

**enrich\_phones** `boolean` *required*

Whether to look up phone numbers.

**contact\_countries** `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.

**created\_at** `string` *required*

When the persona was created.

**updated\_at** `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. |

Every error uses the same shape. See [Errors](https://docs.data.avina.io/api-reference/errors.md).

```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: $(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"]
  }'
```

```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
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())
```

```javascript JavaScript theme={"theme":{"light":"github-light","dark":"github-dark"}}
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);
```

```json 201 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"
}
```

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


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