Bookings are requests from external users to reserve spaces and resources through a BookingModule. They flow through a simple pipeline: pending → approved/denied (→ canceled). When a Booking is approved, it creates an associated Event in the Organization.
A Booking can include multiple BookingEvents (Booking.events). When approved, each BookingEvent can create an associated Event in the Organization.
BookingChangeRequests allow external users to request modifications to their approved Bookings, which administrators can then approve or deny.
Bookings support custom form fields configured at the BookingModule level, allowing you to collect specific information from bookers.
Submit a Booking
Submit a Booking request without authentication, i.e., as an end-user.
Request Body
titlestring · requiredTitle for the
Booking.submissionboolean · requiredWhether this booking was submitted by a non-admin user. Set to
truefor public submissions,falsefor admin-createdBookings.orgIdstring · uuid · requiredThe id of the
Organizationthat owns thisBooking.bookingModuleIdstring · uuid · requiredThe id of the
BookingModulethisBookingbelongs to.portalIdstring · uuid · requiredThe id of the
Portalassociated with thisBooking.contactobject · requiredAnswers to the contact portion of the booking form.
eventsobject[] · requiredThe events requested in this
Booking. ABookingcan include multiple events.
bookingStatusinteger · enumThe initial
Bookingstatus for admin-createdBookings. If submission istrue, has no effect.Value Name Description 0 PENDING The Bookingis awaiting admin approval1 APPROVED The Bookinghas been approved and anEventhas been created2 DENIED The Bookinghas been denied3 CANCELED The Bookinghas been canceledEnum values:0123customerIdstring · uuidOptional id of a
Customerto associate with thisBooking.contactIdstring · uuidOptional id of an existing
Contactto associate with thisBooking.requestNotestring · htmlA note to the
BookingModuleadmin explaining the request. Supports basic HTML tags and formatting.notificationobjectUsed to send an approval notification for admin-created
Bookings. Ignored if submission istrue.
Responses
The submitted Booking. Event will be absent if submission is true.
bookingobject · requiredThe submitted
Booking.
eventsobject[]The
Event(s) that were created or updated, if this was an admin-createdBooking.
Submit a BookingChangeRequest
Submit a BookingChangeRequest without authentication, i.e., as an end-user.
If the request is made for a pending Booking, the Booking will be directly updated with the requested changes. Otherwise, a BookingChangeRequest will be created.
Request Body
bookingIdstring · uuid · requiredThe id of the
Bookingto modify.cancellationboolean · requiredWhether this
BookingChangeRequestis to cancel theBooking.contactobject · requiredUpdated answers to the contact portion of the booking form (all fields optional).
titlestringOptional updated title for the
Booking.addedEventsobject[]New
BookingEvents to add to theBooking.updatedEventsobjectUpdates to existing
BookingEvents. Keys areBookingEventids; values are the fields to update.removedEventIdsstring[]Ids of
BookingEvents to remove from theBooking.requestNotestring · htmlA note to the
BookingModuleadmin explaining the request. Supports basic HTML tags and formatting.
Responses
The submitted BookingChangeRequest, or the updated Booking if the request was automatically applied.
changeRequestobjectbookingobject
List Bookings
Retrieves a map of all Bookings within your Organization.
You can optionally include the Events associated with the returned Bookings by using the returnEvents query parameter.
query Parameters
returnEventsbooleanWhether to include the
Eventsassociated with the returnedBookings.
Responses
A map of Booking ids to Bookings and potentially a list of Events associated with the Bookings.
bookingsobject · requiredA map of
Bookingids toBookings.
associatedEventsobject[]A list of
Eventsassociated with the returnedBookings.
Create a Booking
Creates a Booking based on the provided fields. Bookings created via this endpoint can optionally be based on an existing Event, create a new Event, or be created without an Event as PENDING requests (as if they were created by an end-user).
Note: This endpoint is only accessible to authenticated Users. Booking requests from end-users should be made via /bookings/submit.
Request Body
titlestring · requiredTitle for the
Booking.submissionboolean · requiredWhether this booking was submitted by a non-admin user. Set to
truefor public submissions,falsefor admin-createdBookings.orgIdstring · uuid · requiredThe id of the
Organizationthat owns thisBooking.bookingModuleIdstring · uuid · requiredThe id of the
BookingModulethisBookingbelongs to.portalIdstring · uuid · requiredThe id of the
Portalassociated with thisBooking.contactobject · requiredAnswers to the contact portion of the booking form.
eventsobject[] · requiredThe events requested in this
Booking. ABookingcan include multiple events.
bookingStatusinteger · enumThe initial
Bookingstatus for admin-createdBookings. If submission istrue, has no effect.Value Name Description 0 PENDING The Bookingis awaiting admin approval1 APPROVED The Bookinghas been approved and anEventhas been created2 DENIED The Bookinghas been denied3 CANCELED The Bookinghas been canceledEnum values:0123customerIdstring · uuidOptional id of a
Customerto associate with thisBooking.contactIdstring · uuidOptional id of an existing
Contactto associate with thisBooking.requestNotestring · htmlA note to the
BookingModuleadmin explaining the request. Supports basic HTML tags and formatting.notificationobjectUsed to send an approval notification for admin-created
Bookings. Ignored if submission istrue.
Responses
The submitted Booking and potentially the created or updated Event.
bookingobject · requiredThe submitted
Booking.
eventsobject[]The
Event(s) that were created or updated, if this was an admin-createdBooking.
Update a Booking
Updates the specified Booking by setting the values of the fields passed. Any fields not provided will be left unchanged. By design, you cannot change any properties of a Booking once it has been created besides the associated Customer and Contact.
path Parameters
bookingIdstring · uuid · requiredThe id of the
Booking.
Request Body
customerIdstring · uuidThe id of a
Customerto associate with theBooking, or an empty string to clear the association.contactIdstring · uuidThe id of a
Contactto associate with theBooking, or an empty string to clear the association.
Responses
The updated Booking.
bookingobject · required
Approve a Booking
Approves the specified pending Booking, changing its status to APPROVED, creating a linked Event, and sending an email notification to the booker.
path Parameters
bookingIdstring · uuid · requiredThe id of the
Booking.
Request Body
clientBookingLastUpdatedAtstring · date-time · requiredThe
lastUpdatedtimestamp of theBookingon the client. Used to prevent approval ofBookingsupdated by the end-user without the admin's knowledge.eventsobject[] · requiredOne entry per
BookingEventwith Event creation fields. Used to create theEvent(s) for the approved booking.notificationobject · requiredEmail notification details.
titlestringOptional new title for the
Booking.customerIdstring · uuidOptional id of a
Customerto associate with thisBooking.contactIdstring · uuidOptional id of a
Contactto associate with thisBooking.
Responses
The approved Booking and the newly created Event.
bookingobject · requiredeventsobject[] · requiredThe associated
Event(s) for the approved booking.
Deny a Booking
Denies the specified pending Booking, changing its status to DENIED and sending an email notification to the booker.
path Parameters
bookingIdstring · uuid · requiredThe id of the
Booking.
Request Body
clientBookingLastUpdatedAtstring · date-time · requiredThe
lastUpdatedtimestamp of theBookingon the client. Used to prevent denial ofBookingsupdated by the end-user without the admin's knowledge.notificationobject · requiredEmail notification details.
Responses
The denied Booking.
bookingobject · required
Cancel a Booking
Cancels the specified approved Booking, changing its status to CANCELED and either deletes the associated Event or changes its status to CANCELED.
path Parameters
bookingIdstring · uuid · requiredThe id of the
Booking.
Request Body
eventProcedureinteger · enum · requiredSpecifies how to handle the associated
Eventwhen canceling aBooking.Value Name Description 0 CANCEL Mark the Eventas canceled1 DELETE Delete the EvententirelyEnum values:01notificationobject · requiredEmail notification details.
Responses
The canceled Booking and potentially the associated Event, if it was canceled.
bookingobject · requiredeventsobject[] · requiredThe canceled events, or null if the events were deleted.
Approve a BookingChangeRequest
Approves the specified BookingChangeRequest, applying its changes to the Booking and sending an email notification to the booker. Deletes the BookingChangeRequest.
path Parameters
changeRequestIdstring · uuid · requiredThe id of the
BookingChangeRequest.
Request Body
notificationobject · requiredEmail notification details.
titlestringOptional updated title for the
Booking.addedEventsobject[]New
BookingEvents to add (asCreateBookingEventFields). Used when approving a change request that added booking events.updatedEventsobjectUpdates to existing
BookingEvents. Important; Keys areEventids (notBookingEventids); values are the fields to update.removedEventIdsstring[]Ids of
Events to remove (from the booking). Used when approving a change request that removed booking events.eventProcedureinteger · enumIf the
BookingChangeRequestis a cancellation, specifies whether to cancel or delete theEvent.Value Name Description 0 CANCEL Mark the Eventas canceled1 DELETE Delete the EvententirelyEnum values:01
Responses
The updated Booking and potentially the updated Event, if this was not a cancellation.
bookingobject · requiredeventsobject[] · requiredThe updated events, or null if the events were deleted as part of the change request.
Deny a BookingChangeRequest
Denies the specified BookingChangeRequest, rejecting the requested changes and sending an email notification to the booker. Deletes the BookingChangeRequest.
path Parameters
changeRequestIdstring · uuid · requiredThe id of the
BookingChangeRequest.
Responses
The BookingChangeRequest was successfully denied.