Prerequisite

Please read the introduction to using the API.

Introduction

Integrating the Timekit API into your product is easy, but there are a few things you should know up front in regards to how you structure the data flow between your platform and ours. This article focuses on API integration only and leaves out use cases that include our admin and project widget UIs.

In general, most integrations consist of the following 3 steps:

• Create & setup resources (detailed guide)
• Search for availability (detailed guide)
• Create & update bookings (detailed guide)

When creating and configuring resource settings (step 1), you'll need to save some of the data we return so you can use it for fetching availability (step 2) and creating bookings later on (step 3). Let's jump right in!

Save resource meta-data on your end

Whether you automate resource creation into your own onboarding flow or you create resources manually within our admin, you'll need their ID to communicate with our API.

Almost all endpoints require that you define which resource or resources you're working with, like when creating a booking, you must specify which resource is being booked. You define this by means of the resource's ID.

In your own database (or whatever persistent storage you use), you most likely have a user table where you save metadata about your service providers, your resources. Add the following fields/columns:

The user's ID

timekit_resource_id [UUID]

You are of course free to name the fields/columns whatever you want.
Please note that for some advanced use-cases a resource could have more than one calendar being relevant for querying availability and storing events in.

Availability calendar

**timekit_findtime_calendar is an ID that you pass along to the FindTime endpoint which specifies the calendar witch the algorithm will use to look when searching for availability.

For Google-connected resources that have multiple calendars (e.g. a Personal and Work calendar). You should provide a UI where they pick the calendars to sync and use, and then toggle sync status through our API.

Availability filters

When fetching availability for a user, you can input filters and the FindTime algorithm will take them into account when calculating available time-slots.

Please refer to our introduction to filters for reference.

Target calendar

timekit_booking_calendar is used when you create bookings and specifies which calendar the event should end up in.

This is particularly relevant when syncing with Google, as it enables you to provide a UI where resources can pick which of their Google calendar they want your bookings to end up in. If your user doesn't sync with Google, you still need to provide a calendar ID.

Minimal effort by using our UIs

This article assumes that you want to make a 100% pure API integration (aka 'headless'). There are however also some hybrid approaches where you can leverage Timekit's Admin and booking widget UI to get up and running faster.

If you use Timekit's admin to create and configure resources + setup project widgets, you can actually skip all the above. The gotcha here is that the project widget you set up actually contains all the above in it's JSON config, which we persist in our DB.

Of course, you'll be limited to our standard embed functionality and won't be able to make additional API calls, but it might help you get off the ground fast.