Fetch availability of your resources in the form of timeslots. The availability engine is quite flexible and allows you to handle complex use-cases with different constraints across many resources.
Available until blocked
The default notion in Timekit is that a resource is available until blocked. Blocked meaning that an event is reserving time in the calendar (through provider sync or existing bookings) or that some general business rules like opening hours have been applied (as constraints).
If you on the other hand want to predefine available timeslots in advance, please refer to the availability section in the docs.
With our project model, you can predefine which parameters are used to query availability. If your integration with Timekit is based on projects, simply use the ID of the project instead of setting the parameters directly in the call.
Please refer to our Projects overview.
When calculating availability for one or more resources, you need to choose a strategy for how you want timeslots returned. This is specified by the
mode parameter, which have the following options:
roundrobin_random is used when you want any of the specified resources to be available. It shuffles the
resources array, then calculates each resource's availability and finally returns a list of timeslots with a single bookable resource per timeslot. The returned resource for a given timeslot is random based on the initial shuffle of the list of bookable resources. This can be used when you have a pool of resources, e.g. a team of salespeople, but you only need to book one of them.
roundrobin_prioritized is same as above, but will respect the order of the resources you supply in the
resources array and favor the first one if multiple resources are availability at a given time.
mutual searches for overlapping timeslots where all of the specified resources need to be available. Ideal for use-cases like meetings with multiple participants or rooms that require equipment to be accessible.
Note that there can only be one resource that is "owning" the created booking, so if you need to include more resources in the booking, make sure to add them as participants to the final event to make sure their calendar is blocked too.
At the heart of the availability engine is what we call "constraints": business rules that reduces the available ranges of time that a given resource can be available. In the most common use-cases, these are exemplified as opening hours e.g. a resource should only be a available certain days (monday-tuesday) and at certain times (1pm-5pm).
The constraints that you specify in the
constraints parameter are applied dynamically to each resource in the
resources array. This is in addition to the constraints that you might have defined on the globally on resource model outside of the
POST /availability request, see
POST /resources for how to set a resource's availability.
We do not check for logical blockage on constraints in relation to the search space, this is up to you to check for. For example if your search space consists of just two days, e.i. "from":"now", "to":"2 days" and use the constraint "block_weekends" and you request the endpoint on a saturday morning, you will get no results and you will get no errors or warnings.
How availability is calculated
In essence, the availability engine converts all constraints, calendar events and bookings into "blocking timeslots" that is subtracted from the final output of available timeslots.
For each resource, these are calculated in the following order:
tosupplied in the request (or defined in a project)
constraintssupplied in the request (or defined in a project)
- Resource-level constraints saved on the resource model
- Bookings owned by the resource
- Calendar events for the resource (synced through Google/Microsoft)
The buffer option makes sure that you have some breathing time between any existing events in your calendars, and the available time-slots offered. Once an available time-slot has been booked and turned into a calendar event, additional buffer time will be added to it, when querying for availability.
You define buffer like you define length:
"1 hour" etc.
By default, the algorithm will return sequential time-slots. The time-slots will not overlap, which means that some potential time-slots are ignored. If you want overlapping time-slots you define the increment from the previous time-slot start with this setting.
Example without timeslot_increments:
If we request time-slots of 1 hours length, from 10 to 12, without timeslot_increments defined, these 2 time-slots will be returned:
Examples with timeslot_increments:
If we request with timeslot_increments: "15 minutes", these 5 time-slots will be returned:
If we request with timeslot_increments: "30 minutes", these 3 time-slots will be returned:
With the release of available events, the setting ignore_all_day_events has been deprecated. By default an all day event in google calendar is an available event and will as such not block availability.
If you create all_day_events manually through the /events endpoint, you need to make sure to also set the "available" parameter to true in order to make sure that the event isn't blocking.