Using FindTime

In this tutorial, we'll be teaching you how to request the /findtime endpoint to get availability through the API.

👍

Working with the API

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

➡️ Availability API reference

Introduction

Timekit offers two different ways of querying for availability.

1. Free until booked: Where a resource is available until a booking reserves time in the calendar, usually general business-rules like opening-hours also applies.
2. Group bookings: Where an available time-slot is defined on beforehand, with a limited number of seats available.

In this article we'll be covering the first type: Free until booked, and how you can configure Timekits FindTime engine to help you create your desired booking experience. Please refer to this tutorial for group bookings if that is more in line with your use-case.

FindTime

Timekit utilizes our FindTime engine to find availability for a resource. It works by requesting the /findtime endpoint with a set of params telling the engine which resource, when, how and for how long.

A request to FindTime could look like this:

curl --request POST \
  --url https://api.timekit.io/v2/findtime \
  --header 'Content-Type: application/json' \
  --user :live_api_key_7nzvc7wsBQQISLeFSVhROys9V1bUJ1z7 \
  --data '{
  "resource_ids": ["78a4d873-2a68-41c6-bdd4-c0ca5b35efd3"],
  "filters": { "or": [
    {"specific_day_and_time":{"day":"Monday","start":9,"end":13}},
    {"specific_day_and_time":{"day":"Wednesday","start":10,"end": 16}}
  ]},
  "future": "2 days",
  "length": "30 minutes"
}'

Let's break it down:

In the request above you'll see that we are have something called resource_ids. This is telling FindTime which of your resources it needs to look at, if you provide more than one ID, the engine will look for mutual availability, which means finding timeslots where both resources are available. If you want a query where any of a list of resources are available, please refer to team availability.

Filters

If you just supply a resource Id and not any filters, FindTime will return all available times 24/7. This is usually not what we're looking for. So we'll apply our filters to limit availability to only look at Monday between 9 and 13 and Wednesday between 10
and 16 (note we are using 24h clock).

We have a list of filter examples, to give you idea to how you can structure your filters to be in line with your business-rules

You can also see the full API reference for how to format your filters here: https://reference.timekit.io/reference#find-time-filters

Time-slot length and search-space

Finally you can see we have included "future": "2 days" and "length": "30 minutes" at the bottom of the request. This tells FindTime that it needs to look 2 weeks into the future and look for available time-slots of 30 minutes length.
The search-space will default start from the next full hour, but you can modify this with the "start" parameter, like this: "start": "1 day" which would mean that the search-space would start tomorrow.

Ok, let's look at the response:

{
  "data": [
    {
      "start": "2015-03-24T15:00:00+01:00",
      "end": "2015-03-24T16:00:00+01:00"
    },
    {
      "start": "2015-03-24T21:45:00+01:00",
      "end": "2015-03-24T22:45:00+01:00"
    },
    {
      "start": "2015-03-25T07:30:00+01:00",
      "end": "2015-03-25T08:30:00+01:00"
    },
    {
      "start": "2015-03-25T16:30:00+01:00",
      "end": "2015-03-25T17:30:00+01:00"
    },
    {
      "start": "2015-03-25T18:15:00+01:00",
      "end": "2015-03-25T19:15:00+01:00"
    }
  ]
}

When requesting the endpoint correct you will receive a 200 OK response in JSON format with all the available times that match your request.

For a full reference on the /findtime endpoint please refer to the API reference.