Skip to main content
Introduction to availability.

This article gives an introduction to the concept of availability if you're working with the API.

Written by derrick mak
Updated over a week ago

Timekits default notion is that a resource is available until blocked

Availability is the concept that people most often misunderstand.
The default notion in Timekit is that a resource is available until blocked. Blocked meaning that a booking is reserving time in the calendar or that some general business-rules, like opening-hours have been applied.
This is contrary to the use-cases where the baseline is: A given resource is only available in these pre-defined time-slots, this is what we refer to as added availability

Timekit is powerful enough to handle both concepts, the "added availability" baseline just needs a little more attention from an integration point of view.

Defining the specifics for availability

When you want to find availability you're typically looking for a specific length of time where a resource is available, within a given period and applying some general business-rules. At least this is Timekits way of looking for availability at its core. These next paragraphs will describe how you define the specifics.

Search space

The search space is the period in which you want to search for availability. It is defined by the "from" and the "to" parameters. These two parameters can be static timestamps or relative to now (the time at which the request is send to the API). So if you want to look for availability in the next two coming weeks, and now is friday, you would set "from" to "3 days" and future to "3 days 2 weeks". If you want to find availability in the next week, just omit "from" (it will default to "now") and set "to" to "1 week". If you do not set a "to" parameter in the request, Timekit will default to 4 weeks. Please note that you cannot currently set "to" to more that 6 months.

Time-slot length

Time-slot length is defined by the "length" parameter, so if you're looking for time-slots of 2 hours length, you set the length parameter to "2 hours" and so forth. If you do not define the length parameter Timekit will default to 1 hour.


Constraints are Timekits way of defining general rules for availability. As mentioned opening-hours are a kind of general business-rule. Timekit offers a range of common constraints like "block weekends". But also configurable filters like "allow hours" and finally "allow period" you define exact availability or "block period" for instance if there's a public holiday.
Constraints are either allowing (which in implicitly blocks everything else) and blocking.
For a complete reference of our filters, please refer to the API documentation.

More settings
Timekit supports a range of other settings, but they are out of scope of an introduction. For a complete list of settings please refer to our API reference.

Next steps

If you're ready to go deeper into the "available until blocked" use-case, please read this tutorial if you want to know how you should integrate. If your use-case demands added availability please read on.

Working with added availability

If you need to implement added availability either because you cannot sync the resource's calendar or because your use-case demands this way of implementing availability, we have two ways of achieving this.

  1. Through a list of "allow period" constraints.

  2. Through group bookings. Please refer to the group booking tutorial, for how you set up a group booking.

Added availability through allow_period constraints.
For each time-slot that you want to make available you need to add an allow_period constraint. So for example if you want to make January 2nd and 4th available for booking (and these being the only dates available), this would be the constraints settings you would apply:

"constraints": {
  { "allow_period":
      "start": "2018-01-02T00:00:00+02:00",
      "end": "2018-01-03T00:00:00+02:00"
  { "allow_period":
      "start": "2018-01-04T00:00:00+02:00",
      "end": "2018-01-05T00:00:00+02:00"

When using allow_period constraints for adding availability, you still need to set the "length" parameter or rely in the "1 hour" default.

Did this answer your question?