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

# Termin erstellen

> Einen Blutabnahmetermin für ein Profil an einem Teststandort vereinbaren

Plane einen Termin zur Blutabnahme für ein Patientenprofil an einem bestimmten Teststandort. Nach dem Erstellen erhält der Termin standardmäßig den Status `confirmed` (bei manchen Standorten kann der Standard stattdessen `pending` sein – das ist eine Standorteinstellung). Füge mit [Panels hinzufügen](https://docs.anivahealth.com/de/api/appointments/add-panels.md) Bluttest-Panels hinzu, bevor du [die Blutabnahme bestätigst](https://docs.anivahealth.com/de/api/appointments/confirm-blood-draw.md).

> [!NOTE]
>
> Ein Profil kann pro Standort und Zeitpunkt höchstens **einen** Termin haben. Wenn du einen Termin
> für einen Zeitslot erstellst, den das Profil bereits belegt, gibt die API `409` mit der vorhandenen
> `appointment_id` zurück statt eines zweiten Termins – so kann eine wiederholte oder versehentlich
> doppelt gesendete Anfrage niemals eine Buchung verdoppeln. Siehe [Doppelte
> Termine](#doppelte-termine).

Sende einen optionalen `Idempotency-Key`-Header, damit sich das Erstellen sicher wiederholen lässt – bei Wiederholung mit demselben Schlüssel kommt die ursprüngliche Antwort zurück, statt einen zweiten Termin zu erstellen. Siehe [Idempotenz](https://docs.anivahealth.com/de/concepts/idempotency.md).

Erfordert den Scope `appointments_schedule`.

## Anfrage

### Body-Parameter

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

UUID des Patientenprofils, für das der Termin erstellt werden soll.

**location\_id** `string` *required*

UUID des Teststandorts, an dem die Blutabnahme stattfindet. Nutze [Standorte
auflisten](https://docs.anivahealth.com/de/api/locations/list-locations.md), um verfügbare Standort-IDs zu finden.

**scheduled\_at** `string` *required*

Datum und Uhrzeit des Termins im ISO-8601-Format (z. B. `2026-05-15T10:30:00Z` oder
`2026-05-15T12:30:00+02:00`). **Muss eine Zeitzonenangabe enthalten** – entweder `Z` oder einen
expliziten Offset wie `+02:00`; Zeitangaben ohne Zeitzone werden abgelehnt. Muss in der Zukunft
liegen.

Muss genau dem Start eines Zeitslots im Raster des Standorts entsprechen, und der Slot muss noch
Kapazität haben – lies zuerst [Verfügbarkeit abrufen](https://docs.anivahealth.com/de/api/locations/get-availability.md). Zeiten
außerhalb des Rasters geben `400` zurück; ein ausgebuchter Slot gibt `409` zurück. An von Aniva
betriebenen Standorten muss der Termin außerdem mindestens 12 Stunden in der Zukunft liegen – siehe
[Mindestvorlaufzeit](#mindestvorlaufzeit).

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

Bis zu 5 Adressen, die jeweils eine E-Mail erhalten, sobald alle Laborergebnisse final sind. Die
E-Mail verlinkt auf die Ergebnisseite im Aniva-Admin-Panel. Dein Schlüssel braucht
`results_view`-Zugriff auf den Patienten, sonst `403`. Lass das Feld weg, um die
Standardadressen der Gruppe des Patienten zu verwenden. Eine leere Liste schaltet die E-Mails aus.
Siehe [E-Mails bei fertigen Ergebnissen](https://docs.anivahealth.com/de/concepts/results.md#e-mails-bei-fertigen-ergebnissen).

**draw\_method** `string`

Art der Blutabnahme: `capillary` oder `venous`. Lass das Feld weg, um die `default_draw_method`
des Standorts zu verwenden. Der Standort muss die Methode in `draw_methods` aufführen, sonst
`400`.

## Antwort

Bei Erfolg gibt die API `201 Created` mit dem neuen Termin zurück.

**id** `string` *required*

Eindeutige Terminkennung (UUID).

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

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

**location\_id** `string`

UUID des Teststandorts, an dem die Blutabnahme stattfindet.

**scheduled\_at** `string`

Geplanter Terminzeitpunkt in UTC (ISO 8601 mit `Z`-Suffix, z. B.
`2026-05-15T10:30:00Z`). Kann `null` sein.

**status** `string` *required*

Aktueller Terminstatus. Einer von `pending`, `confirmed`, `blood_drawn` oder `cancelled`. Wie
vollständig die Laborergebnisse sind, ergibt sich aus [Ergebnisse
abrufen](https://docs.anivahealth.com/de/api/appointments/get-results.md); den genaueren Versandverlauf siehst du über jeden Eintrag
im eingebetteten `shipments`-Array (siehe unten) in Kombination mit [Sendung
abrufen](https://docs.anivahealth.com/de/api/shipments/get-shipment.md).

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

**profile** `object` *required*

Das mit diesem Termin verknüpfte Patientenprofil.

**profile**

**id** `string`

Eindeutige Profil-ID (UUID).

**handle** `string`

Profil-Handle oder Benutzername. Kann `null` sein.

**first\_name** `string`

Vorname. Kann `null` sein.

**last\_name** `string`

Nachname. Kann `null` sein.

**email** `string`

E-Mail-Adresse. Kann `null` sein.

**phone** `string`

Telefonnummer im E.164-Format. Kann `null` sein.

**sex** `integer`

Biologisches Geschlecht nach ISO/IEC 5218. Kann `null` sein.

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

Geburtsdatum im Format `YYYY-MM-DD`. Kann `null` sein.

**height** `number`

Körpergröße in Zentimetern. Kann `null` sein.

**weight** `number`

Gewicht in Kilogramm. Kann `null` sein.

**language** `string`

Bevorzugte Sprache: einer der 32 Codes unter [Profil erstellen](https://docs.anivahealth.com/de/api/profiles/create-profile.md).

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

Ob dieses Profil transaktionale (programmgesteuerte) E-Mails erhält. Kann `null` sein.

**panels** `AppointmentPanel[]` *required*

Aktuell diesem Termin zugeordnete Panels. Bei neu erstellten Terminen leer – füge sie über
[Panels hinzufügen](https://docs.anivahealth.com/de/api/appointments/add-panels.md) hinzu. Panel-Details (Name, Biomarker) findest
du über [Panels auflisten](https://docs.anivahealth.com/de/api/panels/list-panels.md).

**Felder der Panel-Verknüpfung**

**panel\_id** `string`

Panel-UUID – Abgleich über [Panels auflisten](https://docs.anivahealth.com/de/api/panels/list-panels.md).

**added\_at** `string`

ISO-8601-Zeitstempel, zu dem das Panel erstmals mit diesem Termin verknüpft wurde.

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

Einzeln gewählte Biomarker, die diesem Termin außerhalb eines Panels zugeordnet sind. Bei neu
erstellten Terminen leer – füge sie über [Einzelne Biomarker
hinzufügen](https://docs.anivahealth.com/de/api/appointments/add-individual-biomarkers.md) hinzu. Gleiche jede `biomarker_id` mit
[Biomarker auflisten](https://docs.anivahealth.com/de/api/biomarkers/list-biomarkers.md) ab, um Anzeigedaten zu erhalten.

**Felder für Einzel-Biomarker**

**biomarker\_id** `integer`

Biomarker-Kennung – Abgleich über
[Biomarker auflisten](https://docs.anivahealth.com/de/api/biomarkers/list-biomarkers.md).

**added\_at** `string`

ISO-8601-Zeitstempel, zu dem der Biomarker erstmals mit diesem Termin verknüpft wurde.

**shipments** `AppointmentShipmentLink[]` *required*

Mit diesem Termin verknüpfte Sendungen, älteste Verknüpfung zuerst. Bei neu erstellten Terminen
leer – verknüpfe sie über [Sendung erstellen](https://docs.anivahealth.com/de/api/shipments/create-shipment.md) (mit
`appointment_id`) oder [Termine einer Sendung
zuordnen](https://docs.anivahealth.com/de/api/shipments/attach-appointments-to-shipment.md).

**Felder der Sendungsverknüpfung**

**id** `string`

Referenzkennung der Sendung – Abgleich über
[Sendung abrufen](https://docs.anivahealth.com/de/api/shipments/get-shipment.md).

**added\_at** `string`

ISO-8601-Zeitstempel, zu dem die Sendung erstmals mit diesem Termin verknüpft wurde.

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

Laborcodes (Röhrchen-Barcodes), die für diesen Termin erfasst wurden, in Scan-Reihenfolge. Leer, bis die Blutabnahme
bestätigt wird. Eine venöse Blutabnahme hat einen Code, der auf jedem Röhrchen steht; eine kapillare Blutabnahme hat einen
Code pro Microtainer. Ergebnisse und Dokumente unter [Ergebnisse abrufen](https://docs.anivahealth.com/de/api/appointments/get-results.md) verweisen
über `lab_code` auf diese Codes.

## Mindestvorlaufzeit

Termine an von Aniva betriebenen Standorten müssen mindestens **12 Stunden** im Voraus gebucht
werden; eine Buchung innerhalb dieses Zeitfensters gibt `400` zurück. [Verfügbarkeit
abrufen](https://docs.anivahealth.com/de/api/locations/get-availability.md) blendet diese Slots bereits aus, daher ist alles, was du
aus diesem Raster liest, buchbar.

Standorte, die du selbst betreibst, haben keine Mindestvorlaufzeit – Buchungen am selben Tag und Walk-ins bleiben unverändert.

## Doppelte Termine

Ein Profil kann pro Standort und Zeitpunkt höchstens einen nicht stornierten Termin haben – bei
einer Person kann nicht zweimal gleichzeitig am selben Ort Blut abgenommen werden, egal wie viele
Stühle der Standort hat.

Wenn du einen Termin für einen Slot erstellst, den das Profil bereits belegt, kommt `409` mit einer
`appointment_id` zurück, die den bereits bestehenden Termin nennt:

```json theme={null}
{
  "error": "This profile already has an appointment at this location and time. Reschedule or cancel the existing appointment instead of creating a second one.",
  "appointment_id": "03e916d2-7fd6-4414-8276-8532a105edc3"
}
```

Behandle die Anfrage in dem Fall als bereits ausgeführt: Ruf den Termin mit [Termin
abrufen](https://docs.anivahealth.com/de/api/appointments/get-appointment.md) ab, verschiebe ihn mit [Termin
aktualisieren](https://docs.anivahealth.com/de/api/appointments/update-appointment.md) oder storniere ihn mit [Termin
stornieren](https://docs.anivahealth.com/de/api/appointments/cancel-appointment.md). Wiederhole das Erstellen nicht – es gibt weiter
`409` zurück.

Das macht wiederholtes Erstellen sicher: Eine Anfrage, die du nach einem Timeout erneut sendest,
oder ein doppelt abgeschicktes Formular kann nicht zwei Termine zur selben Zeit für denselben
Patienten erzeugen.

> [!NOTE]
>
> `appointment_id` ist nur beim `409` wegen eines doppelten Termins enthalten. Das `409` wegen
> fehlender Kapazität – der Slot ist voll, weil *andere* Patienten ihn belegen – gibt nur `error`
> zurück; die richtige Lösung ist dann, einen anderen Slot aus [Verfügbarkeit
> abrufen](https://docs.anivahealth.com/de/api/locations/get-availability.md) zu wählen.

## Fehlerantworten

| Status | Beschreibung |
| - | - |
| `400` | Validierungsfehler – z. B. liegt `scheduled_at` in der Vergangenheit, an einem von Aniva betriebenen Standort weniger als 12 Stunden in der Zukunft oder nicht genau auf dem Beginn eines Zeitfensters im Raster des Standorts, oder der Standort führt keine Behälter für `draw_method`. |
| `403` | Zugriff verweigert – dein API-Schlüssel ist für diesen Vorgang nicht berechtigt, oder `results_ready_emails` ist ohne `results_view`-Zugriff auf den Patienten gesetzt. |
| `404` | Profil oder Standort nicht gefunden, oder der Standort ist inaktiv. |
| `409` | Dieses Profil hat bereits einen Termin an diesem Standort zu dieser Zeit (enthält `appointment_id`), das Zeitfenster ist ausgebucht, der Standort ist an diesem Datum geschlossen, oder der `Idempotency-Key` wurde mit einem anderen Body wiederverwendet oder seine ursprüngliche Anfrage ist noch nicht abgeschlossen. |
| `500` | Interner Serverfehler. |

```bash cURL theme={null}
curl --request POST \
  --url https://anivahealth.com/api/v1/appointments \
  --header 'x-api-key: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "profile_id": "a3f1c2d4-8b7e-4f2a-9c1d-2e3f4a5b6c7d",
    "location_id": "b7e2d1f5-3c4a-4e8b-a2f1-9d0c1e2f3a4b",
    "scheduled_at": "2026-05-15T10:30:00Z"
  }'
```

```json 201 theme={null}
{
  "id": "c9f3e2a1-7d6b-4c5e-b3a2-1f0e9d8c7b6a",
  "profile_id": "a3f1c2d4-8b7e-4f2a-9c1d-2e3f4a5b6c7d",
  "location_id": "b7e2d1f5-3c4a-4e8b-a2f1-9d0c1e2f3a4b",
  "scheduled_at": "2026-05-15T10:30:00Z",
  "status": "confirmed",
  "cancellation_reason": null,
  "results_ready_emails": [],
  "draw_method": "venous",
  "created_at": "2026-04-01T09:45:00Z",
  "updated_at": null,
  "profile": {
    "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": null
  },
  "panels": [],
  "individual_biomarkers": [],
  "shipments": [],
  "lab_codes": []
}
```

```json 400 theme={null}
{
  "error": "Appointments must be booked at least 12 hours in advance. Please pick a later time."
}
```

```json 404 theme={null}
{
  "error": "Location not found or inactive"
}
```

```json 409 theme={null}
{
  "error": "This profile already has an appointment at this location and time. Reschedule or cancel the existing appointment instead of creating a second one.",
  "appointment_id": "03e916d2-7fd6-4414-8276-8532a105edc3"
}
```


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