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

# Afspraken

> Hoe afspraken voor bloedafname werken in de Aniva API voor labtests: boeken, panels, biomarkers, statuswijzigingen en annuleren.

Een afspraak is een geplande bloedafname voor een patiëntprofiel op een fysieke testlocatie, uitgevoerd door een zorgverlener. Kits die per post naar een patiënt worden gestuurd, zijn geen afspraken — zie [Bestellingen van thuistestkits](https://docs.anivahealth.com/nl/concepts/home-kit-orders.md).

## Velden

**id** `string` *required*

UUID die automatisch door Aniva wordt gegenereerd. Gebruik deze om panels toe te voegen, de bloedafname te bevestigen en resultaten op te halen.

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

De UUID van het profiel waarbij deze afspraak hoort.

**location\_id** `string`

De UUID van de testlocatie waar de bloedafname plaatsvindt. Thuistestkits zijn geen afspraken — zie
[Bestellingen van thuistestkits](https://docs.anivahealth.com/nl/concepts/home-kit-orders.md).

**scheduled\_at** `string`

Geplande datum en tijd van de bloedafname in ISO 8601-formaat. Wordt altijd teruggegeven als een UTC-tijdstip
met een `Z`-achtervoegsel (bijv. `2026-04-15T08:30:00Z`). Bij aanmaken / bijwerken **moet de waarde
een tijdzoneaanduiding bevatten** (`Z` of een expliciete offset zoals `+02:00`) — datum-tijdwaarden zonder tijdzone worden geweigerd.
Moet in de toekomst liggen, en bij locaties die door Aniva worden beheerd minstens 12 uur vooruit ([minimale
termijn](https://docs.anivahealth.com/nl/api/appointments/create-appointment.md#minimale-boekingstermijn)).

**status** `string` *required*

Huidige levenscyclusstatus. Een van `pending`, `confirmed`, `blood_drawn` of `cancelled`. Zie
[Levenscyclus](#levenscyclus) hieronder. De voortgang van labresultaten (`in_progress` vs. `completed`) haal
je op via [Resultaten ophalen](https://docs.anivahealth.com/nl/api/appointments/get-results.md); gedetailleerdere voortgang van zendingen (onderweg,
bezorgd, enz.) vind je door elk item in de inline `shipments`-array te volgen naar
[Zending ophalen](https://docs.anivahealth.com/nl/api/shipments/get-shipment.md).

**cancellation\_reason** `string`

Vrije tekst als reden die is vastgelegd bij het annuleren van de afspraak (bijv. no-show, late annulering,
'Mislukt. Herhaling vereist'). `null` tenzij `status` gelijk is aan `cancelled`.

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

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

Hoe het bloed wordt afgenomen: `capillary` (vingertop of bovenarm, in microtainers) of `venous` (uit de ader,
in buisjes). Dit is de methode die de afspraak instelt, anders de `default_draw_method` van de
[locatie](https://docs.anivahealth.com/nl/concepts/locations.md). Na de bloedafname is dit de methode die is gebruikt.

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

ISO 8601-tijdstempel van wanneer de afspraak is aangemaakt.

**updated\_at** `string`

ISO 8601-tijdstempel van de meest recente update. Null als de afspraak nog nooit is bijgewerkt.

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

Labcodes (buisbarcodes) die bij [Bloedafname bevestigen](https://docs.anivahealth.com/nl/api/appointments/confirm-blood-draw.md) zijn geregistreerd,
in scanvolgorde. Leeg totdat de bloedafname is bevestigd. Bij een veneuze bloedafname staat één code op elk
buisje; bij een capillaire bloedafname is er één code per microtainer. Resultaten en documenten verwijzen hiernaar via
`lab_code`.

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

Panels die aan deze afspraak zijn gekoppeld, als `{ panel_id, added_at }`-items. Zie
[Panels toevoegen](#panels-toevoegen).

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

Losse biomarkers die aan deze afspraak zijn gekoppeld, als `{ biomarker_id, added_at }`-items. Zie
[Individuele biomarkers](#individuele-biomarkers).

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

Zendingen die aan deze afspraak zijn gekoppeld, als `{ id, added_at }`-items, oudste koppeling eerst. Zie
[Zendingen koppelen](#zendingen-koppelen).

**profile** `object` *required*

Het volledige profielobject van de patiënt, opgenomen in elke afspraakrespons. De velden hieronder
zijn een selectie. [Afspraak ophalen](https://docs.anivahealth.com/nl/api/appointments/get-appointment.md) vermeldt ze allemaal.

**eigenschappen**

**id** `string`

UUID van het bijbehorende profiel.

**first\_name** `string`

Voornaam van de patiënt.

**last\_name** `string`

Achternaam van de patiënt.

**email** `string`

E-mailadres van de patiënt.

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

Geboortedatum in het formaat `YYYY-MM-DD`.

**sex** `integer`

Biologisch geslacht volgens ISO/IEC 5218.

## Levenscyclus

Afspraken hebben vier levenscyclusstatussen:

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

| Status | Betekenis |
| - | - |
| `pending` | De afspraak is gepland en wacht op bevestiging. Kan worden [bijgewerkt](https://docs.anivahealth.com/nl/api/appointments/update-appointment.md) of [geannuleerd](https://docs.anivahealth.com/nl/api/appointments/cancel-appointment.md). |
| `confirmed` | De planning is bevestigd (bijv. door de praktijk), maar er is nog geen bloed afgenomen. Kan nog worden bijgewerkt of geannuleerd. |
| `blood_drawn` | De labcodes zijn ingediend via [Bloedafname bevestigen](https://docs.anivahealth.com/nl/api/appointments/confirm-blood-draw.md) en de verwerking van de laborder is gestart. Panels zijn vergrendeld en de afspraak kan niet meer worden verzet of geannuleerd. |
| `cancelled` | De afspraak is geannuleerd. Eindstatus — geen verdere overgangen mogelijk. |

> [!NOTE]
>
> De afspraakstatus is bewust globaal gehouden — gedetailleerdere voortgang is beschikbaar
> via aparte endpoints:
>
> * **Voortgang van labresultaten** →
>   [Resultaten ophalen](https://docs.anivahealth.com/nl/api/appointments/get-results.md) — het `status`-veld op het hoogste niveau is `in_progress` of
>   `completed`.
> * **Voortgang van zendingen** (onderweg, bezorgd, enz.) → volg elk item in de inline
>   `shipments`-array bij de afspraak naar [Zending ophalen](https://docs.anivahealth.com/nl/api/shipments/get-shipment.md) — elke
>   zending heeft een eigen `status` en een `status_updates`-eventlog.
>
> Elke statuswijziging verstuurt een `appointment.*`-[webhook](https://docs.anivahealth.com/nl/concepts/webhooks.md), bijvoorbeeld
> `appointment.confirmed`. Een nieuwe tijd of locatie verstuurt `appointment.rescheduled`.

> [!WARNING]
>
> Het bevestigen van een afspraak (de overgang naar `blood_drawn`) is **onomkeerbaar**. Zodra je de
> labcode(s) indient, wordt de verwerking van de laborder gestart en kan dit niet meer ongedaan worden gemaakt. Wijzigingen en annuleringen
> zijn alleen mogelijk zolang de afspraak de status `pending` of `confirmed` heeft.

## Afspraken ophalen

Haal alle afspraken op waartoe je API-key toegang heeft:

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

Geef optioneel `?profile_id={uuid}` mee om op een specifiek profiel te filteren. Zonder deze parameter geldt een standaard tijdsbestek (de afgelopen 2 maanden tot 1 maand vooruit).

## Een afspraak bijwerken

Voordat de bloedafname is bevestigd, kun je de afspraak verzetten of de testlocatie wijzigen:

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

Geef een willekeurige combinatie van `scheduled_at`, `location_id`, `draw_method` en `results_ready_emails` mee om bij te werken. Neem alleen de velden op die je wilt wijzigen.

## Afnamemethode

Elke afspraak heeft een `draw_method`: `capillary` (vingertop of bovenarm, in microtainers) of
`venous` (uit de ader, in buisjes). Dit geldt alleen voor de bloedafname. Urine, uitstrijkjes en andere
monsters die geen bloed zijn, worden bij beide methoden op dezelfde manier afgenomen.

Standaard is dit de `default_draw_method` van de locatie. Stel `draw_method` in bij aanmaken of bijwerken om
een andere methode te gebruiken, of zet dit op `null` om terug te gaan naar de standaard van de locatie. De locatie moet
de methode in `draw_methods` vermelden en de geboekte tests moeten daarmee mogelijk zijn, anders geeft het verzoek
`400` terug. Na de bloedafname kun je dit niet meer wijzigen. Na de bloedafname is `draw_method` de
methode die is gebruikt.

## Eén afspraak per profiel, locatie en tijdstip

Een profiel kan hoogstens één niet-geannuleerde afspraak hebben per combinatie van `(location_id, scheduled_at)` — bij één
persoon kan niet twee keer tegelijk op dezelfde plek bloed worden afgenomen, ongeacht hoeveel parallelle boekingen de
locatie accepteert.

Zowel [Afspraak aanmaken](https://docs.anivahealth.com/nl/api/appointments/create-appointment.md) als
[Afspraak bijwerken](https://docs.anivahealth.com/nl/api/appointments/update-appointment.md) dwingen dit af en geven `409` terug met een
`appointment_id` dat verwijst naar de afspraak die al bestaat. Behandel die respons als al
geboekt in plaats van een fout die je opnieuw moet proberen: haal de genoemde afspraak op, verzet deze of annuleer deze.

In de praktijk betekent dit dat herhaald aanmaken veilig is. Een aanmaakverzoek dat je na een
netwerktime-out opnieuw verstuurt, of dat een gebruiker twee keer triggert, leidt tot één afspraak
in plaats van twee — wat ook betekent dat je achteraf nooit dubbele boekingen voor dezelfde patiënt
hoeft recht te zetten.

> [!NOTE]
>
> Wijzigingen zijn alleen toegestaan vóór de bloedafname — dus zolang de afspraak de status `pending`
> of `confirmed` heeft. Zodra de afspraak overgaat naar `blood_drawn` of `cancelled` is, kan deze
> niet meer worden aangepast. De enige uitzondering is `results_ready_emails`: dat kun je na de
> bloedafname nog wel als enige wijzigen.

## Een afspraak annuleren

Annuleer een afspraak die niet meer nodig is:

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

Hiermee zet je de afspraakstatus op `cancelled`. De geannuleerde afspraak wordt teruggegeven in de response.

Stuur optioneel een `cancellation_reason` (tot 500 tekens) mee in de body om de reden vast te
leggen. Deze wordt opgeslagen bij de afspraak en bij later opvragen teruggegeven als
`cancellation_reason`.

> [!NOTE]
>
> Annuleren is alleen toegestaan vóór de bloedafname — dus zolang de afspraak de status `pending` of
> `confirmed` heeft. Afspraken die al zijn overgegaan naar `blood_drawn` kunnen niet worden
> geannuleerd.

## Panels toevoegen

Voeg vóór het bevestigen van de bloedafname de bloedtestpanels toe die je wilt uitvoeren door dit aan te roepen:

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

Geef een array van panel-UUID's door in het veld `panel_ids`. Panel-ID's worden door Aniva geleverd voor je partneraccount.

> [!NOTE]
>
> Panels moeten vóór de bloedafname worden toegevoegd — dus zolang de afspraak de status `pending`
> of `confirmed` heeft. Zodra de afspraak is overgegaan naar `blood_drawn`, kun je geen panels meer
> toevoegen of wijzigen.

## Panels verwijderen

Als je vóór de bloedafname panels moet verwijderen, roep je dit aan:

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

Geef een array van panel-UUID's door in het veld `panel_ids`. Verwijderen is idempotent: een panel dat niet gekoppeld is, wordt genegeerd.

> [!NOTE]
>
> Net als toevoegen is verwijderen alleen toegestaan vóór de bloedafname — dus zolang de afspraak de
> status `pending` of `confirmed` heeft. Zodra de afspraak is overgegaan naar `blood_drawn`, kunnen
> panels niet meer worden verwijderd.

## Individuele biomarkers

Je kunt individuele biomarkers als à-la-cartetests aan een afspraak koppelen, buiten een vooraf samengesteld panel om. Dit is handig wanneer een behandelaar een selectie op maat wil in plaats van een vast pakket. De gekoppelde biomarkers verschijnen in de afspraakresponse als een `individual_biomarkers`-array (naast `panels`). Routeringsbeslissingen worden verderop in de order-logistiekpipeline genomen op basis van de koppelingen per laboratorium voor elke biomarker.

Biomarkers toevoegen (idempotent — al gekoppelde biomarkers blijven behouden):

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

Biomarkers verwijderen (idempotent — biomarkers die niet gekoppeld zijn, worden genegeerd):

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

Beide endpoints accepteren een `biomarker_ids`-array en valideren de uiteindelijke set tegen de volledigheidsregels van elk laboratorium — een bestelling die niet geldig geplaatst kan worden (bijv. een CRP/HDL-ratio zonder CRP en HDL) geeft `400` terug met de biomarkers die je moet toevoegen, en slaat niets op. Gebruik [Biomarkers weergeven](https://docs.anivahealth.com/nl/api/biomarkers/list-biomarkers.md) om biomarker-ID's op te zoeken.

> [!NOTE]
>
> Net als wijzigingen aan panels kunnen individuele biomarkers alleen vóór de bloedafname worden
> toegevoegd of verwijderd — dus zolang de afspraak de status `pending` of `confirmed` heeft. Zodra
> de afspraak overgaat naar `blood_drawn`, wordt de aangepaste snapshot bevroren.

## Voorbeeld van benodigde containers

Bekijk na het toevoegen van panels of individuele biomarkers welke fysieke afnamecontainers nodig zijn voor de monsterafname:

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

De array `containers` in de response bevat het type, de naam, de dopkleur, het volume, het artikelnummer van de fabrikant en het aantal voor elke benodigde container. Dit helpt behandelaars om de juiste materialen vóór de bloedafname klaar te zetten. De response bevat ook een `pricing`-object — de volledige rekening van de afspraak (de toegepaste posten, de gekoppelde panels en één rij per geleverde biomarker, geprijsd volgens je tariefkaart met de verkoopprijs ernaast; zie [Prijzen](https://docs.anivahealth.com/nl/concepts/pricing.md)), dat wordt gevuld wanneer de afspraak gekoppelde tests heeft en je sleutel de scope `prices_view` heeft, en anders `null` is. `routing` wordt bewust nooit teruggegeven en is altijd `null`.

> [!NOTE]
>
> Het voorbeeld geeft de momenteel gekoppelde panels en biomarkers weer. Als je na het bekijken
> panels toevoegt of verwijdert, roep het preview-endpoint dan opnieuw aan om de bijgewerkte
> benodigde containers op te halen.

## De bloedafname bevestigen

Stuur na de bloedafname de labcodes (buisbarcodes) in om de laborder-pipeline te starten:

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

Stuur `lab_code` wanneer op elk buisje één code is gedrukt (veneuze bloedafname), of `lab_codes` met
één item per code — elk met de bijbehorende `panel_ids` — wanneer elk panel in eigen buisjes met een
eigen code wordt afgenomen (capillaire bloedafname). Elk panel is dan een eigen laboratoriumaanvraag
onder de bijbehorende code. De codes worden als `lab_codes` teruggegeven op de afspraak.

Bij een capillaire bloedafname wordt de bloedafname verdeeld over microtainers. Panels gaan eerst,
in volgorde van boeking. Individuele biomarkers vullen daarna de vrije ruimte in de
panel-microtainers op. Als ze meer ruimte nodig hebben, openen ze nieuwe microtainers. We verdelen ze
gelijkmatig. Elke microtainer bevat maximaal 150 µl aan individuele biomarkers. De aanroepen waarmee
je panels of biomarkers wijzigt, geven `400` terug als de uiteindelijke set deze regel overtreedt.

Hiermee gaat de afspraakstatus over naar `blood_drawn` en start de verwerking in het laboratorium. Deze actie is onomkeerbaar.

## Afhalen van de zending

> [!WARNING]
>
> `POST /api/v1/appointments/pickup` is **verwijderd**, samen met de afspraakstatus
> `shipment_picked_up`. Het geeft nu `405 Method Not Allowed` terug, omdat het pad doorvalt naar de
> route voor afspraken op basis van ID. In de laatste fase was het endpoint een no-op die de aanroep
> accepteerde en niets deed, dus het verwijderen verandert geen gedrag waarop je vertrouwde.

Om de voortgang na de bloedafname te volgen, ga je voor elk item in de inline `shipments`-array van
de afspraak naar [Zending ophalen](https://docs.anivahealth.com/nl/api/shipments/get-shipment.md) — elke zending heeft een eigen
`status` en een `status_updates`-geschiedenis.

## Zendingen koppelen

Een afspraak kan aan een of meer zendingen worden gekoppeld (en andersom — de relatie is
veel-op-veel). De huidige gekoppelde items worden aan beide kanten inline getoond:

* op de afspraak als een `shipments`-array met `{ id, added_at }`-items;
* op de zending als een `appointments`-array met `{ id, added_at }`-items.

Beide arrays staan op volgorde van oudste koppeling eerst. Elke `id` verwijst naar het canonieke
detail-endpoint ([Zending ophalen](https://docs.anivahealth.com/nl/api/shipments/get-shipment.md) /
[Afspraak ophalen](https://docs.anivahealth.com/nl/api/appointments/get-appointment.md)) voor de volledige payload.

Zendingen worden bij het aanmaken gekoppeld via het veld `appointment_id` in
[Zending aanmaken](https://docs.anivahealth.com/nl/api/shipments/create-shipment.md). Na het aanmaken beheer je koppelingen vanaf de
zending met [Afspraken aan zending koppelen](https://docs.anivahealth.com/nl/api/shipments/attach-appointments-to-shipment.md) en
[Afspraken van zending loskoppelen](https://docs.anivahealth.com/nl/api/shipments/detach-appointments-from-shipment.md); beide geven
de bijgewerkte afsprakenlijst voor die zending terug. Om alle pakketten van een afspraak volledig
te bekijken, gebruik je [Zendingen weergeven](https://docs.anivahealth.com/nl/api/shipments/list-shipments.md) met `?appointment_id=`.

De wijzigingsregel is: koppelingen kunnen worden aangemaakt of verwijderd wanneer OFWEL

* de afspraak voorbij de bloedafname is (`blood_drawn`), of
* de zending minder dan 24 uur geleden is aangemaakt.

Buiten dat tijdsvenster is de koppeling vergrendeld, zodat historische gegevens stabiel blijven.

## Labresultaten ophalen

Zodra het lab de bloedmonsters heeft verwerkt, haal je de klinische en genetische resultaten op:

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

De response bevat geplande tests (status `planned`) naast ontvangen resultaten, zodat je kunt
volgen wat nog openstaat. Het veld `status` op het hoogste niveau is `in_progress` tot elke
inzending is afgesloten, en daarna `completed` (of `fault` als geen ervan heeft gerapporteerd) —
gebruik dit om af te leiden of het labwerk van de afspraak klaar is. Een
`appointment.results.completed`-[webhook](https://docs.anivahealth.com/nl/concepts/webhooks.md) laat je weten wanneer dat gebeurt,
zodat je niet hoeft te pollen. De array `submissions` splitst dit uit per laboratoriumaanvraag, elk
met een eigen `lab_code`. Elk ontvangen resultaat en document heeft de `lab_code` waaronder het is
ingediend. De array `documents` verwijst naar de pdf's van labrapporten — gebruik
`GET /api/v1/documents/{id}` om ze te downloaden.

## Voorbeeldafspraak

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