This article is will only talk about API-integration, if you just need to set up group bookings through our Admin interface, please refer to this guide on setting up a group booking.
This article assumes that you have familiarised yourself with the Timekit term "booking graphs" introduced in this article
To recap group bookings from that introduction, group bookings are bookings-flows where you offer a defined number of "seats" at a given time. Each seat-booking has its own flow defined by the group_customer ` graph, depending on whether you need that extra state for your implementation for each seat or not.
We will use a webinar as an example in this tutorial. We will assume that you have created the resource you need to book, for this tutorial we assume the resource to be Doc Brown and his ID is:
78a4d873-2a68-41c6-bdd4-c0ca5b35efd3
Step 1: Define the availability of webinar.
Here we will define such details as when, where, how many seats etc.
curl --request POST \
--url https://api.timekit.io/v2/bookings \
--user :live_api_key_7nzvc7wsBQQISLeFSVhROys9V1bUJ1z7 \
--data '{
"resource_id": "78a4d873-2a68-41c6-bdd4-c0ca5b35efd3",
"project_id" : "3f5ad8b7-ef4e-4765-bb54-f2117c508a00" ,
"graph": "group_owner",
"settings": {
"max_seats": 20
},
"start": "2016-09-30T08:00:00-08:00",
"end": "2016-09-30T09:00:00-08:00",
"what": "Doc Brown's webinar on flux capacitance",
"where": "https://join.skype.com/XXXXXX",
"description": "This webinar assumes you have read Doc Browns introduction paper on flux capacitance"
}'
This will set up a group booking on the 30th of September from 8am to 9am with 20 seats available for booking.
For a full reference of parameters, like deadline for signing up, please refer to our API reference.
The above request will amongst many other things, respond with the ID of the webinar booking, we assume that the API will respond with this id:
58190fc6-1ec0-4ebb-b627-7ce6aa9fc703
Step 2: Query for available seats
Now that we have the webinar set up, we want people to book the seats, but first we need to check if there are any available seats, we do this by requesting the endpoint [GET] /v2/bookings/group/{ID} like so:
curl --request GET \
--url https://api.timekit.io/v2/bookings/groups/58190fc6-1ec0-4ebb-b627-7ce6aa9fc703 \
--user :live_api_key_7nzvc7wsBQQISLeFSVhROys9V1bUJ1z7
This will produce a response similar to this:
{
"data": {
"id": "58190fc6-1ec0-4ebb-b627-7ce6aa9fc703",
"state": "tentative",
"graph": "group_owner",
"completed": false,
"created_at": "2015-12-14T10:28:22-08:00",
"updated_at": "2015-12-14T10:28:22-08:00",
"attributes": {
"event_info": {
"start": "2016-09-30T08:00:00+08:00",
"end": "2016-09-30T09:00:00+08:00",
"what": "Doc Brown's webinar on flux capacitance",
"where": "https://join.skype.com/XXXXXX",
"calendar_id": "bfa0b9fa-36aa-4ae6-8096-f3b20fbed1d2",
"description": "This webinar assumes you have read Doc Browns introduction paper on flux capacitance"
}
"group_booking": {
"max_seats": 10,
"current_seats": 2
}
}
}
}
The important part being current_seats, currently 2 seats are booked, meaning 8 seats are available.
Step 3: Book a seat
As long as there are seats left, we can book them using the group_customer graph. Lets assume that Marty McFly is interested in flux capacitance and wants to book a seat, this will be the request we send, for Marty to book a seat.
curl --request POST \
--url https://api.timekit.io/v2/bookings \
--user :live_api_key_7nzvc7wsBQQISLeFSVhROys9V1bUJ1z7 \
--data '{
"graph": "group_customer",
"related": {
"owner_booking_id": "58190fc6-1ec0-4ebb-b627-7ce6aa9fc703",
"seats": 1
},
"customer": {
"name": "Marty McFly",
"email": "marty.mcfly@timekit.io"
}
}'
Again the important bits are of course "customer" as with normal bookings, and the "related" data, where we specify which group_owner(the webinar) booking this "seat" booking is related to. The "seats" parameter is optional and you can book as many as you like. If omitted it will default to 1, so normally you will omit it, it is just here for reference.
The response to a group_customer booking will return a responce similar to this:
{
"data": {
"id": "e1d7826c-ecaf-4e07-917b-7f3f7219e3f0",
"state": "confirmed",
"graph": "group_customer",
"completed": false,
"created_at": "2017-12-15T03:25:44-0800",
"updated_at": "2017-12-15T03:25:45-0800"
}
}Just like the responce to the creation of group_owner.
Step 4: Cancellations
Cancellations on group bookings are done in the same manner as applying any other action to a booking, however there are some small specifics that you need to be aware of.
For group bookings there are two kinds of cancellation:
Customer cancellation, where one of the bookers of seats cancels a seat booking.
Owner cancellation, where the creator of the group booking in this case the webinar, cancels the entire group booking.
Customer cancellation
Customer cancellation is done by using the action "cancel_by_customer" like so:
curl --request PUT \
--url https://api.timekit.io/v2/bookings/e1d7826c-ecaf-4e07-917b-7f3f7219e3f0/cancel_by_customer \
--user :live_api_key_7nzvc7wsBQQISLeFSVhROys9V1bUJ1z7 \
--data '{
"cancel_by_customer": {
"message": "Double booked. Sorry, Doc!"
}
}'
Please note the ID in the url is the same as the one form group_customer booking. Martys seat will now be available for others to book.
Owner cancellation
Likewise Doc Brown may have to cancel the entire webinar like so:
curl --request PUT \
--url https://api.timekit.io/v2/bookings/58190fc6-1ec0-4ebb-b627-7ce6aa9fc703/cancel \
--user :live_api_key_7nzvc7wsBQQISLeFSVhROys9V1bUJ1z7 \
--data '{
"cancel": {
"message": "Down with the flu, sorry! -Doc."
}
}'
Again please observe the ID in the url is the one for the group owner bookings.
Step 5: Managing the webinar.
If Doc Brown didn't get the flu, we're now close to launching the webinar, so Doc Brown needs to know who the attendees will be. We achieve this by using dynamic includes, in this case the relevant include is related_bookings.customers like so:
curl --request GET \
--url https://api.timekit.io/v2/bookings/58190fc6-1ec0-4ebb-b627-7ce6aa9fc703?include=related_bookings.customers \
--user :live_api_key_7nzvc7wsBQQISLeFSVhROys9V1bUJ1z7
And this will respond with something similar to this:
{
"data": {
"id": "d62ed7a1-0e57-4e98-a877-64d9ad7bcc16",
"state": "tentative",
"graph": "group_owner",
"completed": false,
"created_at": "2015-12-14T10:28:22-08:00",
"updated_at": "2015-12-14T10:28:22-08:00",
"related_bookings": [{
"id": "e1d7826c-ecaf-4e07-917b-7f3f7219e3f0",
"state": "confirmed",
"graph": "group_customer",
"completed": false,
"created_at": "2017-12-15T03:25:44-0800",
"updated_at": "2017-12-15T03:25:45-0800",
"customers": [{
"id": "e4f67f0f-458b-4a97-9954-5f4ad73cdc05",
"name": "Marty McFly",
"email": "marty.mcfly@timekit.io",
"timezone": "America/Los_Angeles"
}]
},
{
"id": "a2c913aa-a3b6-4221-a576-1804093e27fe",
"state": "confirmed",
"graph": "group_customer",
"completed": false,
"created_at": "2017-12-16T05:37:23-0800",
"updated_at": "2017-12-16T05:37:24-0800",
"customers": [{
"id": "bd1b06f6-2857-426c-9e86-175469def735",
"name": "Biff Tannen",
"email": "biff.tannen@timekit.io",
"timezone": "America/Los_Angeles"
}]
}]
}
}Now Doc Brown is ready to launch his webinar.
This concludes our tutorial on group bookings through the API. For a full reference please refer to our API reference.