Version:
Only show these results:

Retrieve booking IDs

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

To retrieve a booking ID, you need to decode the corresponding booking reference. Nylas Scheduler creates a booking reference by combining the associated configuration ID and the booking ID, along with a salt. You can find the booking reference in the rescheduling or cancellation page URL, or by subscribing to the Scheduler webhook triggers.

In this tutorial, you'll learn how to retrieve a booking ID by decoding its corresponding booking reference.

UUID format

Configuration IDs and booking IDs are in UUID format. The standard UUID format is:

xxxxxxxx-xxxx-Mxxx-Nxxx-xxxxxxxxxxxx
  • xxxxxxxx: 8 hexadecimal digits
  • xxxx: 4 hexadecimal digits
  • Mxxx: 4 hexadecimal digits, where the first digit (M) indicates the UUID version (1, 2, 3, 4, or 5)
  • Nxxx: 4 hexadecimal digits, where the first digit (N) indicates the variant (most commonly 8, 9, A, or B)
  • xxxxxxxxxxxx: 12 hexadecimal digits

Decode booking references

To decode a booking reference, follow these steps:

  1. Use a Base64 decoding function to convert the encoded string back into a byte array.
    This array contains the concatenated bytes of the two original UUIDs along with a salt.
  2. Extract the UUIDs.
    The decoded byte array should be 32 bytes long (16 bytes for each UUID).
  3. Extract the remainder as the salt.
  4. Insert hyphens to convert each 16-byte segment back into its original UUID format.
    The first string is the configuration ID, and the second string is the booking ID.
  5. Replace + and / with - and _ to convert 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
  const b64EncodedSalt = salt.toString('base64').replace(/\+/g, '-').replace(/\//g, '_');
  
  return [uuid1, uuid2, b64EncodedSalt];
}

Grab booking references from the Scheduling component

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

  • rescheduleBookingRef
  • cancelBookingRef
  • organizerConfirmationBookingRef

You can listen to the bookingRefExtracted event to retrieve the booking ID.

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