Real-Time Room Status Webhook

room.occupancy.updated

---

The room occupancy webhook sends real-time events whenever a room’s occupancy changes, such as guest check-in or check-out. It is designed for partners that need immediate, event-driven updates, including Smart Locks providers, Smart TVs, guest experience platforms, IoT devices, and alarm or safety systems. For example, a smoke detector may be activated when a guest is present and deactivated when the room is vacant.

The webhook reports the room state using only two possible values: occupied = true or occupied = false.

The most important parameter is occupied, as it is the most reliable indicator of whether a room is currently occupied. Reservation status may not always reflect the actual room state, so partners that rely on real-time occupancy should use the occupied field and not the reservation status.

The webhook can be used on its own, or together with the complementary Real-Time Room Status Inquiry API when additional context or a full snapshot is needed (optional).

---

Payload

---

Main Payload

Field	Type	Format / Example	Description
reservationNumber	String	"007004415"	Minihotel reservation number.
status	String	"IN", "OK", "OUT"	Current reservation status at the time of the event.
rooms	Array	See rooms[] below	Array of rooms included in the occupancy change event.
timestamp	String	yyyy-MM-dd HH:mm:ss / "2026-02-03 00:03:29"	UTC datetime indicating when the event/change was generated.

Rooms

Field	Type	Format / Example	Description
roomNumber	String	"0101"	Room number.
guestFirstName	String	"John"	Guest first name.
guestLastName	String	"Doe"	Guest last name.
countryCode	String	"US"	Guest country code, usually ISO 2-letter country code.
idNumber	String	"123456789"	Guest ID or passport number, when available.
email	String	"[email protected]"	Guest email address, when available.
phone	String	"[phone]"	Guest phone number, when available.
checkInDate	String	yyyy-MM-ddTHH:mm:ss / "2026-02-03T15:00:00"	Reservation check-in datetime.
checkOutDate	String	yyyy-MM-ddTHH:mm:ss / "2026-02-05T11:00:00"	Reservation check-out datetime.
occupied	Boolean	true / false	Indicates whether the room is currently occupied.

---

Payload examples

JSON

{
  "eventID": "56e39148-f14c-4135-a28e-3bae1489aa2a",
  "notificationID": 5,
  "hotelCode": "sandbox",
  "notificationType": "room.occupancy.updated",
  "payload": {
    "reservationNumber": "007004415",
    "status": "IN",
    "rooms": [
      {
        "roomNumber": "0101",
        "guestFirstName": "John",
        "guestLastName": "Doe",
        "countryCode": "US",
        "idNumber": "123456789",
        "email": "[email protected]",
        "phone": "[phone]",
        "checkInDate": "2026-02-03T15:00:00",
        "checkOutDate": "2026-02-05T11:00:00",
        "occupied": true
      }
    ],
    "timestamp": "2026-02-03 00:03:29"
  }
}

JSON

{
  "eventID": "26e39345-a14b-1567-b38f-4bbe1466bb3b",
  "notificationID": 6,
  "hotelCode": "sandbox",
  "notificationType": "room.occupancy.updated",
  "payload": {
    "reservationNumber": "007004415",
    "status": "OK",
    "rooms": [
      {
        "roomNumber": "0101",
        "guestFirstName": "Jane",
        "guestLastName": "Smith",
        "countryCode": "US",
        "idNumber": "123456789",
        "email": "[email protected]",
        "phone": "[phone]",
        "checkInDate": "2026-02-01T15:00:00",
        "checkOutDate": "2026-02-03T11:00:00",
        "occupied": false
      }
    ],
    "timestamp": "2026-02-03 00:05:22"
  }
}

---

Scenarios

This webhook is triggered whenever the occupancy state of a room changes for the current day.

In all scenarios below:

• The affected room must correspond to today’s date
• The room must enter or leave the IN (checked-in / occupied) state

---

Trigger Scenarios

The webhook will be triggered in the following situations:

1. Arrival activates occupancy today
   If a reservation becomes active today and the room is checked IN, the webhook is triggered.
   This applies when the arrival date is today, or when the arrival date is in the past and the room status changes to IN today.

2. Ongoing stay covering today
   If a reservation spans multiple days and today falls within the stay, and the room is marked IN, the webhook is triggered.
   Example: Arrival was two days ago, and the departure date is extended to tomorrow or later while the room remains IN.

3. Room status changes to IN
   If a specific room status is manually changed to IN, and that room is relevant for today, the webhook is triggered.

4. Reservation status changes to IN
   If a reservation status change results in all rooms being marked IN, the webhook is triggered only for rooms active today.

5. Occupancy ends today
   If a room (or reservation) that is IN today changes to OUT (or any non-occupied state), the webhook is triggered with: occupied = false

6. Room reassignment during an active stay
   If a room that is IN today is moved or reassigned to another room, the webhook is triggered.

7. Guest data changes during active occupancy
   If guest first/last name is updated for a room that is IN today, the webhook is triggered.

---

📘

Note: This webhook only sends events for rooms relevant to today’s occupancy, and reflects real-time occupancy state transitions.