Beschikbaarheid opvragen via de API

Met de interface GET /api/v1/availability vraagt je eigen systeem bij Univents na of een periode vrij is: voor één ruimte of voor alle ruimtes van een workspace. Zo kan je website, je planningstool of een ander systeem een toezegging doen zonder dat er een boeking wordt aangemaakt.

Het antwoord is hetzelfde als dat de boekingspagina en de chat gebruiken: bezette evenementen, draaiboekpunten, ruimtegroepen, openstaande aanvragen en blokkeringsperiodes tellen mee.

Sleutel en machtiging

Je hebt een API-sleutel nodig met de machtiging Locaties lezen. Aanmaken doe je onder Integraties → Ontwikkelaars → API-sleutels — de installatie staat in het artikel over API-sleutels. Stuur de sleutel bij elke aanvraag mee als Authorization: Bearer <Schlüssel>. Een sleutel zonder deze machtiging krijgt een weigering, geen leeg resultaat.

De aanvraag

GET /api/v1/availability?from=2026-10-01&to=2026-10-03
GET /api/v1/availability?from=2026-10-01T18:00&to=2026-10-01T23:00&location_id=<Raum-ID>
GET /api/v1/availability?from=2026-10-01&to=2026-10-03&buffer_minutes=120&include_soft_holds=false

Zonder tijdzone gelden datum en tijd in de tijdzone van je workspace. Voeg je een Z of een offset toe (2026-10-01T18:00Z), dan geldt de waarde letterlijk.

Het antwoord

{
  "available": false,
  "window": {
    "requested_from": "2026-10-01",
    "requested_to": "2026-10-03",
    "from": "2026-09-30T22:00:00.000Z",
    "to": "2026-10-03T22:00:00.000Z",
    "buffer_minutes": 120
  },
  "free_location_ids": ["…"],
  "locationAvailable": false,
  "conflicts": [
    {
      "type": "event_overlap",
      "location_id": "…",
      "from": "2026-10-02T15:00:00.000Z",
      "to": "2026-10-02T22:00:00.000Z",
      "confirmed": true
    },
    {
      "type": "soft_hold",
      "location_id": "…",
      "from": null,
      "to": null
    }
  ],
  "notes": ["Soft holds (open, non-archived requests) are counted per day …"]
}

• available — vrij of niet, over alle gecontroleerde ruimtes heen. Bij één opgevraagde ruimte staat er aanvullend locationAvailable.
• window — wat daadwerkelijk is gecontroleerd. Met buffer is het venster aan beide kanten ruimer dan opgevraagd; requested_from/requested_to tonen ongewijzigd wat je hebt verstuurd. Jouw buffer_minutes wordt daarbij getoond; de opbouwtijd van een ruimte zit er niet in, maar staat per conflict in effectiveBufferMinutes.
• free_location_ids — de ruimtes die in het venster vrij zijn.
• conflicts — wat in de weg zit. type geeft aan waardoor:

effectiveBufferMinutes staat bij een bezettingsconflict zodra voor die ruimte een opbouw- en schoonmaaktijd van kracht was: de waarde in minuten waarmee is gerekend — max(buffer_minutes, opbouwtijd van de ruimte), maximaal 1440. Ontbreekt de waarde, dan is zonder buffer gecontroleerd. Bij het conflict blocked_period en bij de bovengrens voor aanvragen (capacity) staat hij er niet.

• degraded — alleen aanwezig als een deel van de controle niet gelezen kon worden. Het antwoord is dan niet sluitend: behandel het niet als toezegging, maar vraag opnieuw op.
• notes — de details die je moet kennen om het antwoord goed te lezen; zie hieronder.

Wat het antwoord niet is

• Geen boeking. De aanroep reserveert niets. Tussen opvragen en boeken kan een ander proces de ruimte bezetten — de boeking zelf controleert opnieuw.
• Geen persoonsgegevens. Het antwoord noemt ruimte-ID’s en periodes, geen namen, geen contacten, geen contactpersonen.
• Geen bovengrens per pagina. De bovengrens voor parallelle aanvragen stel je per boekingspagina in; een API-aanroep heeft geen paginabinding. Daarom staat die grens niet in dit antwoord — ontbreekt hij, dan is dat geen nul.
• Geen precisie op de minuut bij blokkeringsperiodes en openstaande aanvragen. Blokkeringsperiodes en openstaande aanvragen worden per dag gewaardeerd in de tijdzone van de workspace, evenementen daarentegen op de minuut nauwkeurig. Het resultaat is daardoor nooit ruimer dan op de boekingspagina, maar kan strenger zijn. De notes van het antwoord geven dit per geval aan.

Foutgevallen

Een leeg tijdvenster of een typfout in de datum leidt nooit tot „Vrij” — dergelijke aanvragen worden afgewezen. De uitgebreide beschrijving van de interface met alle velden vind je in de API-referentie onder /api/v1/docs.