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

# Heimtest-Kit-Bestellung erstellen

> Ein Versand-Heimtest-Kit zum Selbsttesten für ein Profil anfordern

Fordere eine Heimtest-Kit-Bestellung für ein Patientenprofil an. Mit einer Heimtest-Kit-Bestellung wird ein Test-Kit für zu Hause per Post verschickt – Aniva schickt das Kit an die Lieferadresse, der Patient nimmt zu Hause selbst eine Probe und schickt sie per Post zurück. Das unterscheidet sich von einem [Termin](https://docs.anivahealth.com/de/api/appointments/create-appointment.md), bei dem eine venöse Blutabnahme an einem Teststandort stattfindet.

**Es ist genau ein Panel erforderlich.** Ein Heimtest-Kit entspricht 1:1 einem physischen Kit-Produkt – das Panel ist das Kit – und die Bestellung geht direkt nach der Erstellung in die Packwarteschlange, daher muss die Zusammensetzung von Anfang an feststehen. Solange die Bestellung `pending` ist, kannst du das Panel noch über [Heimtest-Kit-Bestellung aktualisieren](https://docs.anivahealth.com/de/api/home-kit-orders/update-home-kit.md) wechseln.

## Ersatz-Kits

Wenn ein Kit keine Ergebnisse liefern kann – der Patient konnte das Röhrchen nicht füllen, die Probe kam mit zu wenig Material an, das Labor konnte sie nicht analysieren –, bestelle **Ersatz**, indem du `replaces_home_kit_order_id` sendest.

Ein Ersatz ist eine neue Bestellung mit einem neuen Laborcode, auch wenn das erste Kit nie aktiviert wurde: Das Labor braucht einen neuen Auftrag, und zwei Proben unter demselben Code lassen sich nicht auseinanderhalten. Die Bestellung, die du ersetzt, bleibt unberührt – sie behält ihren eigenen Status, ihren eigenen Laborcode und alle Ergebnisse, die bereits darunter erfasst wurden.

Daraus ergeben sich zwei Dinge:

* **Das Panel wird übernommen.** Lässt du `panel_id` weg, übernimmt der Ersatz das Panel der ersetzten Bestellung – genau das, was der Patient gekauft hat und welches Branding die Box trägt.
* **Du wählst aus, was erneut analysiert wird.** Sende `biomarker_ids` mit den fehlgeschlagenen Markern, und das Labor analysiert nur diese erneut, sodass das Kit nur die dafür nötigen Röhrchen enthält. Lass es weg, um das gesamte Panel erneut zu analysieren.

Marker werden als Gruppen des Panels erneut analysiert, nicht einzeln. Wenn du einen Marker einer Gruppe angibst, wird diese gesamte Gruppe erneut analysiert, weil kein Laborauftrag erstellt werden kann, der mehr meldet als angefordert wurde. Ein Ersatz für einen einzelnen Marker kann daher mit mehr als einem Ergebnis eintreffen, und die Anzahl der Röhrchen kann größer sein, als die Markerliste vermuten lässt.

Pro Kit darf immer nur ein Ersatz gleichzeitig unterwegs sein.

> [!NOTE]
>
> Wenn du vor der Einführung dieser Felder integriert hast, liest Aniva beim Erstellen auch
> `metadata.original_kit_id` und `metadata.replacement_reason` aus und behandelt die Bestellung als
> Ersatz. Das ist die einzige Stelle, an der Metadaten interpretiert werden, sie dient nur der
> Unterstützung dieser früheren Integration, und die Felder oben haben immer Vorrang. Sende die
> Felder.

Ein `201` bedeutet, dass die Bestellung verbindlich angelegt ist und ans Fulfillment übergeben wird – du musst nichts weiter tun, damit das Kit gepackt und verschickt wird.

Erfordert den Scope `home_kit_orders_manage`.

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

## Anfrage

### Body-Parameter

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

UUID des Patientenprofils, für das die Heimtest-Kit-Bestellung erstellt wird.

**panel\_id** `string` *required*

UUID des Katalog-Panels, das bestellt werden soll. Genau eines – ein Heimtest-Kit entspricht 1:1
einem physischen Kit-Produkt, das Panel ist also das Kit. Panel-IDs werden von Aniva für dein
Partnerkonto bereitgestellt; siehe [Panels auflisten](https://docs.anivahealth.com/de/api/panels/list-panels.md). Bei einem Ersatz
optional; dort wird standardmäßig das Panel der ersetzten Bestellung verwendet.

**replaces\_home\_kit\_order\_id** `string`

UUID der Heimtest-Kit-Bestellung, die diese ersetzt. Wenn du sie sendest, wird daraus ein
Ersatz-Kit – siehe [Ersatz-Kits](#ersatz-kits) oben. Die Bestellung muss zum selben Profil
gehören, und für sie darf nicht bereits ein Ersatz unterwegs sein.

**replacement\_reason** `string`

Warum der Ersatz nötig ist, in einem Satz (zum Beispiel `Zu wenig Material, HbA1c nicht
    auswertbar`). Erforderlich, wenn du `replaces_home_kit_order_id` sendest, sonst ignoriert.
Höchstens 500 Zeichen.

**biomarker\_ids** `integer[]`

Bei einem Ersatz die Marker, die das Labor erneut analysiert – normalerweise die, die das erste
Kit nicht liefern konnte. Jeder muss Teil dessen sein, was die ersetzte Bestellung angefordert
hat; gleiche sie über [Biomarker auflisten](https://docs.anivahealth.com/de/api/biomarkers/list-biomarkers.md) mit `home_kit=true`
ab. Lass es weg, um das gesamte Panel erneut zu analysieren. Wird nur zusammen mit
`replaces_home_kit_order_id` akzeptiert und nicht zusammen mit einer anderen `panel_id`. Dafür
ist kein zusätzlicher Scope nötig: Marker erneut zu analysieren, die der Patient bereits bezahlt
hat, ist keine À-la-carte-Auswahl.

**metadata** `object`

Deine eigenen Schlüssel-Wert-Paare, die bei jedem Lesezugriff unverändert zurückgegeben und von
Aniva nie interpretiert werden. Nutze das Feld für deine Bestellreferenz, damit du Bestellungen
zuordnen kannst, ohne unsere IDs zu speichern. Höchstens 20 Schlüssel; Schlüssel entsprechen
`[A-Za-z0-9_-]` und sind höchstens 40 Zeichen lang; Werte sind ein String, eine Zahl oder ein
Boolean, wobei Strings höchstens 500 Zeichen lang sind; insgesamt 16.384 Bytes serialisiert.
Schlüssel, die mit `aniva_` beginnen, sind reserviert. Speichere niemals personenbezogene oder
klinische Daten in `metadata` – das Feld wird nicht wie Patientendaten behandelt.

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

**delivery\_address** `object` *required*

Die Adresse, an die das Kit geschickt wird – in einer von zwei Formen: entweder `{ location_id }` als Verweis auf einen bekannten Teststandort oder die Inline-Adressfelder (`name`, `street`, `city`, `postal_code`, `country_code`; `company_name` / `house_number` / `address_line_2` / `state` / `phone` / `email` optional – dasselbe Vokabular wie in der Locations-API). Gib genau eine Variante an – eine Standortreferenz oder eine Inline-Adresse, nicht beides.

**Lieferadresse**

> [tab] Standort referenzieren
>
> **location\_id** `string` *required*
>
> UUID eines bekannten Teststandorts, an den das Kit geschickt wird. Gleiche sie mit
> [Standorte auflisten](https://docs.anivahealth.com/de/api/locations/list-locations.md) ab.

> [tab] Inline-Adresse
>
> **name** `string` *required*
>
> Empfänger-, Firmen- oder Standortname.
>
> **company\_name** `string`
>
> Unternehmen, das das Paket für den Empfänger annimmt – eine `c/o`-Angabe oder eine
> Abteilung.
>
> **street** `string` *required*
>
> Straßenname ohne Hausnummer (z. B. `Wilhelmstraße`).
>
> **house\_number** `string`
>
> Hausnummer (z. B. `118` oder `12a`).
>
> **address\_line\_2** `string`
>
> Gebäude, Eingang oder Etage.
>
> **city** `string` *required*
>
> **state** `string`
>
> Bundesland oder Provinz. Optional.
>
> **postal\_code** `string` *required*
>
> Postleitzahl. Eine deutsche Adresse (`country_code` `DE`) braucht genau 5 Ziffern, z. B.
> `10117`.
>
> **country\_code** `string` *required*
>
> Code nach ISO 3166-1 alpha-2 (zwei Buchstaben, z. B. `DE`). Kleinbuchstaben werden
> akzeptiert und in Großbuchstaben gespeichert.
>
> **phone** `string`
>
> Telefonnummer des Empfängers mit Ländervorwahl (z. B. `+4791234567`). Der
> Versanddienstleister nutzt sie, um den Empfänger über das Paket zu informieren, zum
> Beispiel wenn es in einer Abholstation wartet. Lässt du das Feld weg, erhält der
> Versanddienstleister keine Telefonnummer.
>
> **email** `string`
>
> E-Mail-Adresse des Empfängers. Der Versanddienstleister nutzt sie wie `phone`. Lässt du das
> Feld weg, erhält der Versanddienstleister keine E-Mail-Adresse.

> [!NOTE]
>
> **Packstation oder Postfiliale (nur Deutschland):** Setze `street` auf `Packstation` oder
> `Postfiliale`, `house_number` auf die dreistellige Stationsnummer und `address_line_2` auf die
> DHL-Postnummer des Empfängers (6–10 Ziffern, Leerzeichen erlaubt). Ohne die Postnummer kann das
> Paket nicht gebucht werden. Ein Postfach wird nicht unterstützt.

## Antwort

Bei Erfolg gibt die API `201 Created` mit der neuen Heimtest-Kit-Bestellung zurück.

**id** `string` *required*

Eindeutige Kennung (UUID) der Heimtest-Kit-Bestellung.

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

UUID des Profils, zu dem diese Heimtest-Kit-Bestellung gehört.

**status** `string` *required*

Aktueller Status der Heimtest-Kit-Bestellung. Einer der Werte `pending`, `dispatched`,
`activated` oder `cancelled`. Eine neu erstellte Bestellung startet im Status `pending`.

**delivery\_address** `object` *required*

Die Versandadresse für das Kit – in einer von zwei Formen: entweder `{ location_id }` als Verweis auf einen bekannten Teststandort oder die direkten Adressfelder (`name`, `street`, `city`, `postal_code`, `country_code`; `company_name` / `house_number` / `address_line_2` / `state` / `phone` / `email` optional – dieselben Felder wie in der Locations-API). Gib genau eine Variante an – eine Standortreferenz oder eine direkte Adresse, nicht beides.

**Lieferadresse**

> [tab] Standortreferenz
>
> **location\_id** `string` *required*
>
> UUID des Teststandorts, an den das Kit verschickt wird.

> [tab] Direkte Adresse
>
> **name** `string` *required*
>
> Name des Empfängers, des Unternehmens oder des Standorts.
>
> **company\_name** `string`
>
> Unternehmen, das das Paket für den Empfänger annimmt – ein `c/o`-Empfänger oder eine Abteilung.
>
> **street** `string` *required*
>
> Straßenname ohne Hausnummer (z. B. `Wilhelmstraße`).
>
> **house\_number** `string`
>
> Hausnummer (z. B. `118` oder `12a`).
>
> **address\_line\_2** `string`
>
> Gebäude, Eingang oder Etage.
>
> **city** `string` *required*
>
> **state** `string`
>
> Bundesland oder Provinz. Optional.
>
> **postal\_code** `string` *required*
>
> **country\_code** `string` *required*
>
> Code nach ISO 3166-1 alpha-2 (zwei Buchstaben, z. B. `DE`).
>
> **phone** `string`
>
> **email** `string`

**metadata** `object` *required*

Die Schlüssel-Wert-Paare, die du angegeben hast. Immer vorhanden – `{}`, wenn du keine gesetzt
hast.

**replaces\_home\_kit\_order\_id** `string`

Die Heimtest-Kit-Bestellung, die diese ersetzt. Bei einer normalen Bestellung `null`.

**replacement\_reason** `string`

Der Grund, den du angegeben hast. Bei einer normalen Bestellung `null`.

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

**lab\_code** `string`

Labor-Probencode, unter dem die Ergebnisse gemeldet werden – auf dem physischen Kit aufgedruckt und der
Aktivierungscode, den der Patient von der Box abliest. `null`, bis das Kit verpackt ist.
Schreibgeschützt.

**activated\_at** `string` *required*

Zeitpunkt der Probenahme, gemeldet über [Aktivieren](https://docs.anivahealth.com/de/api/home-kit-orders/activate-home-kit.md).
`null`, bis das Kit aktiviert wird.

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

ISO-8601-Zeitstempel, wann die Heimtest-Kit-Bestellung erstellt wurde.

**updated\_at** `string`

ISO-8601-Zeitstempel der letzten Aktualisierung. Kann `null` sein.

**profile** `object` *required*

Das Patientenprofil, das mit dieser Heimtest-Kit-Bestellung verknüpft ist.

**Profil**

**id** `string`

Eindeutige Profilkennung (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 (programmatische) E-Mails erhält. Kann `null` sein.

**created\_at** `string`

ISO-8601-Zeitstempel der Erstellung des Profils.

**updated\_at** `string`

ISO-8601-Zeitstempel der letzten Profilaktualisierung. Kann `null` sein.

**panels** `HomeKitOrderPanel[]` *required*

Das dieser Heimtest-Kit-Bestellung zugeordnete Panel – dasjenige, das du als `panel_id` angegeben
hast, versehen mit dem Erstellungszeitpunkt der Bestellung. Immer genau eines. Rufe Panel-Details
(Name, Biomarker) über [Panels auflisten](https://docs.anivahealth.com/de/api/panels/list-panels.md) ab.

**Felder der Panel-Zuordnung**

**panel\_id** `string`

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

**added\_at** `string`

ISO-8601-Zeitstempel, wann das Panel dieser Heimtest-Kit-Bestellung erstmals zugeordnet wurde.

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

Biomarker, die außerhalb des Panels hinzugefügt wurden. Bei einer normalen Erstellung leer –
Heimtest-Kit-Bestellungen werden nach Panel bestellt, und das nachträgliche Ändern dieser Liste
erfordert den Capability-Scope `home_kit_orders_individual_biomarker_selection`. Bei einem Ersatz
enthält das Feld die von dir gesendeten `biomarker_ids`, also die Marker, die das Labor erneut
analysiert.

**Felder einzelner Biomarker**

**biomarker\_id** `integer`

Biomarker-ID – zum Abgleich mit
[Biomarker auflisten](https://docs.anivahealth.com/de/api/biomarkers/list-biomarkers.md) mit `home_kit=true`.

**added\_at** `string`

ISO-8601-Zeitstempel, wann der Biomarker dieser Heimtest-Kit-Bestellung erstmals zugeordnet wurde.

**shipments** `HomeKitOrderShipmentLink[]` *required*

Pakete, die mit dieser Heimtest-Kit-Bestellung verknüpft sind, beginnend mit der ältesten
Verknüpfung. Bei der Erstellung immer leer – rufe die vollständigen Paketdaten über
[Sendungen auflisten](https://docs.anivahealth.com/de/api/shipments/list-shipments.md) mit `?home_kit_order_id=` ab.

**Felder der Sendungsverknüpfung**

**id** `string`

Sendungsreferenz – zum Abgleich mit [Sendung abrufen](https://docs.anivahealth.com/de/api/shipments/get-shipment.md).

**added\_at** `string`

ISO-8601-Zeitstempel, wann die Sendung mit dieser Heimtest-Kit-Bestellung verknüpft wurde.

## Fehlerantworten

| Status | Beschreibung |
| - | - |
| `400` | Validierungsfehler – z. B. fehlt ein Feld in `delivery_address` oder eine deutsche Postleitzahl hat nicht 5 Ziffern, `panel_id` ist keine gültige UUID oder `replacement_reason` fehlt bei einem Ersatz. |
| `403` | Zugriff verweigert – dein API-Key hat keinen Zugriff auf diese Operation, das Profil liegt außerhalb deines Berechtigungsbereichs oder du hast `results_ready_emails` ohne `results_view`-Zugriff auf den Patienten gesetzt. |
| `404` | Profil, Panel oder die zu ersetzende Heimtest-Kit-Bestellung nicht gefunden. |
| `409` | Konflikt – der `Idempotency-Key` wurde bereits mit einem anderen Body verwendet, die ursprüngliche Anfrage ist noch nicht abgeschlossen oder für das Kit, das du ersetzt, ist bereits ein Ersatz unterwegs. |
| `422` | Das Panel ist nicht als Heimtest-Kit bestellbar – dafür ist kein Fulfillment-Kit-Produkt konfiguriert. Bei einem Ersatz: Die ersetzte Bestellung gehört zu einem anderen Profil, ein Eintrag in `biomarker_ids` war nicht Teil der ursprünglichen Bestellung oder du hast Marker zusammen mit einer anderen `panel_id` gesendet. |
| `500` | Interner Serverfehler. |

```bash cURL theme={null}
curl --request POST \
  --url https://anivahealth.com/api/v1/home-kit-orders \
  --header 'x-api-key: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "profile_id": "a3f1c2d4-8b7e-4f2a-9c1d-2e3f4a5b6c7d",
    "panel_id": "f1c2d4a3-7b8e-4f2a-9c1d-2e3f4a5b6c7d",
    "metadata": { "your_order_ref": "ORD-10482", "priority": true },
    "delivery_address": {
      "name": "Maria Schmidt",
      "company_name": "c/o Weber",
      "street": "Friedrichstraße",
      "house_number": "123",
      "postal_code": "10117",
      "city": "Berlin",
      "country_code": "DE",
      "phone": "+4930123456789",
      "email": "maria.schmidt@example.com"
    }
  }'
```

```bash Replacement kit theme={null}
curl --request POST \
  --url https://anivahealth.com/api/v1/home-kit-orders \
  --header 'x-api-key: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "profile_id": "a3f1c2d4-8b7e-4f2a-9c1d-2e3f4a5b6c7d",
    "replaces_home_kit_order_id": "d1e2f3a4-5b6c-4d7e-8f9a-0b1c2d3e4f5a",
    "replacement_reason": "Too little material, HbA1c could not be analysed",
    "biomarker_ids": [103],
    "metadata": { "your_order_ref": "ORD-10482-R1" },
    "delivery_address": {
      "name": "Maria Schmidt",
      "street": "Friedrichstraße",
      "house_number": "123",
      "postal_code": "10117",
      "city": "Berlin",
      "country_code": "DE"
    }
  }'
```

```json 201 theme={null}
{
  "id": "d1e2f3a4-5b6c-4d7e-8f9a-0b1c2d3e4f5a",
  "profile_id": "a3f1c2d4-8b7e-4f2a-9c1d-2e3f4a5b6c7d",
  "status": "pending",
  "delivery_address": {
    "name": "Maria Schmidt",
    "company_name": "c/o Weber",
    "address_line_2": null,
    "street": "Friedrichstraße",
    "house_number": "123",
    "postal_code": "10117",
    "city": "Berlin",
    "country_code": "DE",
    "phone": "+4930123456789",
    "email": "maria.schmidt@example.com"
  },
  "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": [
    {
      "panel_id": "f1c2d4a3-7b8e-4f2a-9c1d-2e3f4a5b6c7d",
      "added_at": "2026-04-01T09:45:00Z"
    }
  ],
  "individual_biomarkers": [],
  "metadata": { "your_order_ref": "ORD-10482", "priority": true },
  "replaces_home_kit_order_id": null,
  "replacement_reason": null,
  "results_ready_emails": [],
  "lab_code": null,
  "activated_at": null,
  "shipments": []
}
```

```json 400 theme={null}
{
  "error": "panel_id: panel_id must be a valid UUID"
}
```

```json 404 theme={null}
{
  "error": "Profile not found"
}
```

```json 409 theme={null}
{
  "error": "Idempotency-Key \"ORD-10482\" was already used with a different request body. Use a new key for a different request, or resend the original body to read back its result."
}
```


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