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

# Afspraak aanmaken

> Plan een afspraak voor bloedafname in voor een profiel op een testlocatie

Plan een afspraak voor een bloedafname voor een patiëntprofiel op een specifieke testlocatie. Zodra de afspraak is aangemaakt, krijgt deze standaard de status `confirmed` (bij sommige locaties kan dit standaard `pending` zijn — dit is een instelling per locatie). Gebruik [Panels toevoegen](https://docs.anivahealth.com/nl/api/appointments/add-panels.md) om bloedtestpanels te koppelen voordat je [de bloedafname bevestigt](https://docs.anivahealth.com/nl/api/appointments/confirm-blood-draw.md).

> [!NOTE]
>
> Een profiel kan maximaal **één** afspraak per locatie en tijdstip hebben. Als je een afspraak
> aanmaakt voor een tijdslot dat het profiel al bezet houdt, krijg je een `409` met het bestaande
> `appointment_id` in plaats van een tweede afspraak — zo kan een opnieuw verzonden of per ongeluk
> herhaald verzoek nooit een dubbele boeking maken. Zie [Dubbele afspraken](#dubbele-afspraken).

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

Vereist de scope `appointments_schedule`.

## Verzoek

### Bodyparameters

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

UUID van het patiëntprofiel waarvoor je de afspraak aanmaakt.

**location\_id** `string` *required*

UUID van de testlocatie waar de bloedafname plaatsvindt. Gebruik [Locaties
weergeven](https://docs.anivahealth.com/nl/api/locations/list-locations.md) om beschikbare locatie-ID's te vinden.

**scheduled\_at** `string` *required*

Datum en tijd van de afspraak in ISO 8601-formaat (bijv. `2026-05-15T10:30:00Z` of
`2026-05-15T12:30:00+02:00`). **Moet een tijdzoneaanduiding bevatten** — `Z` of een expliciete
offset zoals `+02:00`; datum-tijdwaarden zonder tijdzone worden afgewezen. Moet in de toekomst liggen.

Moet exact samenvallen met de starttijd van een tijdslot in het rooster van de locatie, en het tijdslot moet nog ruimte hebben — bekijk eerst
[Beschikbaarheid ophalen](https://docs.anivahealth.com/nl/api/locations/get-availability.md). Tijden buiten het rooster geven `400` terug; een vol tijdslot
geeft `409` terug. Op locaties die door Aniva worden beheerd, moet dit bovendien minimaal 12 uur van tevoren zijn — zie
[Minimale boekingstermijn](#minimale-boekingstermijn).

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

**draw\_method** `string`

Hoe het bloed wordt afgenomen: `capillary` of `venous`. Laat dit veld weg om de `default_draw_method`
van de locatie te gebruiken. De methode moet in `draw_methods` van de locatie staan, anders volgt `400`.

## Respons

Bij succes geeft de API `201 Created` terug met de nieuwe afspraak.

**id** `string` *required*

Unieke afspraak-identifier (UUID).

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

UUID van het profiel waarbij deze afspraak hoort.

**location\_id** `string`

UUID van de testlocatie waar de bloedafname plaatsvindt.

**scheduled\_at** `string`

Geplande datum en tijd van de afspraak als UTC-tijdstip (ISO 8601 met `Z`-achtervoegsel, bijv.
`2026-05-15T10:30:00Z`). Kan `null` zijn.

**status** `string` *required*

Huidige status van de afspraak. Een van `pending`, `confirmed`, `blood_drawn` of `cancelled`.
De gedetailleerde voortgang van labresultaten leid je af uit [Resultaten ophalen](https://docs.anivahealth.com/nl/api/appointments/get-results.md);
de verdere voortgang van zendingen uit elk item in de inline `shipments`-array (zie hieronder)
door deze op te vragen via [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.

**profile** `object` *required*

Het patiëntprofiel dat bij deze afspraak hoort.

**profiel**

**id** `string`

Unieke profiel-ID (UUID).

**handle** `string`

Profiel-handle 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 centimeter. Kan `null` zijn.

**weight** `number`

Gewicht in kilogram. 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 (geautomatiseerde) e-mails ontvangt. Kan `null` zijn.

**panels** `AppointmentPanel[]` *required*

Panels die momenteel aan deze afspraak zijn gekoppeld. Leeg voor nieuw aangemaakte afspraken — koppel ze via
[Panels toevoegen](https://docs.anivahealth.com/nl/api/appointments/add-panels.md). Zoek paneldetails (naam, biomarkers) op via
[Panels weergeven](https://docs.anivahealth.com/nl/api/panels/list-panels.md).

**Velden voor gekoppeld panel**

**panel\_id** `string`

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

**added\_at** `string`

ISO 8601-tijdstempel waarop het panel voor het eerst aan deze afspraak werd gekoppeld.

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

Losse biomarkers die buiten een panel om aan deze afspraak zijn gekoppeld. Leeg voor nieuw aangemaakte
afspraken — koppel ze via [Individuele biomarkers toevoegen](https://docs.anivahealth.com/nl/api/appointments/add-individual-biomarkers.md).
Vergelijk elk `biomarker_id` met [Biomarkers weergeven](https://docs.anivahealth.com/nl/api/biomarkers/list-biomarkers.md)
voor weergavegegevens.

**Velden voor individuele biomarker**

**biomarker\_id** `integer`

Biomarker-identifier — zoek op via
[Biomarkers opvragen](https://docs.anivahealth.com/nl/api/biomarkers/list-biomarkers.md).

**added\_at** `string`

ISO 8601-tijdstempel waarop de biomarker voor het eerst aan deze afspraak werd gekoppeld.

**shipments** `AppointmentShipmentLink[]` *required*

Zendingen die aan deze afspraak zijn gekoppeld, oudste koppeling eerst. Leeg voor nieuw aangemaakte afspraken —
koppel ze via [Zending aanmaken](https://docs.anivahealth.com/nl/api/shipments/create-shipment.md) (met `appointment_id`) of
[Afspraken aan zending koppelen](https://docs.anivahealth.com/nl/api/shipments/attach-appointments-to-shipment.md).

**Velden voor zendingkoppeling**

**id** `string`

Zendingreferentie-identifier — zoek op via
[Zending ophalen](https://docs.anivahealth.com/nl/api/shipments/get-shipment.md).

**added\_at** `string`

ISO 8601-tijdstempel waarop de zending voor het eerst aan deze afspraak werd gekoppeld.

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

Labcodes (barcodes op de buisjes) die voor deze afspraak zijn vastgelegd, in scanvolgorde. Leeg totdat de bloedafname
is bevestigd. Een veneuze bloedafname heeft één code die op elk buisje staat gedrukt; een capillaire bloedafname heeft één
code per microtainer. Resultaten en documenten op [Resultaten ophalen](https://docs.anivahealth.com/nl/api/appointments/get-results.md) verwijzen
naar deze codes via `lab_code`.

## Minimale boekingstermijn

Afspraken op locaties die door Aniva worden beheerd, moeten minimaal **12 uur** van tevoren worden geboekt; boeken binnen
die termijn geeft `400` terug. [Beschikbaarheid ophalen](https://docs.anivahealth.com/nl/api/locations/get-availability.md) laat die
tijdslots al weg, dus alles wat je in dat rooster ziet is boekbaar.

Locaties die je zelf beheert hebben geen minimale boekingstermijn — boeken op dezelfde dag en bij inloop blijft ongewijzigd.

## Dubbele afspraken

Een profiel kan maximaal één niet-geannuleerde afspraak per locatie en tijdstip hebben — bij één persoon kan niet
twee keer tegelijk op dezelfde plek bloed worden afgenomen, hoeveel stoelen de locatie ook heeft.

Als je een afspraak aanmaakt voor een tijdslot dat het profiel al bezet houdt, krijg je een `409` terug met een
`appointment_id` dat de al bestaande afspraak aangeeft:

```json theme={null}
{
  "error": "This profile already has an appointment at this location and time. Reschedule or cancel the existing appointment instead of creating a second one.",
  "appointment_id": "03e916d2-7fd6-4414-8276-8532a105edc3"
}
```

Verwerk dit door het verzoek als al uitgevoerd te beschouwen: haal de afspraak op met
[Afspraak ophalen](https://docs.anivahealth.com/nl/api/appointments/get-appointment.md), verplaats deze met
[Afspraak bijwerken](https://docs.anivahealth.com/nl/api/appointments/update-appointment.md) of annuleer deze met
[Afspraak annuleren](https://docs.anivahealth.com/nl/api/appointments/cancel-appointment.md). Probeer het aanmaken niet opnieuw — dit blijft
`409` teruggeven.

Dit maakt herhaald aanmaken veilig: een verzoek dat je na een time-out opnieuw verstuurt, of een dubbel ingediend formulier,
kan geen twee afspraken voor dezelfde patiënt op hetzelfde tijdstip opleveren.

> [!NOTE]
>
> `appointment_id` is alleen aanwezig bij de `409` voor een dubbele afspraak. De `409` voor capaciteit — het tijdslot is vol
> omdat *andere* patiënten het bezet houden — geeft alleen `error` terug, en de juiste oplossing is dan om
> een ander tijdslot te kiezen uit [Beschikbaarheid ophalen](https://docs.anivahealth.com/nl/api/locations/get-availability.md).

## Foutresponsen

| Status | Beschrijving |
| - | - |
| `400` | Validatiefout — bijvoorbeeld als `scheduled_at` in het verleden ligt, minder dan 12 uur vooruit ligt op een locatie van Aniva, niet exact op een starttijd in het rooster van de locatie valt, of als de locatie geen afnamecontainers voor `draw_method` op voorraad heeft. |
| `403` | Geen toegang — je API-sleutel heeft geen toegang tot deze bewerking, of `results_ready_emails` is ingesteld zonder `results_view`-toegang tot de patiënt. |
| `404` | Profiel of locatie niet gevonden, of de locatie is inactief. |
| `409` | Dit profiel heeft al een afspraak op deze locatie en tijd (bevat `appointment_id`), het tijdslot is vol, de locatie is op die datum gesloten, of de `Idempotency-Key` is opnieuw gebruikt met een andere body of het oorspronkelijke verzoek is nog niet voltooid. |
| `500` | Interne serverfout. |

```bash cURL theme={null}
curl --request POST \
  --url https://anivahealth.com/api/v1/appointments \
  --header 'x-api-key: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "profile_id": "a3f1c2d4-8b7e-4f2a-9c1d-2e3f4a5b6c7d",
    "location_id": "b7e2d1f5-3c4a-4e8b-a2f1-9d0c1e2f3a4b",
    "scheduled_at": "2026-05-15T10:30:00Z"
  }'
```

```json 201 theme={null}
{
  "id": "c9f3e2a1-7d6b-4c5e-b3a2-1f0e9d8c7b6a",
  "profile_id": "a3f1c2d4-8b7e-4f2a-9c1d-2e3f4a5b6c7d",
  "location_id": "b7e2d1f5-3c4a-4e8b-a2f1-9d0c1e2f3a4b",
  "scheduled_at": "2026-05-15T10:30:00Z",
  "status": "confirmed",
  "cancellation_reason": null,
  "results_ready_emails": [],
  "draw_method": "venous",
  "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": [],
  "individual_biomarkers": [],
  "shipments": [],
  "lab_codes": []
}
```

```json 400 theme={null}
{
  "error": "Appointments must be booked at least 12 hours in advance. Please pick a later time."
}
```

```json 404 theme={null}
{
  "error": "Location not found or inactive"
}
```

```json 409 theme={null}
{
  "error": "This profile already has an appointment at this location and time. Reschedule or cancel the existing appointment instead of creating a second one.",
  "appointment_id": "03e916d2-7fd6-4414-8276-8532a105edc3"
}
```


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