Velden
UUID die automatisch door Aniva wordt gegenereerd. Gebruik deze om panels toe te voegen, de bloedafname te bevestigen en resultaten op te halen.
De UUID van de testlocatie waar de bloedafname plaatsvindt. Thuistestkits zijn geen afspraken — zie
Bestellingen van thuistestkits.
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).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.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.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.
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.ISO 8601-tijdstempel van de meest recente update. Null als de afspraak nog nooit is bijgewerkt.
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.Panels die aan deze afspraak zijn gekoppeld, als
{ panel_id, added_at }-items. Zie
Panels toevoegen.Losse biomarkers die aan deze afspraak zijn gekoppeld, als
{ biomarker_id, added_at }-items. Zie
Individuele biomarkers.Zendingen die aan deze afspraak zijn gekoppeld, als
{ id, added_at }-items, oudste koppeling eerst. Zie
Zendingen koppelen.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 isin_progressofcompleted. - Voortgang van zendingen (onderweg, bezorgd, enz.) → volg elk item in de inline
shipments-array bij de afspraak naar Zending ophalen — elke zending heeft een eigenstatusen eenstatus_updates-eventlog.
appointment.*-webhook, bijvoorbeeld
appointment.confirmed. Een nieuwe tijd of locatie verstuurt appointment.rescheduled.Afspraken ophalen
Haal alle afspraken op waartoe je API-key toegang heeft:?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: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 eendraw_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: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: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: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 eenindividual_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):
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: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: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
Om de voortgang na de bloedafname te volgen, ga je voor elk item in de inlineshipments-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.
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.
Labresultaten ophalen
Zodra het lab de bloedmonsters heeft verwerkt, haal je de klinische en genetische resultaten op: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.