Skip to content
Docs
or

Retrieve booking IDs

A booking ID is a unique identifier for a specific Scheduler booking. A Configuration ID and booking ID are required to use all Bookings endpoints, and to use the Availability endpoint for round-robin events.

Configuration IDs and booking IDs are in the following standard UUID format, where x represents a hexadecimal digit:

xxxxxxxx-xxxx-Mxxx-Nxxx-xxxxxxxxxxxx

The section beginning with M indicates the UUID version (1, 2, 3, 4, or 5), and the section beginning with N indicates the variant (most commonly 8, 9, A, or B).

To retrieve a booking ID, you need to decode its booking reference. Scheduler creates a booking reference by combining a booking’s Configuration ID and booking ID with a salt. You can find the booking reference in the URL for rescheduling or cancellation pages, or by subscribing to Scheduler webhook triggers.

Decode booking reference

Follow these steps to decode a booking reference:

  1. Use a Base64 decoding function to convert the encoded string to a byte array. This array contains the concatenated bytes of the two original UUIDs, along with a salt.
  2. Extract the UUIDs from the byte array. Each UUID should be 16 bytes long.
  3. Extract the remainder as the salt.
  4. Insert hyphens to convert each 16-byte segment to the original UUID format. The first string is the Configuration ID, and the second is the booking ID.
  5. Replace all + and / characters with - and _, respectively. This converts the extracted salt to a URL-safe Base64 string.

The following code shows one way to decode a booking reference using JavaScript.

export function compactStringToUUIDs(compactString) {
  // Decode the Base64 string to a buffer.
  const buffer = Buffer.from(compactString, 'base64');


  // Extract UUIDs (16 bytes each).
  const uuidBytes1 = buffer.slice(0, 16);
  const uuidBytes2 = buffer.slice(16, 32);


  // Extract the remainder as the salt.
  const salt = buffer.slice(32);


  // Function to convert a buffer to UUID string format.
  function bufferToUUID(buffer) {
    const hex = buffer.toString('hex');
    return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20)}`;
  }
  // Convert buffers to UUID strings.
  const uuid1 = bufferToUUID(uuidBytes1);
  const uuid2 = bufferToUUID(uuidBytes2);


  // Convert salt buffer to URL-safe Base64 string.
  const b64EncodedSalt = salt.toString('base64').replace(/\+/g, '-').replace(/\//g, '_');


  return [uuid1, uuid2, b64EncodedSalt];
}

Extract booking references from Scheduling Component

The Scheduling Component emits a bookingRefExtracted event when you pass one of the following properties:

  • cancelBookingRef
  • organizerConfirmationBookingRef
  • rescheduleBookingRef

You can listen for the bookingRefExtracted event to retrieve booking IDs.

schedulingComponent.addEventListener('bookingRefExtracted', (e) => {
  console.log(e.detail); // { configurationId: rescheduleConfigId, bookingId: rescheduleBookingId }
});