Rooms API

The Rooms API allows you to manage room inventory, status, and configuration.

Endpoints

List Rooms

GET /api/v1/rooms

Query Parameters:

Parameter	Type	Description
room_type_id	string	Filter by room type
floor	string	Filter by floor
status	string	Filter by status (VACANT, OCCUPIED, etc.)
hk_status	string	Filter by housekeeping status
is_active	boolean	Filter by active status
cursor	string	Pagination cursor
limit	integer	Results per page

Response:

{
  "data": [
    {
      "id": "room_101",
      "room_number": "101",
      "room_type": {
        "id": "rt_standard",
        "name": "Standard Room",
        "code": "STD"
      },
      "floor": "1",
      "building": "Main",
      "status": "VACANT",
      "fo_status": "VACANT",
      "hk_status": "CLEAN",
      "is_active": true,
      "features": ["CITY_VIEW", "BALCONY"],
      "current_guest": null
    },
    {
      "id": "room_201",
      "room_number": "201",
      "room_type": {
        "id": "rt_deluxe",
        "name": "Deluxe Room",
        "code": "DLX"
      },
      "floor": "2",
      "building": "Main",
      "status": "OCCUPIED",
      "fo_status": "OCCUPIED",
      "hk_status": "DIRTY",
      "is_active": true,
      "features": ["SEA_VIEW", "BALCONY", "BATHTUB"],
      "current_guest": {
        "id": "guest_abc123",
        "name": "John Doe",
        "reservation_id": "res_xyz789",
        "checkout_date": "2026-02-18"
      }
    }
  ],
  "pagination": {
    "cursor": "eyJpZCI6MTAwfQ==",
    "has_more": true
  }
}

Get Room

GET /api/v1/rooms/:id

Update Room Status

PUT /api/v1/rooms/:id/status

Request Body:

{
  "hk_status": "CLEAN",
  "notes": "Deep cleaned and inspected"
}

Room Status Summary

GET /api/v1/rooms/status-summary

Response:

{
  "data": {
    "total_rooms": 150,
    "out_of_order": 2,
    "out_of_service": 1,
    "available": 147,
    "by_status": {
      "VACANT_CLEAN": 45,
      "VACANT_DIRTY": 12,
      "OCCUPIED_CLEAN": 75,
      "OCCUPIED_DIRTY": 15
    },
    "by_room_type": {
      "rt_standard": {
        "total": 80,
        "vacant": 30,
        "occupied": 50
      },
      "rt_deluxe": {
        "total": 50,
        "vacant": 20,
        "occupied": 30
      },
      "rt_suite": {
        "total": 20,
        "vacant": 7,
        "occupied": 12
      }
    }
  }
}

Room Types

List Room Types

GET /api/v1/room-types

Response:

{
  "data": [
    {
      "id": "rt_standard",
      "code": "STD",
      "name": "Standard Room",
      "description": "Comfortable room with essential amenities",
      "max_occupancy": 2,
      "max_adults": 2,
      "max_children": 1,
      "base_rate": 4000.00,
      "size_sqm": 25,
      "bed_type": "QUEEN",
      "amenities": ["AC", "TV", "WIFI", "MINIBAR"],
      "images": [
        "https://cdn.hmpcloud.com/images/std_room_1.jpg"
      ],
      "room_count": 80,
      "is_active": true
    }
  ]
}

Create Room Type

POST /api/v1/room-types

Request Body:

{
  "code": "EXEC",
  "name": "Executive Room",
  "description": "Spacious room with work desk and premium amenities",
  "max_occupancy": 3,
  "max_adults": 2,
  "max_children": 1,
  "base_rate": 6500.00,
  "size_sqm": 35,
  "bed_type": "KING",
  "amenities": ["AC", "TV", "WIFI", "MINIBAR", "WORK_DESK", "COFFEE_MACHINE"]
}

Out of Order / Service

Set Room Out of Order

POST /api/v1/rooms/:id/out-of-order

Request Body:

{
  "reason": "AC repair required",
  "from_date": "2026-02-15",
  "to_date": "2026-02-17",
  "notes": "Technician scheduled for Feb 16"
}

Clear Out of Order

DELETE /api/v1/rooms/:id/out-of-order

Set Room Out of Service

POST /api/v1/rooms/:id/out-of-service

Request Body:

{
  "reason": "Deep cleaning",
  "from_date": "2026-02-15",
  "to_date": "2026-02-15",
  "return_to_inventory": true
}

Room Assignment

Get Assignable Rooms

GET /api/v1/rooms/assignable

Query Parameters:

Parameter	Type	Description
room_type_id	string	Filter by room type
arrival_date	date	Check-in date
departure_date	date	Check-out date
preferences	string[]	Guest preferences (HIGH_FLOOR, etc.)

Response:

{
  "data": [
    {
      "id": "room_405",
      "room_number": "405",
      "room_type": "Deluxe Room",
      "floor": "4",
      "hk_status": "CLEAN",
      "features": ["SEA_VIEW", "BALCONY"],
      "match_score": 95,
      "preference_matches": ["HIGH_FLOOR", "SEA_VIEW"]
    },
    {
      "id": "room_403",
      "room_number": "403",
      "room_type": "Deluxe Room",
      "floor": "4",
      "hk_status": "CLEAN",
      "features": ["CITY_VIEW", "BALCONY"],
      "match_score": 70,
      "preference_matches": ["HIGH_FLOOR"]
    }
  ]
}

Status Values

Front Office Status (fo_status)

Status	Description
VACANT	Room is not occupied
OCCUPIED	Guest is in house
OUT_OF_ORDER	Not available for sale
OUT_OF_SERVICE	Temporarily unavailable

Housekeeping Status (hk_status)

Status	Description
CLEAN	Room is clean and ready
DIRTY	Room needs cleaning
INSPECTED	Room cleaned and inspected
IN_PROGRESS	Cleaning in progress
OUT_OF_ORDER	Not available

Combined Status

Status	fo_status	hk_status
VACANT_CLEAN	VACANT	CLEAN
VACANT_DIRTY	VACANT	DIRTY
OCCUPIED_CLEAN	OCCUPIED	CLEAN
OCCUPIED_DIRTY	OCCUPIED	DIRTY

Related Documentation

• Reservations API
• Housekeeping Module