Beschikbaarheid opvragen via de API

Na dit artikel kun je via de API opvragen of één ruimte of alle ruimtes van een workspace in een tijdvenster vrij zijn — met conflictlijst, buffer vooraf, de geldende opbouwtijd per ruimte en context over de bezetting.

Met het endpoint 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 een boeking te starten.

Het antwoord is hetzelfde als dat de boekingspagina en de chat gebruiken: alle evenementen van je workspace tellen mee (ook concepten en opties; alleen geannuleerde, afgewezen en gearchiveerde niet), plus draaiboekpunten, ruimtegroepen en blokkades. Open aanvragen houden een ruimte niet vast — maar je kunt ze op wens meetoetsen als voorlopige bezetting.

Sleutel en machtiging

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

Het verzoek

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=true
ParameterVerplichtBetekenis
fromjaBegin van de periode. Datum (2026-10-01) of datum met tijd (2026-10-01T18:00).
tojaEinde van de periode, in dezelfde notatie. Een kale datum betekent de hele dag.
location_idneePrecies deze ruimte. Ontbreekt hij, dan geldt het antwoord voor alle ruimtes van de workspace.
buffer_minutesneeVoor- en nalooptijd in minuten (opbouw, afbouw). 0 (standaard) betekent: de gevraagde periode wordt letterlijk gecontroleerd. De waarde is een ondergrens: heeft een ruimte onder Opbouw- en schoonmaaktijd (minuten) een eigen opbouwtijd, dan geldt voor die ruimte de grootste van beide waarden, niet de som. Welke waarde gold, staat in het antwoord bij het conflict (zie effectiveBufferMinutes).
include_soft_holdsneeStandaard false: open, nog niet beslechte aanvragen tellen niet als bezet — net zoals bij het versturen van een boeking. Met true zie je ze als voorlopige bezetting (soft_hold).

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. Bij één opgevraagde ruimte staat er extra locationAvailable.
  • window — wat daadwerkelijk is gecontroleerd. Met buffer is het venster aan beide kanten ruimer dan gevraagd; requested_from/requested_to tonen ongewijzigd wat je hebt gestuurd. 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 staat. type geeft aan waardoor:
typeBetekenis
event_overlapEen evenement valt binnen het venster. confirmed geeft aan of het al bevestigd is.
schedule_item_overlapEen draaiboekpunt (opbouw, afbouw, levering) bezet de ruimte.
group_cascadeEen andere ruimte van dezelfde ruimtegroep is bezet — de groep wordt als geheel vastgehouden.
soft_holdEr ligt een open aanvraag. Alleen met include_soft_holds=true.
capacityDe bovengrens voor parallelle aanvragen is binnen het venster bereikt.
blocked_periodEen blokkade is van kracht. location_id is hier null als de blokkade de hele workspace betreft.

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, Rüstzeit des Raums), maximaal 1440. Ontbreekt hij, 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 kon worden gelezen. Het antwoord is dan niet uitputtend: behandel het niet als toezegging, maar vraag opnieuw op.
  • notes — de fijne kneepjes 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 wordt per boekingspagina ingesteld; een API-aanroep heeft geen paginacontext. Daarom staat ze niet in dit antwoord — ontbreekt ze, dan is dat geen nul.
  • Geen minuutnauwkeurigheid bij blokkades en voorlopige aanvragen. Blokkades en (met include_soft_holds=true) open aanvragen worden per dag beoordeeld in de tijdzone van de workspace, evenementen daarentegen op de minuut. Het resultaat is daardoor nooit ruimer dan de boekingspagina, maar kan strenger zijn. De notes in het antwoord geven dat per geval aan.

Foutmeldingen

AntwoordBetekenis
400from/to ontbreken, zijn onleesbaar of staan in omgekeerde volgorde; location_id is geen geldige ID; buffer_minutes is negatief of groter dan 1440. Het antwoord noemt de reden.
401Geen of een onbekende sleutel.
403De sleutel heeft de machtiging Locaties lezen niet.
429Te veel verzoeken in korte tijd.

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

Univents-nieuwsbrief

Productnieuws en praktijktips voor event- en cateringbedrijven. Ongeveer één keer per maand, niet vaker.

De nieuwsbrief wordt in het Engels verstuurd.

Onderwerpen
Beschikbaarheid opvragen via de API