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

# Termine

> So funktionieren Blutabnahmetermine in der Aniva API für Labortests: Buchung, Panels, Biomarker, Statusänderungen und Stornierung.

Ein Termin ist eine geplante Blutabnahme für ein Patientenprofil an einem physischen Teststandort, durchgeführt von einer medizinischen Fachkraft. Kits, die per Post an einen Patienten gesendet werden, sind keine Termine – siehe [Heimtest-Kit-Bestellungen](https://docs.anivahealth.com/de/concepts/home-kit-orders.md).

## Felder

**id** `string` *required*

Von Aniva automatisch generierte UUID. Nutze sie, um Panels hinzuzufügen, die Blutabnahme zu bestätigen und Ergebnisse abzurufen.

**profile\_id** `string` *required*

Die UUID des Profils, zu dem dieser Termin gehört.

**location\_id** `string`

Die UUID des Teststandorts, an dem die Blutabnahme stattfindet. Heimtest-Kits sind keine Termine – siehe
[Heimtest-Kit-Bestellungen](https://docs.anivahealth.com/de/concepts/home-kit-orders.md).

**scheduled\_at** `string`

Geplanter Zeitpunkt der Blutabnahme im ISO-8601-Format. Wird immer als UTC-Zeitpunkt mit dem Suffix `Z`
zurückgegeben (z. B. `2026-04-15T08:30:00Z`). Beim Erstellen / Aktualisieren **muss der Wert eine Zeitzonenangabe
enthalten** (entweder `Z` oder einen expliziten Offset wie `+02:00`) – Zeitangaben ohne Zeitzone werden abgelehnt. Muss
in der Zukunft liegen und an von Aniva betriebenen Standorten mindestens 12 Stunden im Voraus ([Mindestvorlaufzeit](https://docs.anivahealth.com/de/api/appointments/create-appointment.md#mindestvorlaufzeit)).

**status** `string` *required*

Aktueller Lebenszyklus-Status. Einer der Werte `pending`, `confirmed`, `blood_drawn` oder `cancelled`. Siehe
[Lebenszyklus](#lebenszyklus) unten. Der genaue Bearbeitungsstand der Laborergebnisse (`in_progress` vs. `completed`) ergibt
sich aus [Ergebnisse abrufen](https://docs.anivahealth.com/de/api/appointments/get-results.md); den detaillierten Sendungsverlauf (unterwegs,
zugestellt usw.) erhältst du, indem du jedem Eintrag im eingebetteten `shipments`-Array zu
[Sendung abrufen](https://docs.anivahealth.com/de/api/shipments/get-shipment.md) folgst.

**cancellation\_reason** `string`

Freitextgrund, der bei der Stornierung des Termins erfasst wurde (z. B. Nichterscheinen, späte Stornierung,
'Fehlgeschlagen. Wiederholung erforderlich'). `null`, sofern `status` nicht `cancelled` ist.

**results\_ready\_emails** `string[]` *required*

Adressen in Kleinbuchstaben, die jeweils eine E-Mail erhalten, sobald alle Laborergebnisse final sind. Leer, wenn deaktiviert. Siehe
[E-Mails bei fertigen Ergebnissen](https://docs.anivahealth.com/de/concepts/results.md#e-mails-bei-fertigen-ergebnissen).

**draw\_method** `string` *required*

Art der Blutabnahme: `capillary` (aus der Fingerkuppe oder dem Oberarm, in Microtainer) oder `venous` (aus der Vene,
in Röhrchen). Entspricht der im Termin festgelegten Methode, sonst der `default_draw_method` des
[Standorts](https://docs.anivahealth.com/de/concepts/locations.md). Nach der Blutabnahme ist es die verwendete Methode.

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

ISO-8601-Zeitstempel der Erstellung des Termins.

**updated\_at** `string`

ISO-8601-Zeitstempel der letzten Aktualisierung. Null, falls der Termin noch nie aktualisiert wurde.

**lab\_codes** `string[]` *required*

Laborcodes (Röhrchen-Barcodes), die bei [Blutabnahme bestätigen](https://docs.anivahealth.com/de/api/appointments/confirm-blood-draw.md)
erfasst wurden, in Scan-Reihenfolge. Leer, bis die Blutabnahme bestätigt ist. Bei einer venösen Blutabnahme ist ein Code auf jedem
Röhrchen aufgedruckt; bei einer kapillaren Blutabnahme gibt es einen Code pro Mikroröhrchen. Ergebnisse und Dokumente verweisen über
`lab_code` darauf.

**panels** `object[]` *required*

Panels, die diesem Termin zugeordnet sind, als `{ panel_id, added_at }`-Einträge. Siehe
[Panels hinzufügen](#panels-hinzufuegen).

**individual\_biomarkers** `object[]` *required*

Einzeln gebuchte Biomarker, die diesem Termin zugeordnet sind, als `{ biomarker_id, added_at }`-Einträge. Siehe
[Einzelne Biomarker](#einzelne-biomarker).

**shipments** `object[]` *required*

Sendungen, die mit diesem Termin verknüpft sind, als `{ id, added_at }`-Einträge, älteste Verknüpfung zuerst. Siehe
[Sendungen verknüpfen](#sendungen-verknuepfen).

**profile** `object` *required*

Das vollständige Profilobjekt des Patienten, eingebettet in jeder Terminantwort. Die folgenden Felder
sind eine Teilmenge. [Termin abrufen](https://docs.anivahealth.com/de/api/appointments/get-appointment.md) listet alle auf.

**Eigenschaften**

**id** `string`

UUID des zugehörigen Profils.

**first\_name** `string`

Vorname des Patienten.

**last\_name** `string`

Nachname des Patienten.

**email** `string`

E-Mail-Adresse des Patienten.

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

Geburtsdatum im Format `YYYY-MM-DD`.

**sex** `integer`

Biologisches Geschlecht nach ISO/IEC 5218.

## Lebenszyklus

Termine haben vier Lebenszyklus-Zustände:

```
pending → confirmed → blood_drawn
   │          │             │
   └──────────┴─────────────┴──→ cancelled
```

| Status | Bedeutung |
| - | - |
| `pending` | Der Termin ist geplant und wartet auf Bestätigung. Kann [aktualisiert](https://docs.anivahealth.com/de/api/appointments/update-appointment.md) oder [storniert](https://docs.anivahealth.com/de/api/appointments/cancel-appointment.md) werden. |
| `confirmed` | Die Terminplanung wurde bestätigt (z. B. durch die Praxis), aber es wurde noch kein Blut abgenommen. Kann weiterhin aktualisiert oder storniert werden. |
| `blood_drawn` | Die Laborcodes wurden über [Blutabnahme bestätigen](https://docs.anivahealth.com/de/api/appointments/confirm-blood-draw.md) übermittelt und die Laborauftrags-Pipeline wurde gestartet. Panels sind gesperrt und der Termin kann nicht mehr verschoben oder storniert werden. |
| `cancelled` | Der Termin wurde storniert. Endzustand – keine weiteren Übergänge. |

> [!NOTE]
>
> Der Terminstatus ist bewusst grob gehalten – detailliertere Fortschritte sind über
> eigene Endpunkte abrufbar:
>
> * **Bearbeitungsstand der Laborergebnisse** →
>   [Ergebnisse abrufen](https://docs.anivahealth.com/de/api/appointments/get-results.md) – das oberste `status`-Feld ist `in_progress` oder
>   `completed`.
> * **Sendungsverlauf** (unterwegs, zugestellt usw.) → folge jedem Eintrag im eingebetteten
>   `shipments`-Array des Termins zu [Sendung abrufen](https://docs.anivahealth.com/de/api/shipments/get-shipment.md) – jede
>   Sendung hat ihren eigenen `status` und ein `status_updates`-Ereignisprotokoll.
>
> Jede Statusänderung sendet einen `appointment.*`-[Webhook](https://docs.anivahealth.com/de/concepts/webhooks.md), zum Beispiel
> `appointment.confirmed`. Eine neue Uhrzeit oder ein neuer Standort sendet `appointment.rescheduled`.

> [!WARNING]
>
> Das Bestätigen eines Termins (Wechsel zu `blood_drawn`) ist **unumkehrbar**. Sobald du den oder die
> Laborcodes übermittelst, wird die Laborauftrags-Pipeline gestartet und lässt sich nicht mehr rückgängig machen. Aktualisierungen und Stornierungen
> sind nur erlaubt, solange der Termin den Status `pending` oder `confirmed` hat.

## Termine auflisten

Rufe alle Termine ab, auf die dein API-Schlüssel Zugriff hat:

```
GET /api/v1/appointments
```

Übergib optional `?profile_id={uuid}`, um nach einem bestimmten Profil zu filtern. Ohne diesen Parameter gilt ein Standard-Zeitfenster (die letzten 2 Monate bis 1 Monat in die Zukunft).

## Termin aktualisieren

Bevor die Blutabnahme bestätigt ist, kannst du den Termin verschieben oder den Teststandort ändern:

```
PATCH /api/v1/appointments/{id}
```

Übergib zum Aktualisieren eine beliebige Kombination aus `scheduled_at`, `location_id`, `draw_method` und `results_ready_emails`. Gib nur die Felder an, die du ändern möchtest.

## Abnahmemethode

Jeder Termin hat eine `draw_method`: `capillary` (Fingerkuppe oder Oberarm, in Mikroröhrchen) oder
`venous` (aus der Vene, in Röhrchen). Sie gilt nur für die Blutabnahme. Urinproben, Abstriche und andere
Nicht-Blutproben werden bei beiden Methoden auf die gleiche Weise genommen.

Standardmäßig ist das die `default_draw_method` des Standorts. Setze `draw_method` beim Erstellen oder Aktualisieren, um
eine andere Methode zu nutzen, oder setze es auf `null`, um zur Standardeinstellung des Standorts zurückzukehren. Der Standort muss
die Methode in `draw_methods` auflisten und die gebuchten Tests müssen damit möglich sein, sonst gibt die Anfrage
`400` zurück. Nach der Blutabnahme kannst du sie nicht mehr ändern. Nach der Blutabnahme ist `draw_method` die
Methode, die verwendet wurde.

## Ein Termin pro Profil, Standort und Zeitpunkt

Ein Profil hat höchstens einen nicht stornierten Termin pro `(location_id, scheduled_at)`-Paar – einer
Person kann nicht am selben Ort zur selben Zeit zweimal Blut abgenommen werden, unabhängig davon, wie viele parallele Buchungen der
Standort zulässt.

Sowohl [Termin erstellen](https://docs.anivahealth.com/de/api/appointments/create-appointment.md) als auch
[Termin aktualisieren](https://docs.anivahealth.com/de/api/appointments/update-appointment.md) setzen das durch und geben `409` mit einer
`appointment_id` zurück, die auf den bereits bestehenden Termin verweist. Behandle diese Antwort als bereits
gebucht statt als Fehler für einen erneuten Versuch: Rufe den genannten Termin ab, verschiebe ihn oder storniere ihn.

In der Praxis ist wiederholtes Erstellen sicher. Eine Anfrage, die du nach einem Netzwerk-Timeout
erneut sendest oder die ein Nutzer zweimal auslöst, ergibt einen einzigen Termin statt zwei – wodurch
du doppelte Buchungen für denselben Patienten nie nachträglich bereinigen musst.

> [!NOTE]
>
> Änderungen sind nur vor der Blutabnahme erlaubt – also solange der Termin den Status `pending`
> oder `confirmed` hat. Sobald der Termin auf `blood_drawn` steht oder `cancelled` wurde, lässt er
> sich nicht mehr ändern. Die einzige Ausnahme ist `results_ready_emails`: Dieses Feld kannst du
> auch nach der Blutabnahme noch allein ändern.

## Termin stornieren

Storniere einen Termin, der nicht mehr benötigt wird:

```
DELETE /api/v1/appointments/{id}
```

Dadurch wird der Terminstatus auf `cancelled` gesetzt. Der stornierte Termin wird in der Antwort zurückgegeben.

Optional kannst du im Body eine `cancellation_reason` (bis zu 500 Zeichen) als Grund mitsenden. Sie
wird am Termin gespeichert und bei späteren Lesezugriffen als `cancellation_reason` zurückgegeben.

> [!NOTE]
>
> Eine Stornierung ist nur vor der Blutabnahme erlaubt – also solange der Termin den Status
> `pending` oder `confirmed` hat. Termine, die bereits auf `blood_drawn` stehen, lassen sich nicht
> mehr stornieren.

## Panels hinzufügen

Bevor du die Blutabnahme bestätigst, füge die gewünschten Bluttest-Panels mit diesem Aufruf hinzu:

```
POST /api/v1/appointments/{id}/panels
```

Übergib im Feld `panel_ids` ein Array aus Panel-UUIDs. Die Panel-IDs erhältst du von Aniva für dein Partnerkonto.

> [!NOTE]
>
> Panels müssen vor der Blutabnahme hinzugefügt werden – also solange der Termin den Status
> `pending` oder `confirmed` hat. Sobald der Termin auf `blood_drawn` steht, kannst du keine Panels
> mehr hinzufügen oder ändern.

## Panels entfernen

Wenn du vor der Blutabnahme Panels entfernen musst, rufe diesen Endpunkt auf:

```
DELETE /api/v1/appointments/{id}/panels
```

Übergib im Feld `panel_ids` ein Array aus Panel-UUIDs. Das Entfernen ist idempotent: Ein nicht hinzugefügtes Panel wird ignoriert.

> [!NOTE]
>
> Wie beim Hinzufügen ist das Entfernen nur vor der Blutabnahme erlaubt – also solange der Termin
> den Status `pending` oder `confirmed` hat. Sobald der Termin auf `blood_drawn` steht, lassen sich
> keine Panels mehr entfernen.

## Einzelne Biomarker

Du kannst einzelne Biomarker als À-la-carte-Tests zu einem Termin hinzufügen, unabhängig von vorgefertigten Panels. Das ist praktisch, wenn ein Behandler statt einer vorgegebenen Zusammenstellung eine individuelle Auswahl möchte. Die hinzugefügten Biomarker erscheinen in der Terminantwort als Array `individual_biomarkers` (auf derselben Ebene wie `panels`). Die Routing-Entscheidungen trifft nachgelagert die Bestelllogistik-Pipeline anhand der jeweiligen Laborzuordnungen pro Biomarker.

Biomarker hinzufügen (idempotent – bereits hinzugefügte Biomarker bleiben erhalten):

```
PATCH /api/v1/appointments/{id}/biomarkers
```

Biomarker entfernen (idempotent – nicht hinzugefügte Biomarker werden ignoriert):

```
DELETE /api/v1/appointments/{id}/biomarkers
```

Beide Endpunkte erwarten ein `biomarker_ids`-Array und prüfen die resultierende Auswahl gegen die Vollständigkeitsregeln jedes Labors – lässt sich ein Auftrag nicht sauber platzieren (z. B. ein CRP/HDL-Verhältnis ohne CRP und HDL), gibt der Endpunkt `400` mit den zusätzlich erforderlichen Biomarkern zurück und speichert nichts. Nutze [Biomarker auflisten](https://docs.anivahealth.com/de/api/biomarkers/list-biomarkers.md), um Biomarker-IDs zu finden.

> [!NOTE]
>
> Wie bei Panel-Änderungen können einzelne Biomarker nur vor der Blutabnahme hinzugefügt oder
> entfernt werden – also solange der Termin den Status `pending` oder `confirmed` hat. Sobald der
> Termin auf `blood_drawn` steht, ist der individuelle Snapshot eingefroren.

## Vorschau der benötigten Probengefäße

Nachdem du Panels oder einzelne Biomarker hinzugefügt hast, kannst du dir vorab anzeigen lassen, welche physischen Probengefäße für die Probenahme benötigt werden:

```
GET /api/v1/appointments/{id}/preview
```

Das `containers`-Array der Antwort enthält Typ, Namen, Kappenfarbe, Volumen, Hersteller-Artikelnummer und Anzahl für jedes benötigte Gefäß. So können Behandler vor der Blutabnahme das richtige Material vorbereiten. Die Antwort enthält außerdem ein `pricing`-Objekt – die Gesamtabrechnung für den Termin (die angefallenen Positionen, die hinzugefügten Panels und eine Zeile pro geliefertem Biomarker, jeweils mit deinem Tarifpreis neben dem Endkundenpreis; siehe [Preise](https://docs.anivahealth.com/de/concepts/pricing.md)), das befüllt wird, wenn der Termin hinzugefügte Tests hat und dein Key den Scope `prices_view` besitzt, andernfalls `null`. `routing` wird bewusst nie ausgegeben und ist immer `null`.

> [!NOTE]
>
> Die Vorschau spiegelt die aktuell hinzugefügten Panels und Biomarker wider. Wenn du danach Panels
> hinzufügst oder entfernst, rufe den Vorschau-Endpunkt erneut auf, um aktualisierte Angaben zu den
> benötigten Probengefäßen zu erhalten.

## Blutabnahme bestätigen

Übermittle nach der Blutabnahme die Laborcodes (Röhrchen-Barcodes), um die Laborauftrags-Pipeline auszulösen:

```
POST /api/v1/appointments/{id}/confirm
```

Sende `lab_code`, wenn auf allen Röhrchen derselbe Code steht (venöse Blutabnahme), oder `lab_codes`
mit einem Eintrag pro Code – jeweils mit den abgedeckten `panel_ids` –, wenn jedes Panel in eigene
Röhrchen mit eigenem Code abgenommen wird (kapillare Blutabnahme). Jedes Panel bildet dann unter
seinem Code einen eigenen Laborauftrag. Die Codes werden am Termin als `lab_codes` zurückgegeben.

Bei einer kapillaren Blutabnahme wird die Probe auf Mikrotainer aufgeteilt. Zuerst kommen die Panels,
in Buchungsreihenfolge. Einzelne Biomarker füllen dann den freien Platz in den Panel-Mikrotainern.
Wenn sie mehr Platz brauchen, kommen neue Mikrotainer hinzu. Wir verteilen sie gleichmäßig. Jeder
Mikrotainer fasst höchstens 150 µl an einzelnen Biomarkern. Aufrufe, die Panels oder Biomarker
ändern, antworten mit `400`, wenn die resultierende Auswahl gegen diese Regel verstößt.

Dadurch wechselt der Terminstatus zu `blood_drawn` und die Laborverarbeitung wird gestartet. Diese Aktion lässt sich nicht rückgängig machen.

## Sendungsabholung

> [!WARNING]
>
> `POST /api/v1/appointments/pickup` wurde **entfernt**, ebenso der Terminstatus
> `shipment_picked_up`. Der Endpunkt antwortet jetzt mit `405 Method Not Allowed`, weil der Pfad an
> die Route für Termine nach ID durchgereicht wird. In seiner letzten Phase war der Endpunkt ein
> No-op, der den Aufruf annahm und nichts tat – das Entfernen ändert also kein Verhalten, auf das du
> dich verlassen hast.

Um den Verlauf nach der Blutabnahme zu verfolgen, folge jedem Eintrag im eingebetteten `shipments`-Array
des Termins zu [Sendung abrufen](https://docs.anivahealth.com/de/api/shipments/get-shipment.md) – jede Sendung hat ihren eigenen
`status` und einen `status_updates`-Verlauf.

## Sendungen verknüpfen

Ein Termin kann mit einer oder mehreren Sendungen verknüpft sein (und umgekehrt – es handelt sich
um eine n:m-Beziehung). Die aktuellen Verknüpfungen erscheinen eingebettet auf beiden Seiten:

* am Termin als `shipments`-Array mit `{ id, added_at }`-Einträgen;
* an der Sendung als `appointments`-Array mit `{ id, added_at }`-Einträgen.

Beide Arrays beginnen mit der ältesten Verknüpfung. Jede `id` verweist für die vollständige
Payload auf den jeweiligen Detail-Endpunkt ([Sendung abrufen](https://docs.anivahealth.com/de/api/shipments/get-shipment.md) /
[Termin abrufen](https://docs.anivahealth.com/de/api/appointments/get-appointment.md)).

Sendungen werden beim Erstellen über das Feld `appointment_id` in
[Sendung erstellen](https://docs.anivahealth.com/de/api/shipments/create-shipment.md) verknüpft. Danach verwaltest du Verknüpfungen
von der Sendung aus mit [Termine mit Sendung verknüpfen](https://docs.anivahealth.com/de/api/shipments/attach-appointments-to-shipment.md)
und [Termine von Sendung trennen](https://docs.anivahealth.com/de/api/shipments/detach-appointments-from-shipment.md); beide geben die
aktualisierte Terminliste für diese Sendung zurück. Um die Sendungen eines Termins vollständig
abzurufen, nutze [Sendungen auflisten](https://docs.anivahealth.com/de/api/shipments/list-shipments.md) mit `?appointment_id=`.

Für Änderungen gilt: Verknüpfungen können erstellt oder entfernt werden, wenn ENTWEDER

* der Termin nach der Blutabnahme liegt (`blood_drawn`) oder
* die Sendung vor weniger als 24 Stunden erstellt wurde.

Außerhalb dieses Zeitfensters ist die Verknüpfung gesperrt, damit historische Datensätze unverändert bleiben.

## Laborergebnisse abrufen

Sobald das Labor die Blutproben verarbeitet hat, rufe klinische und genetische Ergebnisse ab:

```
GET /api/v1/appointments/{id}/results
```

Die Antwort enthält neben den eingegangenen Ergebnissen auch geplante Tests (Status `planned`),
damit du nachverfolgen kannst, was noch aussteht. Das übergeordnete Feld `status` ist `in_progress`,
bis jede Einreichung abgeschlossen ist, und danach `completed` (oder `fault`, wenn keine Ergebnisse
gemeldet wurden) – daran erkennst du, ob die Laborarbeit für den Termin abgeschlossen ist. Ein
`appointment.results.completed`-[Webhook](https://docs.anivahealth.com/de/concepts/webhooks.md) informiert dich, sobald es so weit
ist, sodass du nicht pollen musst. Das Array `submissions` schlüsselt dies pro Laborauftrag auf,
jeweils mit eigenem `lab_code`. Jedes eingegangene Ergebnis und Dokument trägt den `lab_code`, unter
dem es eingereicht wurde. PDFs der Laborberichte sind im Array `documents` referenziert – lade sie
mit `GET /api/v1/documents/{id}` herunter.

## Beispieltermin

```json theme={null}
{
  "id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
  "profile_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "location_id": "c3d4e5f6-a7b8-9012-cdef-123456789012",
  "scheduled_at": "2026-04-15T08:30:00Z",
  "status": "confirmed",
  "cancellation_reason": null,
  "results_ready_emails": [],
  "draw_method": "venous",
  "created_at": "2026-04-01T10:00:00Z",
  "updated_at": null,
  "profile": {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "handle": null,
    "first_name": "Jane",
    "last_name": "Doe",
    "email": "jane.doe@example.com",
    "phone": "+4930123456789",
    "sex": 2,
    "date_of_birth": "1990-06-15",
    "height": 170,
    "weight": 62,
    "language": "en",
    "transactional_emails_enabled": true,
    "created_at": "2026-04-01T09:55:00Z",
    "updated_at": null
  },
  "panels": [
    {
      "panel_id": "f1c2d4a3-7b8e-4f2a-9c1d-2e3f4a5b6c7d",
      "added_at": "2026-04-01T10:05:00Z"
    }
  ],
  "individual_biomarkers": [
    {
      "biomarker_id": 42,
      "added_at": "2026-04-01T10:07:00Z"
    }
  ],
  "shipments": [
    {
      "id": "P2611194821",
      "added_at": "2026-04-15T07:00:00Z"
    }
  ],
  "lab_codes": []
}
```


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