Get available calendar slots

API
1

I’m using the API to create bookings. I can also get all the bookings that I made with the API. This all works fine. But I obviously have a question. I’ll try to explain what I currently have a first.

I have a web page where a user can “book” a timeslot to make an appointment with us. So a user can pick a day in the coming week, and after that he can choose a certain time.

So for example, a user can pick a day, lets say: “Wednesday”.
He is then presented with timeslots, each of 30 minutes (like it is configured on the booking calendar):

08:00 - 08:30 (available)
08:30 - 09:00 (available)
0900 - 09:30 (busy)
etc.
16:30 - 17:00 (last available timeslot in a workweek)

So what I basically need to do is render a “calendar” that shows all the booked and available dates.

I can do this by getting booked dates from the API. Then do a foreach loop on a date/time, increment that by 30 minutes and check if that current date/time is in the list of bookings.

But I’d rather get this “calender” from the API if possible instead of doing this manually.

That way, if they ever decide to change the working hours from 09:00 till 18:00, instead of 08:00 till 17:00, I then don’t have to change anything on my side in the code, because the entire calender would come from the API.

Is it possible to get this “calendar” data from the API including all the booked and available timeslots?

2

@Vivendi great question. We do not yet have our availability endpoint exposed to the public. This is only used internally for the booking engine to function. I will get your feedback submitted as a feature request. One option in the interim is to use either Google Calendar or Microsoft’s API to run a free/busy check on the linked calendars. This adds another layer of complexity, but may be possible to get you something in the interim.

3

Thanks for the quick feedback and your suggestion. I will look into the Microsoft API for this functionality.

1 Like
4

It might be worth checking out https://www.cronofy.com/.

I’ve used them for this exact purpose and it was pretty great.

5

Any progress on this?

6

@tomds we are finishing up testing our new booking system. This then will open the team up for the roll out of v2 of our API which will have an availability endpoint. I don’t have a definitive timeframe, but that is next on our list to tackle to get to unlock another large scale team infrastructure update we are working on.

7

Any update on getting availability through the API?

8

Yes, it is available on new pages built within the new system. I will work up the documentation for this and share with everyone.

At a real high level, the availability endpoint is based off of a concept of intents. This essentially is a recipe for the booking. This includes but is not limited to, Team Member, Appointment Type, Timezone, Duration, etc.

At a high level though you first make a POST to:
https://api.youcanbook.me/v1/intents
{
“subdomain”: “booker-app-test”
}

The subdomain of the page will be needed here.

Then you get a return of the intentId:
{
“id” : “itt_39c8e88d-afa8-4e53-aae0-b0e7db369304”,
“createdAt” : 1679061108697,
“intentStatus” : “SETTING_UP”,
“bookingId” : null, "
selections" :
{
“timeZone” : null,
“duration” : null,
“units” : null,
“appointmentTypeIds” : null,
“teamMemberId” : null,
“startsAt” : null,
“form” : null
}
}

From there you can make your PATCH to: https://api.youcanbook.me/v1/intents/{intentId}/selections

Passing in whatever is applicable:
{
“selections” :
{
“timeZone” : “US/Central”,
“units” : null,
“appointmentTypeIds” : [

“jsid4353484”

],
“teamMemberId” : null
}

After adjusting the intentId, you can get the availbilityKey: https://api.youcanbook.me/v1/intents/{intentId}/availabilitykey

Returns:
{ “key” : “avl_b68855aaaf28705b6d513854a71799db292e0fde59c0f9e0370c4271e1efdd55T_57” }

Then GET : https://api.youcanbook.me/v1/availabilities/{availbilityKey}

This will return the millisecond availability based off of the selections you have made in the intent.

1 Like
9

Thank you @Ben, I got it working based on your instructions. :+1:

1 Like
11

@Trilliumaire

1 Like
12

Hey!
How would I go about getting availability for a specific week/month?

I tried passing this into the /v1/intents

	"selections": {
			"startsAt": 1693821600000
	}

But it didn’t seem to limit it. Ideally I want to pass in a start&end time. Any docs on this yet?

13

@Martyn let me check with the development team.

14

@Martyn the way of requesting for availability for specific dates is using the startSearchAt when requesting the availbility key

e.g https://api.youcanbook.me/v1/intents/itt_830d7758-9eec-48b4-b59a-b6702ab75818/availabilitykey?startSearchAt=2023-09-21 will start the availability search on the 21st of September, and it will return the availability for the following 30 days