Updated by Kate Santo
Bookings are posts of type event that allow users to reserve themselves a slot. This slot might be for a meeting room in a workplace app, a parking space or a shared space in a property app, or a sports pitch in a community engagement app.
Find out more about bookings in this guide.
See for yourself
- You can download the iOS or Android app on your phone to follow this journey along. And you can also log in or sign up to the web app here
- You can also follow along by checking out the images or code snippets in this guide
- And you will find the relevant endpoints linked and explained in this guide, but the full API is documented in Swagger UI
- For bookings to display in the UI, the padoq needs its
qrEnabledparameters setting to
true. This can only be done by an admin as padoqs don't default to these settings
Bookings are event posts with specific bits of data attached. In broad terms, an event is a post with structured content that includes information like
amount (if the event is paid),
frequency (if the event is recurrent) or
maxAttendees (to limit how many people can attend the event). A booking will have properties like
frequency, but also properties like
isAppointment (which has a value of
true, differentiating a booking from a standard event).
There's a property in a member's profile that interacts with bookings:
bookingLimit which defines how many hours the member can book rooms (or any other entities) for.
And, in the padoq, the
bookingInfo property defines the size of the bookable time slots:
In that example, members can book a maximum of 3 hours in any 24 hour period, and 12 hours in any 28 day period. In property apps, this ensures all tenants have fair access to bookable rooms and services, because not one tenant can book a room for excessive periods of time.
In a workplace app where meeting rooms can be booked, each room is set up as a calendar user. This ensures that the same room can't be booked twice at the same time, for example.
One of the key properties in a padoq is
permittedPostTypes, which sets the types of posts members can create. Events, like bookings, are not permitted as default. The padoq admin needs to add events to the list of
permittedPostTypes to allow members to create bookings.
Creating a booking
The process to create a booking is the same as the process to create a post. The user needs to be authenticated in the app, and the app needs to allow members to create posts overall and events in particular.
Then, the createPost endpoint is called. It takes 2 parameters:
name of the padoq to create the post in and
role, which optionally sets the user's role. The data sent through the UI (either by a member if the padoq allows it or by an admin in the Super Admin page) will generate a booking that might look like this when viewed through the browser:
DESCRIPTION:MeetingRoomS1 booked by JaneSmith
Bookings are displayed via the getPosts endpoint with some parameters:
nameof the padoq we are getting posts for
Accept: the type of response the endpoint accepts. In this case, it's data of type text/calendar, as opposed to the JSON format most endpoints take
postStatus(optional): this allows to only view bookings that are open or cancelled
Updating and deleting bookings is done via the editPost and deletePost endpoints. In the Super Admin page, bookings are deleted via this option in the UI (see 'cancel booking' button on the bottom-right corner):
On mobile, members can edit and cancel their bookings (referred to as 'events' here) via an overlay menu:
Beyond editing and deleting, admins can limit how many times a padoq member can make bookings. This is done via the updatePersonaBookingLimit. A booking limit of 0, for example, means that the user can't make bookings in that padoq:
A booking limit of 1750, for example means that the user can book a maximum of 1750 hours in that padoq: