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

# Thuistestkit-bestelling aanmaken

> Een thuistestkit per post aanvragen voor een profiel

Vraag een thuistestkitbestelling aan voor een patiëntprofiel. Een thuistestkitbestelling verzendt een doe-het-zelftestkit per post — Aniva stuurt de kit naar het bezorgadres, de patiënt neemt thuis zelf een monster af en stuurt het per post terug. Dit verschilt van een [afspraak](https://docs.anivahealth.com/nl/api/appointments/create-appointment.md), wat een veneuze bloedafname op een testlocatie is.

**Er is precies één panel vereist.** Een thuistestkit komt 1:1 overeen met een fysiek kitproduct — het panel is de kit — en de bestelling komt direct na het aanmaken in de inpakwachtrij, dus de samenstelling moet vooraf definitief zijn. Je kunt het panel nog wijzigen via [Thuistestkitbestelling bijwerken](https://docs.anivahealth.com/nl/api/home-kit-orders/update-home-kit.md) zolang de bestelling `pending` is.

## Vervangende kits

Als een kit geen resultaten kan opleveren — de patiënt kon het buisje niet vullen, het monster kwam met te weinig materiaal aan, het laboratorium kon het niet analyseren — bestel dan een **vervanging** door `replaces_home_kit_order_id` mee te sturen.

Een vervanging is een nieuwe bestelling met een nieuwe labcode, ook als de eerste kit nooit is geactiveerd: het laboratorium heeft een nieuwe aanvraag nodig, en twee monsters onder één code zijn niet uit elkaar te houden. De bestelling die je vervangt blijft ongewijzigd — die behoudt zijn eigen status, zijn eigen labcode en alle resultaten die er al onder zijn vastgelegd.

Daaruit volgen twee dingen:

* **Het panel wordt overgenomen.** Laat `panel_id` weg en de vervanging krijgt het panel van de bestelling die wordt vervangen, wat de patiënt heeft gekocht en hoe de doos is bedrukt.
* **Je kiest wat opnieuw wordt getest.** Stuur `biomarker_ids` mee met de markers die zijn mislukt en het laboratorium test alleen die opnieuw, zodat de kit alleen de benodigde buisjes bevat. Laat dit weg om het hele panel opnieuw te testen.

Markers worden opnieuw getest in de groepen van het panel, niet één voor één. Als je één marker uit een groep opgeeft, wordt die hele groep opnieuw getest, omdat een laboratoriumaanvraag die meer rapporteert dan gevraagd niet kan worden geplaatst. Een vervanging voor één marker kan daarom meer dan één resultaat opleveren, en het aantal buisjes kan groter zijn dan de markerlijst doet vermoeden.

Er mag maar één vervanging per kit tegelijk onderweg zijn.

> [!NOTE]
>
> Als je hebt geïntegreerd voordat deze velden bestonden, leest Aniva ook `metadata.original_kit_id` en
> `metadata.replacement_reason` bij het aanmaken en behandelt de bestelling als een vervanging. Dit is de enige
> plek waar metadata wordt geïnterpreteerd, het bestaat alleen om die eerdere integratie te ondersteunen, en de velden
> hierboven hebben altijd voorrang. Stuur de velden mee.

Een `201` betekent dat de bestelling is vastgelegd en wordt overgedragen aan fulfilment — je hoeft niets anders meer te doen om de kit te laten inpakken en verzenden.

Vereist de scope `home_kit_orders_manage`.

Stuur een optionele `Idempotency-Key`-header mee om het aanmaken veilig opnieuw te kunnen proberen — bij herhaling van dezelfde sleutel krijg je de oorspronkelijke respons terug in plaats van een tweede aan te maken. Zie [Idempotentie](https://docs.anivahealth.com/nl/concepts/idempotency.md).

## Verzoek

### Bodyparameters

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

UUID van het patiëntprofiel waarvoor de thuistestkitbestelling wordt aangemaakt.

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

UUID van het cataloguspanel om te bestellen. Precies één — een thuistestkit komt 1:1 overeen met een fysiek kitproduct,
dus het panel is de kit. Panel-ID's worden door Aniva verstrekt voor je partneraccount; zie [Panels
weergeven](https://docs.anivahealth.com/nl/api/panels/list-panels.md). Optioneel bij een vervanging, waarbij standaard het panel wordt gebruikt van de
bestelling die je vervangt.

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

UUID van de thuistestkitbestelling die deze vervangt. Door dit mee te sturen wordt dit een vervangende kit — zie
[Vervangende kits](#vervangende-kits) hierboven. De bestelling moet bij hetzelfde profiel horen en mag
nog geen vervanging onderweg hebben.

**replacement\_reason** `string`

Waarom de vervanging nodig is, in één zin (bijvoorbeeld `Zu wenig Material, HbA1c nicht
    auswertbar`). Vereist wanneer je `replaces_home_kit_order_id` meestuurt, en wordt anders genegeerd. Maximaal
500 tekens.

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

Bij een vervanging de markers die het laboratorium opnieuw test — meestal de markers die de eerste kit niet kon
opleveren. Elke marker moet deel uitmaken van wat de bestelling die je vervangt heeft aangevraagd; controleer dit met [Biomarkers
weergeven](https://docs.anivahealth.com/nl/api/biomarkers/list-biomarkers.md) met `home_kit=true`. Laat dit weg om het hele panel opnieuw te testen. Alleen
geaccepteerd samen met `replaces_home_kit_order_id`, en niet samen met een andere `panel_id`.
Hiervoor is geen extra scope nodig: markers opnieuw testen waar de patiënt al voor heeft betaald is geen à-la-carteselectie.

**metadata** `object`

Je eigen key/value-paren, die bij elke leesactie letterlijk worden teruggegeven en nooit door Aniva worden geïnterpreteerd. Gebruik
dit om je eigen bestelreferentie mee te geven zodat je gegevens kunt koppelen zonder onze ID's op te slaan. Maximaal 20 keys;
keys voldoen aan `[A-Za-z0-9_-]` en zijn maximaal 40 tekens lang; waarden zijn een string, getal of boolean,
waarbij strings maximaal 500 tekens lang zijn; 16.384 bytes geserialiseerd in totaal. Keys die beginnen met `aniva_` zijn
gereserveerd. Zet nooit persoonlijke of klinische gegevens in `metadata` — dit wordt niet als patiëntgegevens behandeld.

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

Maximaal 5 adressen die elk één e-mail krijgen zodra alle labresultaten definitief zijn. De e-mail
linkt naar de resultatenpagina in het Aniva-adminpanel. Je sleutel heeft `results_view`-toegang tot
de patiënt nodig, anders volgt `403`. Laat dit veld weg om de standaardadressen van de groep van de
patiënt te gebruiken. Een lege lijst zet de e-mails uit. Zie [E-mails wanneer resultaten
klaarstaan](https://docs.anivahealth.com/nl/concepts/results.md#e-mails-zodra-resultaten-klaarstaan).

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

Het adres waarnaar de kit wordt verzonden — in een van twee vormen: ofwel `{ location_id }` dat verwijst naar een bekende testlocatie, ofwel de inline adresvelden (`name`, `street`, `city`, `postal_code`, `country_code`; `company_name` / `house_number` / `address_line_2` / `state` / `phone` / `email` optioneel — dezelfde terminologie als de locations-API). Geef er precies één op — een locatieverwijzing of een inline adres, niet beide.

**bezorgadres**

> [tab] Verwijzen naar een locatie
>
> **location\_id** `string` *required*
>
> UUID van een bekende testlocatie waarnaar de kit wordt verzonden. Koppel met [Locaties
> weergeven](https://docs.anivahealth.com/nl/api/locations/list-locations.md).

> [tab] Inline adres
>
> **name** `string` *required*
>
> Naam van ontvanger, bedrijf of locatie.
>
> **company\_name** `string`
>
> Bedrijf dat het pakket voor de ontvanger in ontvangst neemt — een `c/o`-partij of een afdeling.
>
> **street** `string` *required*
>
> Straatnaam, zonder huisnummer (bijv. `Wilhelmstraße`).
>
> **house\_number** `string`
>
> Huisnummer (bijv. `118` of `12a`).
>
> **address\_line\_2** `string`
>
> Gebouw, ingang of verdieping.
>
> **city** `string` *required*
>
> **state** `string`
>
> Deelstaat of provincie. Optioneel.
>
> **postal\_code** `string` *required*
>
> Postcode. Een Duits adres (`country_code` `DE`) vereist precies 5 cijfers, bijv. `10117`.
>
> **country\_code** `string` *required*
>
> ISO 3166-1 alpha-2-code (twee letters, bijv. `DE`). Kleine letters worden geaccepteerd en opgeslagen als
> hoofdletters.
>
> **phone** `string`
>
> Telefoonnummer van de ontvanger, met landcode (bijv. `+4791234567`). De vervoerder gebruikt het om
> de ontvanger over het pakket te informeren, bijvoorbeeld dat het klaarligt bij een afhaalpunt. Laat
> je het weg, dan krijgt de vervoerder geen telefoonnummer.
>
> **email** `string`
>
> E-mailadres van de ontvanger. De vervoerder gebruikt het net als `phone`. Laat je het weg, dan krijgt de vervoerder geen
> e-mailadres.

> [!NOTE]
>
> **Packstation of Postfiliale (alleen Duitsland):** stel `street` in op `Packstation` of `Postfiliale`,
> `house_number` op het driecijferige stationsnummer en `address_line_2` op het
> DHL-Postnummer van de ontvanger (6–10 cijfers, spaties toegestaan). Zonder het Postnummer kan het pakket niet worden geboekt.
> Een Postfach wordt niet ondersteund.

## Respons

Bij succes retourneert de API `201 Created` met de nieuwe thuistestkitbestelling.

**id** `string` *required*

Unieke identifier (UUID) van de thuistestkitbestelling.

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

UUID van het profiel waarbij deze thuistestkitbestelling hoort.

**status** `string` *required*

Huidige status van de thuistestkitbestelling. Een van `pending`, `dispatched`, `activated` of `cancelled`. Een
nieuw aangemaakte bestelling start in `pending`.

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

Het adres waar de kit naartoe wordt gestuurd — in een van twee vormen: ofwel `{ location_id }` dat verwijst naar een bekende testlocatie, ofwel de inline adresvelden (`name`, `street`, `city`, `postal_code`, `country_code`; `company_name` / `house_number` / `address_line_2` / `state` / `phone` / `email` optioneel — dezelfde velden als de locations-API). Geef precies één vorm op — een locatieverwijzing of een inline adres, niet beide.

**bezorgadres**

> [tab] Locatieverwijzing
>
> **location\_id** `string` *required*
>
> UUID van de testlocatie waar de kit naartoe wordt verzonden.

> [tab] Inline adres
>
> **name** `string` *required*
>
> Naam van ontvanger, bedrijf of locatie.
>
> **company\_name** `string`
>
> Bedrijf dat het pakket voor de ontvanger in ontvangst neemt — een `c/o`-partij of een afdeling.
>
> **street** `string` *required*
>
> Straatnaam, zonder huisnummer (bijv. `Wilhelmstraße`).
>
> **house\_number** `string`
>
> Huisnummer (bijv. `118` of `12a`).
>
> **address\_line\_2** `string`
>
> Gebouw, ingang of verdieping.
>
> **city** `string` *required*
>
> **state** `string`
>
> Deelstaat of provincie. Optioneel.
>
> **postal\_code** `string` *required*
>
> **country\_code** `string` *required*
>
> ISO 3166-1 alpha-2-code (twee letters, bijv. `DE`).
>
> **phone** `string`
>
> **email** `string`

**metadata** `object` *required*

De key/value-paren die je hebt meegegeven. Altijd aanwezig — `{}` als je er geen hebt ingesteld.

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

De thuistestkitbestelling die deze vervangt. `null` bij een normale bestelling.

**replacement\_reason** `string`

De reden die je hebt opgegeven. `null` bij een normale bestelling.

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

E-mailadressen die elk één e-mail krijgen zodra alle labresultaten definitief zijn, in kleine letters. Leeg wanneer uitgeschakeld. Zie
[E-mails bij beschikbare resultaten](https://docs.anivahealth.com/nl/concepts/results.md#e-mails-zodra-resultaten-klaarstaan).

**lab\_code** `string`

Monstercode van het laboratorium waaronder de resultaten worden gerapporteerd — afgedrukt op de fysieke kit, en wat de
patiënt van de doos afleest als activeringscode. `null` totdat de kit is verpakt.
Alleen-lezen.

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

Tijdstip van afname gemeld via [Activeren](https://docs.anivahealth.com/nl/api/home-kit-orders/activate-home-kit.md). `null` totdat
de kit is geactiveerd.

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

ISO 8601-tijdstempel waarop de thuistestkitbestelling is aangemaakt.

**updated\_at** `string`

ISO 8601-tijdstempel van de laatste update. Kan `null` zijn.

**profile** `object` *required*

Het patiëntprofiel dat bij deze thuistestkitbestelling hoort.

**profiel**

**id** `string`

Unieke profiel-identifier (UUID).

**handle** `string`

Profielhandle of gebruikersnaam. Kan `null` zijn.

**first\_name** `string`

Voornaam. Kan `null` zijn.

**last\_name** `string`

Achternaam. Kan `null` zijn.

**email** `string`

E-mailadres. Kan `null` zijn.

**phone** `string`

Telefoonnummer in E.164-formaat. Kan `null` zijn.

**sex** `integer`

Biologisch geslacht volgens ISO/IEC 5218. Kan `null` zijn.

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

Geboortedatum in `YYYY-MM-DD`-formaat. Kan `null` zijn.

**height** `number`

Lengte in centimeters. Kan `null` zijn.

**weight** `number`

Gewicht in kilogrammen. Kan `null` zijn.

**language** `string`

Voorkeurstaal: een van de 32 codes in [Profiel aanmaken](https://docs.anivahealth.com/nl/api/profiles/create-profile.md).

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

Of dit profiel transactionele (programmatische) e-mails ontvangt. Kan `null` zijn.

**created\_at** `string`

ISO 8601-tijdstempel van wanneer het profiel is aangemaakt.

**updated\_at** `string`

ISO 8601-tijdstempel van de laatste profielupdate. Kan `null` zijn.

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

Het panel dat aan deze thuistestkitbestelling is gekoppeld — het panel dat je als `panel_id` hebt opgegeven, voorzien van het
aanmaaktijdstip van de bestelling. Altijd precies één. Zoek panelgegevens (naam, biomarkers) op via
[Panels weergeven](https://docs.anivahealth.com/nl/api/panels/list-panels.md).

**Velden voor panelkoppeling**

**panel\_id** `string`

Panel-UUID — op te zoeken via [Panels ophalen](https://docs.anivahealth.com/nl/api/panels/list-panels.md).

**added\_at** `string`

ISO 8601-tijdstempel waarop het panel voor het eerst aan deze thuistestkitbestelling is gekoppeld.

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

Biomarkers die buiten het panel zijn toegevoegd. Leeg bij normaal aanmaken — thuistestkitbestellingen worden per
panel besteld, en om deze lijst achteraf te wijzigen is de
capability-scope `home_kit_orders_individual_biomarker_selection` vereist. Bij een vervanging bevat dit de
`biomarker_ids` die je hebt meegestuurd, die het laboratorium opnieuw test.

**Velden voor losse biomarkers**

**biomarker\_id** `integer`

Biomarker-identifier — op te zoeken via
[Biomarkers ophalen](https://docs.anivahealth.com/nl/api/biomarkers/list-biomarkers.md) met `home_kit=true`.

**added\_at** `string`

ISO 8601-tijdstempel waarop de biomarker voor het eerst aan deze thuistestkitbestelling is gekoppeld.

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

Pakketten die aan deze thuistestkitbestelling zijn gekoppeld, met de oudste koppeling eerst. Altijd leeg bij aanmaken — lees de
volledige pakketten uit met [Zendingen weergeven](https://docs.anivahealth.com/nl/api/shipments/list-shipments.md) en `?home_kit_order_id=`.

**Velden voor zendingskoppeling**

**id** `string`

Zendingsreferentie — op te zoeken via [Zending ophalen](https://docs.anivahealth.com/nl/api/shipments/get-shipment.md).

**added\_at** `string`

ISO 8601-tijdstempel waarop de zending aan deze thuistestkitbestelling is gekoppeld.

## Foutresponsen

| Status | Beschrijving |
| - | - |
| `400` | Validatiefout — bijv. in `delivery_address` ontbreekt een veld of staat een Duitse postcode die niet uit 5 cijfers bestaat, `panel_id` is geen geldige UUID, of `replacement_reason` ontbreekt bij een vervanging. |
| `403` | Niet toegestaan — je API-key heeft geen toegang tot deze bewerking, het profiel valt buiten je machtigingsscope, of je hebt `results_ready_emails` ingesteld zonder `results_view`-toegang tot de patiënt. |
| `404` | Profiel, panel of de te vervangen thuistestkitbestelling niet gevonden. |
| `409` | Conflict — de `Idempotency-Key` is al gebruikt met een andere body, het oorspronkelijke verzoek is nog niet afgerond, of de kit die je vervangt heeft al een vervanging onderweg. |
| `422` | Het panel kan niet als thuistestkit worden besteld — er is geen fulfilment-kitproduct voor geconfigureerd. Bij een vervanging: de bestelling die je vervangt hoort bij een ander profiel, een item in `biomarker_ids` maakt geen deel uit van wat is aangevraagd, of je hebt markers meegestuurd samen met een andere `panel_id`. |
| `500` | Interne serverfout. |

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