> For the complete documentation index, see [llms.txt](https://docs.snapfix.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.snapfix.com/product/features/rooms/room-status.md).

# Room status

{% hint style="info" %}
Draft, written by an agent and not yet checked by a person ([how to read these docs](https://docs.snapfix.com/how-to-read.md)). [Source on GitHub](https://github.com/snapfix/docs/blob/main/product/features/room-status.md).
{% endhint %}

**Room status** shows every **room** of a site with its **main status**, its optional **secondary status**, its **priority** and its reservation details. People change one room or several at once, and filter the rooms by status and priority. The statuses come from the site's **status catalogue**. A site's property management system (**PMS**) can change them too, and changes made in Snapfix go back to it. Some status changes start housekeeping work.

## Rules

### Statuses and priorities

* A room has one main status and may have one secondary status. Both come from the site's catalogue, which is grouped in sections. A status from another site's catalogue is refused ([room status sections](https://docs.snapfix.com/engineering-reference/api/rooms.md#room-status-section-object), [Room and area permissions](https://docs.snapfix.com/engineering-reference/api/rooms.md#room-and-area-permissions)).
* A new building gets the sections "Cleaning status", "Operation status" and "Other", and default main statuses such as "STAY-OVER", "DEPARTURE", "CLEANING", "CLEANED", "INSPECTED", "DND", "MAINTENANCE", "OUT OF ORDER" and "OUT OF SERVICE" (api\_php\_live\_v2 @ ef3c4319f6, `resources/other/default_building_sections.php`, `resources/other/default_building_room_statuses.php`). Each status has a colour name, an icon and a read-only flag ([room status object](https://docs.snapfix.com/engineering-reference/api/rooms.md#room-status-object)).
* A read-only status is shown but can't be picked on the web, on Android or in the iOS single-room sheet. The iOS multi-select sheet and the API don't check it ([Room status](https://docs.snapfix.com/how-the-apps-work/screens/rooms/room-status.md#states)).
* Statuses can be set but not cleared. Once a room has a secondary status, it can be replaced but not removed; leaving it out keeps the old one \[[ASK-87](https://github.com/snapfix/docs/blob/main/ASK.md#ask-87-should-staff-be-able-to-clear-a-rooms-secondary-status)] ([Room status](https://docs.snapfix.com/how-the-apps-work/screens/rooms/room-status.md#inputs)).
* On the web, a secondary status needs a main status first. The apps allow a secondary status alone.
* Priority is high (the star "1"), medium (the star "2") or none. Choosing the set star again clears it. The API knows more levels, such as low and emergency, but no screen offers them ([Room status](https://docs.snapfix.com/how-the-apps-work/screens/rooms/room-status.md#inputs)).
* The reservation shown with a room comes from the PMS guest stays, not from the status. Its occupancy reads "Occupied" or "Vacant" from the secondary status's name when that says so, and otherwise from today's stay ([reservation object](https://docs.snapfix.com/engineering-reference/api/rooms.md#reservation-object)).

### Who can change

* Every member of the site can see and change any room's status and priority. No screen checks a role, and the API checks only site membership, any role; who should be allowed is open \[[ASK-81](https://github.com/snapfix/docs/blob/main/ASK.md#ask-81-who-may-create-rename-and-delete-rooms-and-areas-and-change-their-priority-and-status)] ([Room status](https://docs.snapfix.com/how-the-apps-work/screens/rooms/room-status.md)).
* The apps save changes on the device and send them with the sync, which checks no membership.
* The building's "manual room status" flag is stored, but nothing reads it, so no setting stops changes by hand \[[ASK-84](https://github.com/snapfix/docs/blob/main/ASK.md#ask-84-what-should-the-building-setting-manual-room-status-do)].
* No plan check applies \[[ASK-85](https://github.com/snapfix/docs/blob/main/ASK.md#ask-85-is-room-status-a-paid-feature)].

### Changing one room or several

* One room: the web edits it in a dialog and saves priority and status together with "Save". The apps save a status on the tap; iOS saves a priority when the sheet closes, Android on the tap. Changing the main status keeps the secondary status ([Room status](https://docs.snapfix.com/how-the-apps-work/screens/rooms/room-status.md#actions)).
* Several rooms: the web changes the selected rooms, the loaded rooms, or every room that matches the search and filters ("Select All Rooms"). The apps change the rooms selected with a long press ([Room status](https://docs.snapfix.com/how-the-apps-work/screens/rooms/room-status.md#actions)).
* In a bulk status change, the web sets a main status, a secondary status or both; the apps set one status ([Room status](https://docs.snapfix.com/how-the-apps-work/screens/rooms/room-status.md#status-of-several-rooms)).
* A bulk change skips rooms that already have the new priority or main status. A room on the chosen main status therefore doesn't get the chosen secondary status either, and the count leaves it out.
* A bulk change has no size limit, and its per-room work runs inside the request.

### What a status change does

* Every web status change writes a row to the room status change log. A priority change writes none ([Status change side effects](https://docs.snapfix.com/engineering-reference/api/rooms.md#status-change-side-effects)).
* **PMS.** About 10 seconds after a web change, each change goes to every PMS integration of the site, unless a newer change for the same room has overtaken it. A change from the apps goes only to the PMS the room is mapped to, the first of seven mapping tables that matches \[[ASK-83](https://github.com/snapfix/docs/blob/main/ASK.md#ask-83-which-room-status-changes-should-create-inspections-and-cleaning-tasks-and-reach-the-pms)]. A change that comes from the PMS is not sent back ([Status change side effects](https://docs.snapfix.com/engineering-reference/api/rooms.md#status-change-side-effects), [`save_pri_log_roomstatuschange`](https://docs.snapfix.com/engineering-reference/api/rooms.md#post-actionsave_pri_log_roomstatuschange)).
* **Return inspection.** When housekeeping is on for the site and a web change moves a room from "OUT OF ORDER" or "OUT OF SERVICE" (as its main or secondary status, in any letter case) to available statuses, the server creates a red inspection task for the room, unless the room has an open one. It goes to the inspection group of the site's room status rules, or else to the first group whose name starts with "HouseKeeping"; with neither, no task is created and nothing is shown. The caller is added to that group as an admin when they are not in it ([Status change side effects](https://docs.snapfix.com/engineering-reference/api/rooms.md#status-change-side-effects), [Inspections](https://docs.snapfix.com/product/features/housekeeping/inspections.md)).
* App changes create no inspection, and neither web nor app changes create cleaning tasks \[[ASK-83](https://github.com/snapfix/docs/blob/main/ASK.md#ask-83-which-room-status-changes-should-create-inspections-and-cleaning-tasks-and-reach-the-pms)].
* **PMS changes.** A PMS status change for one room creates the return inspection in the same way. Otherwise, when housekeeping is on and the site has an admin user, it runs the housekeeping task generator for that room, which creates or archives its cleaning tasks by the site's rules (api\_php\_live\_v2 @ ef3c4319f6, `app/Http/Controllers/v1/Versions/v1_0/Internal/InternalController.php:85-158`; [Cleaning tasks](https://docs.snapfix.com/product/features/housekeeping/cleaning-tasks.md)).
* **Room status rules.** A site's rules ([`tPri_RoomStatus_TaskRules`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_roomstatus_taskrules.md)) name a main status, a secondary status or both, and say whether to create a cleaning task, an inspection or both, each with its group and checklist. No screen sets them: the PMS setup actions write them, and staff can add one with a console command (php-apis @ 238ca4414e, `html/api/snapfix/web/index.php:692-891`; api\_php\_live\_v2 @ ef3c4319f6, `app/Console/Commands/AddRoomTaskRuleForParentCommand.php:31-35`). A room with no rule for its statuses gets the building's first rule's groups in the housekeeping create form \[[ASK-82](https://github.com/snapfix/docs/blob/main/ASK.md#ask-82-should-a-room-whose-status-has-no-task-rule-get-the-buildings-first-rule)] ([`GET /v1/app/rooms/{uuid}/hk-businesses`](https://docs.snapfix.com/engineering-reference/api/housekeeping.md#get-v1approomsuuidhk-businesses)).
* Starting a cleaning task, or finishing a cleaning or inspection task, can set the room's status when its rule says so ([Cleaning tasks](https://docs.snapfix.com/product/features/housekeeping/cleaning-tasks.md)).

### Lists and filters

* The list shows every room with its statuses and priority. The web searches on the server, also by main status name; the apps search their device copy by room or status name ([Room status](https://docs.snapfix.com/how-the-apps-work/screens/rooms/room-status.md#inputs)).
* Rooms can be filtered by priority and by status, section by section. The web filters on the server and keeps the filter per site in the browser; iOS keeps it per site on the device; the apps filter their device copy ([Room status](https://docs.snapfix.com/how-the-apps-work/screens/rooms/room-status.md#filter)).

## Flow

```mermaid
flowchart LR
  open["Fix: Room Status"] --> filter["Filter by priority or status"]
  open --> one["One room: priority and statuses"]
  open --> many["Select rooms, or all that match"]
  one --> save["Save"]
  many --> save
  save --> log["Status change logged"]
  log --> pms["Sent to the site's PMS after about 10 seconds"]
  log --> ret{"Back from out of order or out of service, housekeeping on?"}
  ret -->|yes| insp["Inspection task, unless one is open"]
  app["App change on the device"] --> sync["Sync: the room's mapped PMS only, no inspection"]
  pmsin["PMS status change"] --> gen["Housekeeping tasks for the room, by the rules"]
```

## Platforms

| Capability                             | Web                                              | iOS                                                    | Android                                 |
| -------------------------------------- | ------------------------------------------------ | ------------------------------------------------------ | --------------------------------------- |
| Where                                  | Fix, "Rooms" tab, "Room Status" option           | Fix, "Room Status"                                     | Fix, the "Room Tasks" chip tapped again |
| Change one room                        | Dialog with "Save"                               | Sheet: a tap saves the status, the star saves on close | Sheet: a tap saves                      |
| Change several rooms                   | Selected, loaded, or all that match              | Long press, selected rooms                             | Long press, selected rooms              |
| Main and secondary together in bulk    | Yes                                              | One status                                             | One status                              |
| Secondary status without a main status | No                                               | Yes                                                    | Yes                                     |
| Reservation details                    | Yes                                              | Yes                                                    | Yes                                     |
| Filters                                | Drawer, on the server                            | Sheet, kept per site                                   | Sheet                                   |
| Changes reach                          | Every PMS of the site, and the return inspection | The room's mapped PMS                                  | The room's mapped PMS                   |
| Offline                                | No                                               | Changes synced later                                   | Changes synced later                    |

Android also has a separate room status screen on the hidden Track tab, which opens only when the app restores Track as the last tab \[[ASK-10](https://github.com/snapfix/docs/blob/main/ASK.md#ask-10-which-differences-between-the-ios-and-android-apps-are-intended)].

## Screens

* [Room status](https://docs.snapfix.com/how-the-apps-work/screens/rooms/room-status.md): the list, one room's dialog or sheet, the multi-room actions and the filters.
* [Room tasks](https://docs.snapfix.com/how-the-apps-work/screens/rooms/room-tasks.md): the other view of the same tab.
* [Room](https://docs.snapfix.com/how-the-apps-work/screens/rooms/room.md): a room's tasks, opened from its status dialog or sheet.

## API and data

* [Rooms API](https://docs.snapfix.com/engineering-reference/api/rooms.md):
  * The catalogue: [`GET /v1/app/parents/{uuid}/room-statuses`](https://docs.snapfix.com/engineering-reference/api/rooms.md#get-v1appparentsuuidroom-statuses).
  * The list with its filters: [`POST /v1/app/rooms/list`](https://docs.snapfix.com/engineering-reference/api/rooms.md#post-v1approomslist); one room with its reservation: [`GET /v1/app/rooms/{uuid}`](https://docs.snapfix.com/engineering-reference/api/rooms.md#get-v1approomsuuid).
  * One room: [`PUT /v1/app/rooms/{uuid}/status`](https://docs.snapfix.com/engineering-reference/api/rooms.md#put-v1approomsuuidstatus) and, for the priority, [`PUT /v1/app/rooms/{uuid}`](https://docs.snapfix.com/engineering-reference/api/rooms.md#put-v1approomsuuid).
  * Several rooms: [`POST /v1/app/rooms/status/multi`](https://docs.snapfix.com/engineering-reference/api/rooms.md#post-v1approomsstatusmulti), [`POST /v1/app/rooms/status/all`](https://docs.snapfix.com/engineering-reference/api/rooms.md#post-v1approomsstatusall), [`POST /v1/app/rooms/priority/multi`](https://docs.snapfix.com/engineering-reference/api/rooms.md#post-v1approomsprioritymulti) and [`POST /v1/app/rooms/priority/all`](https://docs.snapfix.com/engineering-reference/api/rooms.md#post-v1approomspriorityall).
  * The apps' sync: [`?action=save_pri_room`](https://docs.snapfix.com/engineering-reference/api/rooms.md#post-actionsave_pri_room) and [`?action=save_pri_log_roomstatuschange`](https://docs.snapfix.com/engineering-reference/api/rooms.md#post-actionsave_pri_log_roomstatuschange).
* [Integrations API](https://docs.snapfix.com/engineering-reference/api/integrations.md): the PMS services post room status changes to `POST /v1/internal/rooms/{uuid}/status` and `POST /v1/internal/rooms/status/multi`.
* [`POST /api/reports/room-status-log`](https://docs.snapfix.com/engineering-reference/api/housekeeping.md#post-apireportsroom-status-log): the last seven days of status changes, for the Ops Dashboard's "Activity Log".
* Tables: [`tPri_Room`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_room.md) (status links and priority), [`tPri_BuildingRoomSection`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_buildingroomsection.md), [`tPri_BuildingRoomStatusMain`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_buildingroomstatusmain.md) and [`tPri_BuildingRoomStatusSecondary`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_buildingroomstatussecondary.md) (the catalogue), [`tPri_RoomStatusIcon`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_roomstatusicon.md), [`tPri_Log_RoomStatusChange`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_log_roomstatuschange.md) (the log), [`tPri_RoomStatus_TaskRules`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_roomstatus_taskrules.md) (the rules), [`tPri_RoomGuestStatus`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_roomgueststatus.md) and [`tPri_RoomGuests`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_roomguests.md) (the stays behind the reservation), [`tPri_Building`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_building.md) (the housekeeping and manual status flags).

## Depends on

* [Rooms and areas](https://docs.snapfix.com/product/features/rooms/rooms-and-areas.md): the rooms, on the same Rooms tab.
* [PMS integrations](https://docs.snapfix.com/product/features/integrations/pms-integrations.md): statuses come from and go back to the PMS; reservations and occupancy come from it.
* [Cleaning tasks](https://docs.snapfix.com/product/features/housekeeping/cleaning-tasks.md) and [Inspections](https://docs.snapfix.com/product/features/housekeeping/inspections.md): the rules create them, a return from out of order creates an inspection, and a task's start or finish can set a status.
* [Groups](https://docs.snapfix.com/product/features/groups/groups.md) and [Group members](https://docs.snapfix.com/product/features/groups/group-members.md): site membership decides who may change statuses on the server; the return inspection goes to a housekeeping group.
* [Ops dashboard](https://docs.snapfix.com/product/features/reports/ops-dashboard.md): the room status log.
* [Snapfix AI](https://docs.snapfix.com/product/features/ai/snapfix-ai.md): the assistant lists rooms by status.
* Notifications: none; room status changes send no pushes.

## Edge cases

* **Refused save (web):** a refused change in the single-room dialog still closes it as saved, and the card shows the new values until the next load. A refused bulk change shows the error alert and keeps its dialog open ([Room status](https://docs.snapfix.com/how-the-apps-work/screens/rooms/room-status.md#states)).
* **Unknown or foreign status:** an unknown status fails validation; a status from another site's catalogue answers "Access denied" ([`PUT /v1/app/rooms/{uuid}/status`](https://docs.snapfix.com/engineering-reference/api/rooms.md#put-v1approomsuuidstatus)).
* **Renamed statuses:** "OUT OF ORDER" and "OUT OF SERVICE" are matched by name, so a site that renames them gets no return inspection.
* **No admin user:** a PMS status change creates no housekeeping tasks for a site without an admin user.
* **Site with no building:** the catalogue and the bulk changes answer "Resource not found" ([Room and area permissions](https://docs.snapfix.com/engineering-reference/api/rooms.md#room-and-area-permissions)).
* **Empty list (web):** a site with no rooms, or a search or filter that matches nothing, shows the Room Tasks placeholder, which talks about tasks, not statuses. A failed first page reads "Room Status (Undefined)".
* **Old priority flag:** a room with the old priority flag reads as high priority, but filters and bulk changes treat it as none.
* **Offline:** the apps save changes on the device and send them when online; the web needs a connection.
* **Several sites:** each site has its own catalogue; a reservation's guest names can be read by anyone signed in who knows the room's ID.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.snapfix.com/product/features/rooms/room-status.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
