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

# Отримати лабораторні результати

> Отримати клінічні та генетичні лабораторні результати для замовлення набору для домашнього тесту

Отримай клінічні та генетичні лабораторні результати для замовлення набору для домашнього тесту разом із посиланнями на PDF-документи лабораторних звітів.

Кожен біомаркер, замовлений у наборі, з’являється у відповіді, тож ти можеш відстежувати все замовлення, а не лише те, що вже надійшло. Результати прив’язуються до `lab_code` замовлення — лабораторне замовлення оформлюється під час [активації](https://docs.anivahealth.com/uk/api/home-kit-orders/activate-home-kit.md), і лабораторія передає маркери окремо, щойно їх проаналізує, тому часткові дані є нормою, а верхньорівневий `status` залишається `in_progress` до фінального звіту. Перевіряй `status` кожного результату перед використанням його `value`:

* Тести, які ще очікуються, мають статус `planned`, поки замовлення перебуває в статусі `in_progress`. Ти можеш викликати цей ендпоїнт до активації — тоді кожен замовлений маркер матиме статус `planned`.
* Результати, які лабораторія надіслала, але які **не** можна використовувати клінічно, мають статус `fault` або `undeliverable` і містять поле `status_reason` із поясненням причини. Результат зі статусом `fault` усе одно має заповнене поле `value` — це значення хибне. Ніколи не показуй його як результат аналізу.
* Результати, у яких сумнівається Aniva або учасник, мають статус `likely_wrong` і поле `status_reason`. Значення не підтверджене. Не показуй його як результат аналізу без перевірки.

Використовуй [Завантажити документ](https://docs.anivahealth.com/uk/api/documents/download-document.md), щоб завантажити PDF-файли лабораторних звітів, посилання на які містяться в масиві `documents`.

Тобі не потрібно періодично опитувати цей ендпоїнт. Підпишись на [вебхуки](https://docs.anivahealth.com/uk/concepts/webhooks.md) `home_kit_order.results.updated` або `home_kit_order.results.completed` і викликай його, коли надійде подія. Періодичне опитування все одно працює як запасний варіант.

Потрібен дозвіл `results_view` — лабораторні результати й документи завжди захищені ним, так само як результати запису та [Завантажити документ](https://docs.anivahealth.com/uk/api/documents/download-document.md), — а також дозвіл `home_kit_orders_view` або `home_kit_orders_manage` для доступу до самого замовлення набору.

## Запит

### Параметри шляху

**id** `string` *required*

Унікальний ідентифікатор (UUID) замовлення набору для домашнього тесту, для якого потрібно отримати результати.

## Відповідь

У разі успіху API повертає `200 OK` з об’єктом результатів.

**status** `string` *required*

Загальний статус результатів. Одне зі значень:

* `in_progress` — частина направлень усе ще в лабораторії.
* `completed` — усі направлення закрито і щонайменше за одним надійшли результати.
* `fault` — усі направлення завершилися невдало без результатів. Більше нічого не очікується.

**submissions** `object[]` *required*

Один елемент на кожне лабораторне направлення — забір крові у кілька пробірок або для кількох лабораторій має
їх кілька. Верхньорівневий `status` стає `completed`, коли кожен елемент закрито і за одним із них надійшли результати.

**об’єкт направлення**

**lab\_code** `string`

Лабораторний код (штрихкод пробірки), під яким зареєстровано це направлення. Може бути `null`, якщо лабораторія
його не вказала.

**status** `string` *required*

`in_progress`, поки лабораторія ще працює над ним, `completed`, коли його звіт
остаточний, або `fault`, коли направлення відхилено чи скасовано і воно ніколи не надасть результатів —
зразок часто передають до іншої лабораторії, яка потім створює власний елемент.

**clinical\_results** `object[]` *required*

Масив клінічних результатів біомаркерів.

**об’єкт клінічного результату**

**id** `string`

Ідентифікатор рядка лабораторного результату (UUID). Він не змінюється, коли лабораторія виправляє цей рядок, тому використовуй його для upsert. `null` для результату `planned`.

**status** `string` *required*

Статус результату. Одне зі значень:

* `planned` — замовлено, лабораторія ще не надіслала результат. `value` має значення `null`.
* `received` — отримано від лабораторії.
* `corrected` — отримано, а потім виправлено людиною. `value` містить виправлене значення.
* `likely_wrong` — автоматична перевірка Aniva або учасник сумнівається у значенні. Не підтверджено: не показуй це як висновок без перевірки. Див. `status_reason`.
* `fault` — отримано, але підтверджено як хибне; **не використовуй у клінічній практиці**. `value` містить хибне число. Див. `status_reason`.
* `undeliverable` — лабораторія не змогла отримати значення. `value` має значення `null`. Див. `status_reason`.

**status\_reason** `string` *required*

Чому результат сумнівний або непридатний для використання. Заповнюється для `likely_wrong`, `fault` і `undeliverable`, `null` для всіх інших статусів.

Відрізняється від `comment`, який є власною приміткою лабораторії у звіті — у більшості хибних результатів `comment` порожній, тому вважай `status_reason` основним поясненням.

**lab\_code** `string`

Лабораторний код (штрихкод пробірки), за яким зареєстровано результат — один із лабораторних кодів замовлення. `null` для результату `planned` та для результатів, які лабораторія надіслала без коду.

**biomarker\_id** `integer` *required*

Ідентифікатор біомаркера.

**biomarker\_name** `string` *required*

Назва біомаркера для відображення.

**category** `string`

Категорія біомаркера (наприклад, гормони, вітаміни). Може бути `null`.

**value** `number`

Фактичне значення результату (виправлене, якщо є, інакше первинне). Може бути `null`.

**value\_operator** `string`

Оператор порівняння для значення: `eq` (дорівнює), `lt` (менше ніж) або `gt` (більше ніж). Може бути `null`.

**unit\_id** `integer`

Ідентифікатор одиниці вимірювання. Може бути `null`.

**unit** `string`

Назва одиниці вимірювання для відображення. Може бути `null`.

**reference\_range\_lab** `object`

Референтні діапазони, які лабораторія надала для **цього** результату, переведені в ті самі одиниці, що й `value`. `null`, якщо лабораторія не надала діапазону.

Межа, яку лабораторія залишила відкритою, залишається `null`, тому односторонній інтервал заповнює лише власну межу — верхній поріг надходить як `normal_min: null, normal_max: 50`, нижній як `normal_min: 55, normal_max: null`. Не сприймай межу `null` як нуль або необмеженість за замовчуванням; сприймай її як «лабораторія не встановила обмеження з цього боку».

Кожен результат містить діапазон, за яким його виміряли, тому пацієнт, чиї результати охоплюють кілька заборів крові або кілька лабораторій, отримує правильний інтервал для кожного результату, а не лише останній.

**референтний діапазон**

**normal\_min** `number`

Нижня межа нормального діапазону. Може бути `null`.

**normal\_max** `number`

Верхня межа нормального діапазону. Може бути `null`.

**optimal\_min** `number`

Нижня межа оптимального діапазону. Може бути `null`.

**optimal\_max** `number`

Верхня межа оптимального діапазону. Може бути `null`.

**reference\_range\_lab\_absent\_reason** `string`

Чому `reference_range_lab` має значення `null`. `null`, коли `reference_range_lab` присутній, а також для результату `planned`.

* `not_provided`: діапазону немає. Лабораторія не надіслала жодного. Покажи «Не застосовується».
* `lab_text_only`: лабораторія надрукувала лише текст, наприклад цільовий показник, рівень ризику або діапазон для певного етапу життя. Покажи `lab_reported.reference_range`.
* `not_measured`: результат має статус `undeliverable`, тому немає значення для порівняння. Покажи `status_reason`.

**aniva\_range** `object`

Порівняльні значення, які зібрала Aniva, у тій самій шкалі, що й `value`. Вони різняться за віком, статтю та тижнем вагітності. `normal_*` — це загальний діапазон. `optimal_*` — вужчий діапазон. Ці значення мають виключно інформаційний характер. Вони не є медичною порадою, діагнозом чи оцінкою результату. Aniva не виставляє позначок на їхній основі. Використовуй `reference_range_lab` як стандарт для результату. `null`, якщо твій ключ не має права доступу `aniva_ranges_view` або Aniva не має значень для цього біомаркера.

**референтний діапазон**

**normal\_min** `number`

Нижня межа нормального діапазону. Може бути `null`.

**normal\_max** `number`

Верхня межа нормального діапазону. Може бути `null`.

**optimal\_min** `number`

Нижня межа оптимального діапазону. Може бути `null`.

**optimal\_max** `number`

Верхня межа вужчого діапазону. Може бути `null`.

**sources** `object[]`

Опубліковані джерела, які Aniva зафіксувала для цих значень. Кожен запис містить `title` і `url`. `url` може бути `null`. Список порожній, якщо Aniva не зафіксувала жодного джерела.

**tested\_at** `string`

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

**comment** `string`

Необов’язковий коментар до результату. Може бути `null`.

**origin** `string`

Хто надав документ, із якого взято це значення, як у полі `origin` документа. Значення із завантаженого документа отримане, коли Aniva зчитала файл, а не з лабораторного звіту. `null` для результату `planned`.

**lab\_reported** `object`

Власний рядок звіту лабораторії-виконавця дослівно — щоб звіряти ці дані з PDF-файлом лабораторії. Може бути `null`, якщо в нас немає первинного запису для результату.

Усі інші поля результату нормалізовано: `value` і `unit` переведено в стандартну одиницю біомаркера, а `biomarker_name` — це наша назва аналіту, а не лабораторна. Поля нижче не нормалізовано. Вважай їх довідкою у друкованому вигляді, а канонічні поля — засобом перевірки узгодженості.

Числа тут — це власні межі лабораторії в її шкалі: `reference_range_min` і `reference_range_max` **не** переведені в інші одиниці й відрізнятимуться від `reference_range_lab` скрізь, де ці дві шкали різні. Межа, яку лабораторія залишила відкритою, залишається `null`; нічого не домислюється і не підставляється за замовчуванням.

**дані лабораторії**

**name** `string`

Назва аналіту в тому вигляді, як її надрукувала лабораторія. Може бути `null`.

**code** `string`

Власний код аналіту лабораторії. Може бути `null`.

**category** `string`

Заголовок розділу звіту, наприклад `Klinische Chemie`. Може бути `null`.

**value** `string`

Значення у друкованому вигляді. Це рядок, щоб нечислові результати зберігалися без змін (`<0.04`, `negativ`, `1:100`). Може бути `null`.

**unit** `string`

Одиниця вимірювання у друкованому вигляді, наприклад `U/l`. Може бути `null`.

**reference\_range** `string`

Референтний інтервал у друкованому вигляді, включно з односторонніми порогами: `40 - 129`, `< 50`, `> 55`. Може бути `null`.

**reference\_range\_min** `number`

Нижня межа лабораторії без переведення одиниць. `null` для інтервалу, який лабораторія залишила відкритим знизу.

**reference\_range\_max** `number`

Верхня межа лабораторії без переведення одиниць. `null` для інтервалу, який лабораторія залишила відкритим зверху.

**flag** `string`

Лабораторна позначка відхилення для цього рядка: `normal`, `high`, `low`, `critical_high`, `critical_low`, `abnormal`. Код, який ми не розпізнаємо, передається так, як його надіслала лабораторія. Може бути `null`.

**result\_status** `string`

Статус результату від лабораторії: `final`, `preliminary`, `correction`, `incomplete`, `partial`, `deleted`, `cannot_be_obtained`. Значення зі статусом `preliminary` ще може змінитися. Пізніший [вебхук](https://docs.anivahealth.com/uk/concepts/webhooks.md)`results.updated` підкаже тобі, коли завантажити дані знову. Може бути `null`.

**comment** `string`

Власна примітка лабораторії до цього рядка. Відступи стовпців прибрано; формулювання не змінено. Може бути `null`.

**genetic\_results** `object[]` *required*

Масив генетичних результатів біомаркерів.

**об’єкт генетичного результату**

**id** `string`

Ідентифікатор рядка лабораторного результату (UUID). Він не змінюється, коли лабораторія виправляє цей рядок, тому використовуй його для upsert. `null` для результату `planned`.

**status** `string` *required*

Статус результату. Одне зі значень:

* `planned` — замовлено, лабораторія ще не надіслала результат.
* `received` — отримано від лабораторії.
* `likely_wrong` — автоматична перевірка Aniva або учасник сумнівається в генотипі. Не підтверджено. Див. `status_reason`.
* `fault` — отримано, але підтверджено як хибне; **не використовуй у клінічній практиці**. Див. `status_reason`.
* `undeliverable` — лабораторія не змогла визначити генотип. Див. `status_reason`.

**status\_reason** `string` *required*

Чому результат сумнівний або непридатний для використання. Заповнюється для `likely_wrong`, `fault` і `undeliverable`, `null` для всіх інших статусів.

**lab\_code** `string`

Лабораторний код (штрихкод пробірки), за яким зареєстровано результат. `null` для результату `planned` та для результатів, які лабораторія надіслала без коду.

**biomarker\_id** `integer` *required*

Ідентифікатор біомаркера (гена).

**gene** `string` *required*

Символ гена (наприклад, APOE, MTHFR).

**genotype** `string`

Генотип для відображення (наприклад, E3/E4). Може бути `null`.

**clinical\_significance** `string`

Загальна клінічна значущість. Одне зі значень: `pathogenic`, `likely_pathogenic`, `uncertain`, `likely_benign`, `benign`, `high_risk`, `moderate_risk`, `low_risk`, `protective`, `drug_response`, `poor_metabolizer` або `rapid_metabolizer`. Може бути `null`.

**risk\_description** `string`

Опис ризику для цього генотипу. Може бути `null`.

**tested\_at** `string`

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

**comment** `string`

Необов’язковий коментар до результату. Може бути `null`.

**origin** `string`

Хто надав документ, із якого взято це значення, як у полі `origin` документа. Значення із завантаженого документа отримане, коли Aniva зчитала файл, а не з лабораторного звіту. `null` для результату `planned`.

**variants** `object[]` *required*

Виявлені генетичні варіанти.

**об’єкт варіанта**

**name** `string` *required*

Загальновживана назва варіанта (наприклад, APOE E4).

**clinical\_significance** `string`

Клінічна значущість на рівні варіанта. Може бути `null`.

**description** `string`

Опис варіанта. Може бути `null`.

**hgvs\_c** `string`

Нотація кодувальної ДНК за HGVS. Може бути `null`.

**hgvs\_p** `string`

Нотація білка за HGVS. Може бути `null`.

**conditions** `object[]` *required*

Пов’язані стани.

**об’єкт стану**

**condition** `string` *required*

Назва стану або захворювання.

**association\_description** `string`

Опис зв’язку між варіантом і станом. Може бути `null`.

**badge** `string`

Короткий текст бейджа для відображення. Може бути `null`.

**snvs** `object[]` *required*

Однонуклеотидні варіанти, що визначають цей варіант.

**об’єкт SNV**

**rs\_id** `string` *required*

Ідентифікатор dbSNP (наприклад, rs429358).

**allele** `string` *required*

Алель варіанта (`A`, `C`, `G`, `T`, `del`, `ins` або `undetermined`).

**reference\_allele** `string` *required*

Популяційний референтний алель.

**hgvs\_c** `string`

Нотація кодувальної ДНК за HGVS. Може бути `null`.

**hgvs\_p** `string`

Нотація білка за HGVS. Може бути `null`.

**documents** `object[]` *required*

Документи лабораторних звітів. Використовуй `GET /api/v1/documents/{id}`, щоб завантажити кожен файл.

**об’єкт документа**

**id** `string` *required*

Ідентифікатор файлу (UUID). Передай його в [Завантажити документ](https://docs.anivahealth.com/uk/api/documents/download-document.md), щоб отримати файл.

**file\_name** `string` *required*

Назва файлу. [Завантажити документ](https://docs.anivahealth.com/uk/api/documents/download-document.md) надсилає ту саму назву в `Content-Disposition`. Вона містить дату, назву документа й лабораторний код, наприклад `20260405 - Quade Befund - 7642001234.pdf`. Використовуй її лише для відображення. Зчитуй лабораторний код із `lab_code`, а не з назви.

**original\_file\_name** `string` *required*

Назва файлу точно така, як її передало джерело, наприклад `7642100312_B0012_FA_V.pdf` від лабораторії або власна назва файлу, завантаженого учасником. Aniva її не змінює.

**origin** `string` *required*

Хто передав файл. Одне зі значень: `lab` (надіслала лабораторія), `member_upload` (завантажив учасник), `staff_upload` (завантажили працівники Aniva) або `partner_upload` (вивантажено тобою через [Вивантажити документ](https://docs.anivahealth.com/uk/api/documents/upload-document.md)).

**content\_type** `string` *required*

Медіатип файлу, наприклад `application/pdf`, `image/jpeg` або `text/csv`. Більшість лабораторних звітів мають формат PDF.

**etag** `string`

Версія вмісту файлу. Вона змінюється щоразу, коли змінюються байти, тому порівнюй її зі збереженим у тебе значенням, щоб визначити, чи потрібно завантажувати файл повторно. [Завантажити документ](https://docs.anivahealth.com/uk/api/documents/download-document.md) надсилає її в лапках як стандартний HTTP-заголовок `ETag`. Може бути `null`, якщо збережений файл відсутній.

**size\_bytes** `integer`

Розмір файлу в байтах. Може бути `null`, якщо збережений файл відсутній.

**lab\_code** `string`

Лабораторний код (штрихкод пробірки), до якого належить звіт. Може бути `null`, якщо лабораторія його не вказала.

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

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

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

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

| Статус | Опис |
| - | - |
| `400` | Недійсний формат ID — передане значення не є дійсним UUID. |
| `403` | Доступ заборонено — у твоєму API-ключі немає дозволу `results_view`, немає жодного з дозволів `home_kit_orders_view` і `home_kit_orders_manage`, або замовлення набору для домашнього тесту поза твоїм контекстом доступу. |
| `404` | Замовлення набору для домашнього тесту не знайдено. |
| `500` | Внутрішня помилка сервера. |

```bash cURL theme={null}
curl --request GET \
  --url https://anivahealth.com/api/v1/home-kit-orders/d1e2f3a4-5b6c-4d7e-8f9a-0b1c2d3e4f5a/results \
  --header 'x-api-key: YOUR_API_KEY'
```

```json 200 theme={null}
{
  "status": "in_progress",
  "submissions": [
    {
      "lab_code": "7642001234",
      "status": "in_progress"
    }
  ],
  "clinical_results": [
    {
      "id": "e9f1a3c5-6b7d-4c2e-8a4f-1d3b5c7e9f02",
      "status": "received",
      "status_reason": null,
      "lab_code": "7642001234",
      "biomarker_id": 104,
      "biomarker_name": "Vitamin D",
      "category": "Vitamins",
      "value": 38.5,
      "value_operator": "eq",
      "unit_id": 1,
      "unit": "ng/mL",
      "reference_range_lab": {
        "normal_min": 30,
        "normal_max": 100,
        "optimal_min": null,
        "optimal_max": null
      },
      "reference_range_lab_absent_reason": null,
      "aniva_range": {
        "normal_min": 30,
        "normal_max": 100,
        "optimal_min": 30,
        "optimal_max": 60,
        "sources": [
          {
            "title": "Example source title",
            "url": "https://example.com/source"
          }
        ]
      },
      "tested_at": "2026-04-05",
      "comment": null,
      "origin": "lab",
      "lab_reported": {
        "name": "Vitamin D (25-OH)",
        "code": "vitd",
        "category": "Endokrinologie",
        "value": "38.5",
        "unit": "ng/ml",
        "reference_range": "30 - 100",
        "reference_range_min": 30,
        "reference_range_max": 100,
        "flag": "normal",
        "result_status": "final",
        "comment": null
      }
    },
    {
      "id": null,
      "status": "planned",
      "status_reason": null,
      "lab_code": null,
      "biomarker_id": 79,
      "biomarker_name": "Thyroid-Stimulating Hormone (TSH)",
      "category": "Hormones",
      "value": null,
      "value_operator": null,
      "unit_id": null,
      "unit": null,
      "reference_range_lab": null,
      "reference_range_lab_absent_reason": null,
      "aniva_range": null,
      "tested_at": null,
      "comment": null,
      "origin": null,
      "lab_reported": null
    }
  ],
  "genetic_results": [
    {
      "id": "1b3d5f7a-9c2e-4a6b-8d0f-2e4a6c8b0d13",
      "status": "received",
      "status_reason": null,
      "lab_code": "7642001234",
      "biomarker_id": 348,
      "gene": "APOE",
      "genotype": "E3/E4",
      "clinical_significance": "moderate_risk",
      "risk_description": "Carriers of one APOE E4 allele have a moderately increased risk of Alzheimer's disease.",
      "tested_at": "2026-04-05",
      "comment": null,
      "origin": "lab",
      "variants": [
        {
          "name": "APOE E4",
          "clinical_significance": "moderate_risk",
          "description": "The E4 allele is associated with increased Alzheimer's risk.",
          "hgvs_c": "c.388T>C",
          "hgvs_p": "p.Cys130Arg",
          "conditions": [
            {
              "condition": "Alzheimer's disease",
              "association_description": "Increased risk with one E4 allele",
              "badge": "Moderate Risk"
            }
          ],
          "snvs": [
            {
              "rs_id": "rs429358",
              "allele": "C",
              "reference_allele": "T",
              "hgvs_c": "c.388T>C",
              "hgvs_p": "p.Cys130Arg"
            }
          ]
        }
      ]
    }
  ],
  "documents": [
    {
      "id": "f8a1b2c3-d4e5-4f6a-7b8c-9d0e1f2a3b4c",
      "file_name": "20260405 - Quade Befund - 7642001234.pdf",
      "original_file_name": "7642001234_B0012_FA_E.pdf",
      "origin": "lab",
      "content_type": "application/pdf",
      "etag": "56104b36f860cfd5b41efc716fdf7b6f",
      "size_bytes": 258341,
      "lab_code": "7642001234"
    }
  ]
}
```

```json 404 theme={null}
{
  "error": "Home kit order not found"
}
```


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