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

# Список профілів

> Отримати список профілів пацієнтів або знайти їх за електронною поштою

Отримай список профілів пацієнтів, доступних твоєму API-ключу, або знайди один із них за точною електронною адресою.

Якщо передано `email`, ендпоїнт виконує кешований у Redis пошук за точним збігом із
канонічною електронною адресою для входу та повертає 0 або 1 результат; у такому разі `limit` і `offset`
ігноруються. Якщо параметр не передано, ендпоїнт повертає список профілів із пагінацією в межах контексту доступу твого
API-ключа.

Пошук за електронною адресою є точним і нечутливим до регістру — пошук за підрядком і префіксом не підтримується.
Перевіряється лише канонічна електронна адреса для входу; альтернативні адреси, як-от `work_email`, не
враховуються.

Потребує дозволу `profiles_view` або `impersonate`.

## Запит

### Параметри запиту

**email** `string`

Фільтр за точною електронною адресою (без урахування регістру). Якщо задано, повертає 0 або 1 результат, а
`limit`/`offset` ігноруються. Пошук обслуговується зворотним індексом із кешуванням у Redis та
індексованим резервним запитом SQL.

**limit** `integer` (default: 100)

Максимальна кількість профілів у відповіді. За замовчуванням 100, максимум 500. Ігнорується, якщо задано `email`.

**offset** `integer` (default: 0)

Кількість профілів, які потрібно пропустити для пагінації. За замовчуванням 0. Ігнорується, якщо задано `email`.

## Відповідь

У разі успіху API повертає `200 OK` із масивом об’єктів профілів. Структура кожного
елемента відповідає [Отримати профіль](https://docs.anivahealth.com/uk/api/profiles/get-profile.md).

**id** `string` *required*

Унікальний ідентифікатор профілю (UUID).

**handle** `string`

Псевдонім або ім’я користувача профілю. Може бути `null`.

**first\_name** `string`

Ім’я. Може бути `null`.

**last\_name** `string`

Прізвище. Може бути `null`.

**email** `string`

Електронна адреса. Може бути `null`.

**phone** `string`

Номер телефону у форматі E.164. Може бути `null`.

**sex** `integer`

Біологічна стать за ISO/IEC 5218 (`0` = невідома, `1` = чоловіча, `2` = жіноча). Може бути `null`.

**date\_of\_birth** `string`

Дата народження у форматі `YYYY-MM-DD`. Може бути `null`.

**height** `number`

Зріст у сантиметрах. Може бути `null`.

**weight** `number`

Вага в кілограмах. Може бути `null`.

**language** `string`

Бажана мова: `en`, `bg`, `ca`, `cs`, `da`, `de`, `el`, `es`, `et`, `fi`, `fr`, `ga`, `hr`, `hu`, `is`, `it`, `lb`, `lt`, `lv`, `mt`, `nl`, `no`, `pl`, `pt`, `ro`, `ru`, `sk`, `sl`, `sr`, `sv`, `tr` або `uk`.

**transactional\_emails\_enabled** `boolean`

Чи отримує цей профіль транзакційні (програмні) листи. `null`, якщо значення ніколи не встановлювалося.

**created\_at** `string`

Часова мітка створення профілю у форматі ISO 8601.

**updated\_at** `string`

Часова мітка ISO 8601 останнього оновлення. Може бути `null`.

## Особливості роботи

* Порожній масив повертається і тоді, коли жоден профіль не відповідає електронній адресі, і тоді, коли збіг існує
  поза межами твого контексту доступу. Це зроблено навмисно — так ендпоїнт не розкриває
  існування профілів, які ти не можеш читати.
* Щойно створені профілі одразу можна знайти за `email`, оскільки процес створення
  синхронно прогріває кеш.
* Нефільтрований список відсортовано за `created_at` у порядку спадання (спочатку найновіші) з пагінацією через
  `limit` і `offset`.

## Повторні виклики

Aniva зберігає відповідь цього ендпойнта 5 хвилин для кожного API-ключа. Повторний виклик упродовж
цього часу отримує збережену відповідь. Заголовки `Cache-Status` і `Age` показують, що відповідь
збережена і як давно її збережено.

Щоб дізнаватися про зміни одразу, підпишись на події вебхуків `profile.created`, `profile.updated` та `profile.deleted`.
Див. [Повторні зчитування](https://docs.anivahealth.com/uk/concepts/webhooks.md#povtorni-chitannya).

## Відповіді з помилками

| Статус | Опис |
| - | - |
| `400` | Помилка валідації — некоректний формат електронної адреси або значення `limit`/`offset` поза допустимим діапазоном. |
| `403` | Доступ заборонено — твій API-ключ не має потрібного дозволу (`profiles_view`/`impersonate`). |
| `500` | Внутрішня помилка сервера. |

```bash cURL (lookup by email) theme={null}
curl --request GET \
  --url 'https://anivahealth.com/api/v1/profiles?email=maria.schmidt@example.com' \
  --header 'x-api-key: YOUR_API_KEY'
```

```bash cURL (paginated list) theme={null}
curl --request GET \
  --url 'https://anivahealth.com/api/v1/profiles?limit=50&offset=0' \
  --header 'x-api-key: YOUR_API_KEY'
```

```json 200 theme={null}
[
  {
    "id": "a3f1c2d4-8b7e-4f2a-9c1d-2e3f4a5b6c7d",
    "handle": null,
    "first_name": "Maria",
    "last_name": "Schmidt",
    "email": "maria.schmidt@example.com",
    "phone": "+4930123456789",
    "sex": 2,
    "date_of_birth": "1985-03-22",
    "height": 168,
    "weight": 65,
    "language": "de",
    "transactional_emails_enabled": true,
    "created_at": "2026-04-01T09:14:32Z",
    "updated_at": "2026-04-01T11:05:00Z"
  }
]
```

```json 200 (no match) theme={null}
[]
```

```json 400 theme={null}
{
  "error": "email: Invalid email format"
}
```


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