Skip to content
Nylas Docs

Retrieve booking IDs

A booking ID is a unique identifier for a specific booking. The Availability endpoint for round-robin events and all Bookings endpoints require both a configuration ID and a booking ID. To use a single string to make the frontend code cleaner, 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 URL of the email notification sent at the time of booking. For example, https://book.nylas.com/us/cancel/FMfcgzGxSlVHnZBcBwnfPWvtvjZjpqbZ.

In this tutorial, you’ll learn how to decode the corresponding booking reference to retrieve a booking ID.

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 }
});