Availability overview

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

📘

We're evolving

Please remember to also check out our avaliability v2 docs.
Availability v2 is our next iteration without stepping an entire major version up. Availability v2 is used by projects, has a simpler syntax, supports resource-specific availability-constraints and is much faster for team availability.

👍

Working with the API

Take a look at our API reference to learn more about the different endpoints in the API.

➡️ Availability API reference

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 "start" and the "future" parameters. These two parameters are 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 start to "3 days" and future to "3 days 2 weeks". If you want to find availability in the next week/7 days, just omit start (it will default to "now") and set future to "1 week". If you do not set a "future" parameter in the request, Timekit will default to 4 weeks. Please note that you cannot currently set future 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.

Filters

Filters 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 filters like business hours ( 9-18 / 9am-6pm ), exclude weekends etc. But also configurable filters like specific day and specific time and finally between timestamps where you define exact availability.

Filters can be combined in "and" and "or" combinations to achieve complex business rules.

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.

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 "between timestamps" filters.
2. Through group bookings. Please refer to the group booking tutorial, for how you set up a group booking.

Added availability through between timestamps filters.

For each time-slot that you want to make available you need to add a between timeslots filter. 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 filter settings you would apply:

"filters": {
  "or": [
    { "between_timestamps": {
      "start": "2018-01-02T00:00:00+02:00", 
      "end": "2018-01-03T00:00:00+02:00", 
      "timezone": "Europe/Copenhagen"}
    },
    { "between_timestamps": {
      "start": "2018-01-04T00:00:00+02:00", 
      "end": "2018-01-05T00:00:00+02:00", 
      "timezone": "Europe/Copenhagen"}
    }
  ]
}

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