Naar hoofdinhoud gaan
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.

Velden

string
vereist
UUID die automatisch door Aniva wordt gegenereerd. Gebruik deze om panels toe te voegen, de bloedafname te bevestigen en resultaten op te halen.
string
vereist
De UUID van het profiel waarbij deze afspraak hoort.
string
De UUID van de testlocatie waar de bloedafname plaatsvindt. Thuistestkits zijn geen afspraken — zie Bestellingen van thuistestkits.
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).
string
vereist
Huidige levenscyclusstatus. Een van pending, confirmed, blood_drawn of cancelled. Zie Levenscyclus hieronder. De voortgang van labresultaten (in_progress vs. completed) haal je op via Resultaten ophalen; gedetailleerdere voortgang van zendingen (onderweg, bezorgd, enz.) vind je door elk item in de inline shipments-array te volgen naar Zending ophalen.
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.
string[]
vereist
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.
string
vereist
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. Na de bloedafname is dit de methode die is gebruikt.
string
vereist
ISO 8601-tijdstempel van wanneer de afspraak is aangemaakt.
string
ISO 8601-tijdstempel van de meest recente update. Null als de afspraak nog nooit is bijgewerkt.
string[]
vereist
Labcodes (buisbarcodes) die bij Bloedafname bevestigen 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.
object[]
vereist
Panels die aan deze afspraak zijn gekoppeld, als { panel_id, added_at }-items. Zie Panels toevoegen.
object[]
vereist
Losse biomarkers die aan deze afspraak zijn gekoppeld, als { biomarker_id, added_at }-items. Zie Individuele biomarkers.
object[]
vereist
Zendingen die aan deze afspraak zijn gekoppeld, als { id, added_at }-items, oudste koppeling eerst. Zie Zendingen koppelen.
object
vereist
Het volledige profielobject van de patiënt, opgenomen in elke afspraakrespons. De velden hieronder zijn een selectie. Afspraak ophalen vermeldt ze allemaal.

Levenscyclus

Afspraken hebben vier levenscyclusstatussen:
De afspraakstatus is bewust globaal gehouden — gedetailleerdere voortgang is beschikbaar via aparte endpoints:
  • Voortgang van labresultaten → Resultaten ophalen — 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 — elke zending heeft een eigen status en een status_updates-eventlog.
Elke statuswijziging verstuurt een appointment.*-webhook, bijvoorbeeld appointment.confirmed. Een nieuwe tijd of locatie verstuurt appointment.rescheduled.
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:
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:
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 als Afspraak bijwerken 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.
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:
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.
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:
Geef een array van panel-UUID’s door in het veld panel_ids. Panel-ID’s worden door Aniva geleverd voor je partneraccount.
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:
Geef een array van panel-UUID’s door in het veld panel_ids. Verwijderen is idempotent: een panel dat niet gekoppeld is, wordt genegeerd.
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):
Biomarkers verwijderen (idempotent — biomarkers die niet gekoppeld zijn, worden genegeerd):
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 om biomarker-ID’s op te zoeken.
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:
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), 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.
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:
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

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 — 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 / Afspraak ophalen) voor de volledige payload. Zendingen worden bij het aanmaken gekoppeld via het veld appointment_id in Zending aanmaken. Na het aanmaken beheer je koppelingen vanaf de zending met Afspraken aan zending koppelen en Afspraken van zending loskoppelen; beide geven de bijgewerkte afsprakenlijst voor die zending terug. Om alle pakketten van een afspraak volledig te bekijken, gebruik je Zendingen weergeven 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:
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 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