Query availability

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.

Project ID

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.

Mode

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:

Round-robin random
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.

Round-robin prioritized
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.

Exclusive
exclusive returns all resources UUIDs that are available at the specified time provided. Whereas Round-robin random selects a resource at random and and Round-robin prioritized selects a resource in a particular order, Exclusive can be used to return every resource so that you can select one, several, or all of them to be displayed to give you a choice.

Mutual
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 "owns" 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.

Constraints

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:

1. Parameters from and to supplied in the request (or defined in a project)
2. Global constraints supplied in the request (or defined in a project)
3. Resource-level constraints saved on the resource model
4. Bookings owned by the resource
5. Calendar events for the resource (synced through Google/Microsoft)

Buffer Time

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: "15 minutes", "1 hour" etc.

Timeslot increments

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:
10:00-11:00
11:00-12:00

Examples with timeslot_increments:

If we request with timeslot_increments: "15 minutes", these 5 time-slots will be returned:
10:00-11:00
10:15-11:15
10:30-11:30
10:45-11:45
11:00-12:00

If we request with timeslot_increments: "30 minutes", these 3 time-slots will be returned:
10:00-11:00
10:30-11:30
11:00-12:00

Example scenario: You want a 15 min meeting that starts at 00 and 30 only.

Supposing we review a sample availability 12:00 pm to 2:00pm.
If you check for availability using 30 mins increments for this, you would see
12:00
12:30
1:00
1:30
If you booked a 15 min meeting at 12:00, then 12:00 - 12:15 is booked. Subsequently, if you check for availability again using 30 min increments, it would appear like this:

12:15 - 12:45
12:45 - 1:15
1:15 - 1:45

Increments work on availability, so Timekit sees that the first availability is 12:15 and then increments 30 mins from there.

As a possible alternative, if you wanted meetings to be only available at 00 and 30, then you could add a 15 min buffer to your 15 min meeting, and make a PUT call to the Project endpoint with something like this:

{
        "mode": "roundrobin_random",
        "length": "15 minutes",
        "from": "1 hour",
        "to": "4 weeks",
        "buffer": "15 minutes",
        "ignore_all_day_events": false,
        "timeslot_increments":"30 minutes"
}

📘

Deprecated ignore_all_day_events

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.