> 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/engineering-reference/api/rooms.md).

# Rooms API

{% 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/spec/api/rooms.md).
{% endhint %}

Rooms and areas inside a site: creating, listing, changing and deleting them, the room status catalog, room status and priority changes, and the "viewed" records behind the counts of tasks with new activity. The mobile apps read and write the same rows through php-apis sync actions.

A **room** is a row of [`tPri_Room`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_room.md) and an **area** a row of [`tPri_Area`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_area.md); both belong to the site's building ([`tPri_Building`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_building.md)). A room's status is two links: a main status and an optional secondary status ([`tPri_BuildingRoomStatusMain`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_buildingroomstatusmain.md), [`tPri_BuildingRoomStatusSecondary`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_buildingroomstatussecondary.md)), each in one of the building's room sections. Tasks link to rooms and areas through [`tPri_JobRoom`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_jobroom.md) and [`tPri_JobArea`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_jobarea.md); setting those links, and a room's or area's own task list, are in the [Tasks API](https://docs.snapfix.com/engineering-reference/api/tasks.md#post-v1apptasksroom-add).

* **Services:** `api_php_live_v2` at `https://z4.snapfix.com` (`/v1/app/rooms`, `/v1/app/areas`, `/v1/app/parents/{uuid}/room-statuses`); `php-apis` at `https://z1.snapfix.com/api/snapfix/index.php`. Other environments: [Services and hosts](https://docs.snapfix.com/engineering-reference/api.md#services-and-hosts).
* **Auth:** api\_php\_live\_v2: user token (authpy access JWT in `Authorization: Bearer`). The reads check nothing beyond the token, so any signed-in user can read any site's rooms, areas, statuses and room reservations by ID. The writes check only that the caller belongs to the site; only the two bulk deletes need a site admin ([Room and area permissions](#room-and-area-permissions)). php-apis: user token (Bearer JWT, if `JWT_AUTH_ENABLED` is on \[[ASK-12](https://github.com/snapfix/docs/blob/main/ASK.md#ask-12-which-settings-do-the-production-api-servers-use)]); actions use the `user_uuid` in the request, not the token's user, and check no access to the sites, rooms or rows they name.
* **Used by:** web\_app\_v2 ([Room tasks](https://docs.snapfix.com/how-the-apps-work/screens/rooms/room-tasks.md), [Room status](https://docs.snapfix.com/how-the-apps-work/screens/rooms/room-status.md), [Areas](https://docs.snapfix.com/how-the-apps-work/screens/rooms/areas.md), the [room](https://docs.snapfix.com/how-the-apps-work/screens/rooms/room.md) and [area](https://docs.snapfix.com/how-the-apps-work/screens/rooms/area.md) task lists, [Areas & rooms](https://docs.snapfix.com/how-the-apps-work/screens/rooms/areas-and-rooms.md), the room and area pickers of tasks, filters and the planner, the housekeeping create-task dialog), iOS and Android (site download and sync), snapfix\_ai\_agent (Simon: room and area search, room status); 7 of the 41 endpoints have no caller.
* **Answers:** api\_php\_live\_v2 answers `{status, message, data}`; the errors every endpoint shares (`401`, `409`, `428`, `422`, `404`, `429`, `500` and the blocked-caller `400`) are in the [Tasks API](https://docs.snapfix.com/engineering-reference/api/tasks.md#common-errors). php-apis answers `{result, message, data, serverTs}`, with failures as HTTP `200` and `result: false` ([API conventions](https://docs.snapfix.com/engineering-reference/api.md#responses)).

The product: [Rooms and areas](https://docs.snapfix.com/product/features/rooms/rooms-and-areas.md), [Room status](https://docs.snapfix.com/product/features/rooms/room-status.md).

| Method | Path                                                                                               | Service            | Purpose                                                                   |
| ------ | -------------------------------------------------------------------------------------------------- | ------------------ | ------------------------------------------------------------------------- |
| POST   | [`/v1/app/areas`](#post-v1appareas)                                                                | api\_php\_live\_v2 | Create areas                                                              |
| POST   | [`/v1/app/areas/delete/multi`](#post-v1appareasdeletemulti)                                        | api\_php\_live\_v2 | Delete several areas                                                      |
| POST   | [`/v1/app/areas/get-updates`](#post-v1appareasget-updates)                                         | api\_php\_live\_v2 | Count each area's tasks with new activity since the caller last viewed it |
| POST   | [`/v1/app/areas/list`](#post-v1appareaslist)                                                       | api\_php\_live\_v2 | List a site's areas                                                       |
| GET    | [`/v1/app/areas/mark-as-visited/{areaUuid}`](#get-v1appareasmark-as-visitedareauuid)               | api\_php\_live\_v2 | Record that the caller viewed an area                                     |
| POST   | `/v1/app/areas/priority/all`                                                                       | api\_php\_live\_v2 | Set the priority of all areas (no caller)                                 |
| POST   | `/v1/app/areas/priority/multi`                                                                     | api\_php\_live\_v2 | Set the priority of several areas (no caller)                             |
| GET    | [`/v1/app/areas/templates/list`](#get-v1appareastemplateslist)                                     | api\_php\_live\_v2 | List the area name templates                                              |
| GET    | [`/v1/app/areas/{uuid}`](#get-v1appareasuuid)                                                      | api\_php\_live\_v2 | Get an area                                                               |
| PUT    | [`/v1/app/areas/{uuid}`](#put-v1appareasuuid)                                                      | api\_php\_live\_v2 | Change an area                                                            |
| DELETE | [`/v1/app/areas/{uuid}`](#delete-v1appareasuuid)                                                   | api\_php\_live\_v2 | Delete an area                                                            |
| GET    | [`/v1/app/areas/{uuid}/business/{businessUuid}/jobs`](#get-v1appareasuuidbusinessbusinessuuidjobs) | api\_php\_live\_v2 | List an area's tasks in a group                                           |
| GET    | [`/v1/app/areas/{uuid}/businesses`](#get-v1appareasuuidbusinesses)                                 | api\_php\_live\_v2 | List the groups that have tasks in an area                                |
| GET    | [`/v1/app/parents/{uuid}/room-statuses`](#get-v1appparentsuuidroom-statuses)                       | api\_php\_live\_v2 | List a site's room statuses, by section                                   |
| POST   | [`/v1/app/rooms`](#post-v1approoms)                                                                | api\_php\_live\_v2 | Create rooms                                                              |
| POST   | [`/v1/app/rooms/delete/multi`](#post-v1approomsdeletemulti)                                        | api\_php\_live\_v2 | Delete several rooms                                                      |
| POST   | [`/v1/app/rooms/get-updates`](#post-v1approomsget-updates)                                         | api\_php\_live\_v2 | Count each room's tasks with new activity since the caller last viewed it |
| GET    | `/v1/app/rooms/list`                                                                               | api\_php\_live\_v2 | List rooms, the old GET form of `POST /v1/app/rooms/list` (no caller)     |
| POST   | [`/v1/app/rooms/list`](#post-v1approomslist)                                                       | api\_php\_live\_v2 | List a site's rooms, with statuses, reservations and counts               |
| GET    | [`/v1/app/rooms/mark-as-visited/{roomUuid}`](#get-v1approomsmark-as-visitedroomuuid)               | api\_php\_live\_v2 | Record that the caller viewed a room                                      |
| POST   | [`/v1/app/rooms/priority/all`](#post-v1approomspriorityall)                                        | api\_php\_live\_v2 | Set the priority of all rooms that match a filter                         |
| POST   | [`/v1/app/rooms/priority/multi`](#post-v1approomsprioritymulti)                                    | api\_php\_live\_v2 | Set the priority of several rooms                                         |
| POST   | [`/v1/app/rooms/status/all`](#post-v1approomsstatusall)                                            | api\_php\_live\_v2 | Set the status of all rooms that match a filter                           |
| POST   | [`/v1/app/rooms/status/multi`](#post-v1approomsstatusmulti)                                        | api\_php\_live\_v2 | Set the status of several rooms                                           |
| GET    | [`/v1/app/rooms/{uuid}`](#get-v1approomsuuid)                                                      | api\_php\_live\_v2 | Get a room, with its reservation                                          |
| PUT    | [`/v1/app/rooms/{uuid}`](#put-v1approomsuuid)                                                      | api\_php\_live\_v2 | Change a room                                                             |
| DELETE | [`/v1/app/rooms/{uuid}`](#delete-v1approomsuuid)                                                   | api\_php\_live\_v2 | Delete a room                                                             |
| GET    | [`/v1/app/rooms/{uuid}/business/{businessUuid}/jobs`](#get-v1approomsuuidbusinessbusinessuuidjobs) | api\_php\_live\_v2 | List a room's tasks in a group                                            |
| GET    | [`/v1/app/rooms/{uuid}/businesses`](#get-v1approomsuuidbusinesses)                                 | api\_php\_live\_v2 | List the groups that have tasks in a room                                 |
| PUT    | [`/v1/app/rooms/{uuid}/status`](#put-v1approomsuuidstatus)                                         | api\_php\_live\_v2 | Change a room's status                                                    |
| POST   | [`?action=read_parent_area_data`](#post-actionread_parent_area_data)                               | php-apis           | Read a site's area master data                                            |
| POST   | [`?action=read_parent_room_data`](#post-actionread_parent_room_data)                               | php-apis           | Read a site's room master data, with guest records and account rows       |
| POST   | [`?action=save_pri_area`](#post-actionsave_pri_area)                                               | php-apis           | Save area rows from the apps                                              |
| ANY    | `?action=save_pri_area_user`                                                                       | php-apis           | Save area users (no caller)                                               |
| ANY    | `?action=save_pri_area_user_assigned`                                                              | php-apis           | Save area assignees (no caller)                                           |
| POST   | [`?action=save_pri_log_areavieweduser`](#post-actionsave_pri_log_areavieweduser)                   | php-apis           | Log that a user viewed an area                                            |
| POST   | [`?action=save_pri_log_roomstatuschange`](#post-actionsave_pri_log_roomstatuschange)               | php-apis           | Save room status changes and send them to the room's PMS                  |
| POST   | [`?action=save_pri_log_roomvieweduser`](#post-actionsave_pri_log_roomvieweduser)                   | php-apis           | Log that a user viewed a room                                             |
| POST   | [`?action=save_pri_room`](#post-actionsave_pri_room)                                               | php-apis           | Save room rows from the apps                                              |
| ANY    | `?action=save_pri_room_user`                                                                       | php-apis           | Save room users (no caller)                                               |
| ANY    | `?action=save_pri_room_user_assigned`                                                              | php-apis           | Save room assignees (no caller)                                           |

Notes on the table:

* Rows marked "(no caller)" have no caller in the pinned clones. The GET form of `rooms/list` is routed with the comment "TODO remove after april release" (api\_php\_live\_v2 @ ef3c4319f6, `routes/room.php:12`); every client sends the POST form. No client has an endpoint for the two area priority routes, and no client references the four `save_pri_*_user*` actions. Whether to remove them is open \[[ASK-11](https://github.com/snapfix/docs/blob/main/ASK.md#ask-11-which-unused-api-endpoints-are-still-needed)].
* The php-apis rows with a caller show `POST`: iOS and Android send `POST` with a JSON body (ios @ aa31967ac8, `APIManagers/APIManager.swift:933` and `:1399`; android @ 86068bfeea, `network/ApiService.java:147-149` and `:256-258`). The `ANY` rows keep `ANY`.
* Priority values are the `PriorityLevels` codes: `0` none, `1` temporary (still accepted, marked for removal), `5` low, `10` medium, `20` high, `30` emergency. The web and both apps use `0`, `10` and `20` only (web\_app\_v2 @ 0989b8e685, `src/app/shared/config.ts:105-109`; ios @ aa31967ac8, `SnapFix/PriorityView/PriorityView.swift:11-14`; android @ 86068bfeea, `model/Priority.kt:3-6`). A level above `0` also sets the old flag `fPriority` to `1`; `0` clears both.
* A room's status changes in three ways. The web uses `PUT /v1/app/rooms/{uuid}/status` and the bulk status routes, which log the change, may create an inspection task and push the change to every PMS of the site ([Status change side effects](#status-change-side-effects)) \[[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)]. The apps change the room in their local database and sync it: the room row with its new status through `save_pri_room`, and the change through `save_pri_log_roomstatuschange`, which only sends it to the PMS the room is mapped to \[[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 services post their changes to `POST /v1/internal/rooms/{uuid}/status` ([Integrations](https://docs.snapfix.com/engineering-reference/api/integrations.md)); that route doesn't push the change back to the PMS (api\_php\_live\_v2 @ ef3c4319f6, `app/Http/Controllers/v1/Versions/v1_0/Internal/InternalController.php`: only the multi-room route dispatches `MapRoomStatus`, at `:325`).
* The cleaning and inspection groups of a room, `GET /v1/app/rooms/{uuid}/hk-businesses`, are documented with [Housekeeping](https://docs.snapfix.com/engineering-reference/api/housekeeping.md#get-v1approomsuuidhk-businesses).

## POST /v1/app/areas

Creates areas in a site. Names the site already has are skipped; the request fails only when every name is taken.

* **Auth:** user token; the caller must belong to the site ([permissions](#room-and-area-permissions)).
* **Used by:** web: the create-area dialog of [Areas & rooms](https://docs.snapfix.com/how-the-apps-work/screens/rooms/areas-and-rooms.md), for typed, template or uploaded names (`account-settings-manage-area-create-dialog.component.ts:465`).

**Request** (JSON body)

| Name         | In   | Type             | Required | Rules                                                                                                            |
| ------------ | ---- | ---------------- | -------- | ---------------------------------------------------------------------------------------------------------------- |
| `parentUuid` | body | string           | yes      | The site                                                                                                         |
| `areas`      | body | array of strings | yes      | Area names, none empty. A name the site already has is skipped, compared without case. Repeated names count once |

**Response** `200`

```json
{
  "status": "success",
  "message": "Operation was successful",
  "data": null
}
```

**Errors:** `403` "Access denied" when the caller doesn't belong to the site; `422` "The areas has already been taken." when every name is in the site already; `422` for a missing `parentUuid` or an empty name.

**Side effects:**

* Inserts one [`tPri_Area`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_area.md) row per new name. `enum_Origin` comes from the `fOrigin` request header: `android` 1, `ios` 2, `web` 3, `web-admin` 4, `email` 5, `qr-app` 6, `publicapi` 7, `guest-line` 8, `schedule` 9, `auto-hk` 10, anything else 0 (`getOrigin` in `app/Helpers/common.php:656-671`). The web sends `web`.
* When the site has no building, first creates one, named `default_parent_building-b6b7`. When the building has no room sections, adds the default sections ([`tPri_BuildingRoomSection`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_buildingroomsection.md)) and the default main statuses (`app/Services/BuildingService.php:21-55`).

## POST /v1/app/areas/delete/multi

Deletes several areas of one site.

* **Auth:** user token; site admins only: a [`tPri_UserParent`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_userparent.md) row with user type `admin` ([permissions](#room-and-area-permissions)).
* **Used by:** web: "Delete Selected" on the Areas tab of [Areas & rooms](https://docs.snapfix.com/how-the-apps-work/screens/rooms/areas-and-rooms.md) (`account-settings-manage-room-list.component.ts:476`).

**Request** (JSON body)

| Name         | In   | Type             | Required | Rules                                                                       |
| ------------ | ---- | ---------------- | -------- | --------------------------------------------------------------------------- |
| `parentUuid` | body | string           | yes      | The site                                                                    |
| `uuids`      | body | array of strings | yes      | At least one area ID. IDs of areas outside the site are skipped. No maximum |

**Response** `200`: `data` is a [bulk result](#bulk-result-object), and the message counts the areas deleted.

```json
{
  "status": "success",
  "message": "2 areas deleted successfully",
  "data": { "total": 2 }
}
```

**Errors:** `403` "Access denied" for a caller who isn't a site admin; `404` when the site has no building; `422` when `uuids` is missing or empty.

**Side effects:** [soft-deletes](#room-and-area-permissions) each area. Each area is deleted with its own queries, inside the request.

## POST /v1/app/areas/get-updates

Counts, for each area, the tasks with new activity since the caller last viewed the area. An area the caller has never viewed is marked viewed now, so its count is 0.

* **Auth:** user token; no site check.
* **Used by:** web: [Areas](https://docs.snapfix.com/how-the-apps-work/screens/rooms/areas.md), after each page of the list (`area.component.ts:196`).

**Request** (JSON body)

| Name        | In   | Type             | Required | Rules    |
| ----------- | ---- | ---------------- | -------- | -------- |
| `areaUuids` | body | array of strings | yes      | Area IDs |

**Response** `200`: `data` is a list of [update counts](#update-count-object), one per requested area, in the request's order.

```json
{
  "status": "success",
  "message": "Operation was successful",
  "data": [ { "areaUuid": "123", "updatedJobCount": 2 } ]
}
```

**Errors:** `422` when `areaUuids` is missing or not a list; `404` "Resource not found" when any ID isn't an area that exists and isn't deleted; the whole request then fails.

**Side effects:** for each requested ID the caller has no view record for, inserts a [`tPri_Log_AreaViewedUser`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_log_areavieweduser.md) row with the current time. This happens before the areas are looked up, so unknown IDs get rows too, also when the request ends in `404`.

## POST /v1/app/areas/list

Lists a site's areas, with task counts and optional paging. Names that start with a number come first, in number order, then the rest by name.

* **Auth:** user token; no site check.
* **Used by:** web: [Areas](https://docs.snapfix.com/how-the-apps-work/screens/rooms/areas.md) (`area.component.ts:152`), [Areas & rooms](https://docs.snapfix.com/how-the-apps-work/screens/rooms/areas-and-rooms.md) (`account-settings-manage-room-list.component.ts:308`), the area picker of the task filters and the task's rooms-and-areas dialog (`area-list-partial.component.ts:153`), and the create-task dialog, to see whether the site has areas (`task-create-dialog.component.ts:1066`); Simon (area search, `src/agent/tools/resolve.py:280`).

**Request** (JSON body and query string; the web and Simon send `parentUuid`, `limit` and `offset` in the query string)

| Name            | In            | Type       | Required | Rules                                                                                            |
| --------------- | ------------- | ---------- | -------- | ------------------------------------------------------------------------------------------------ |
| `parentUuid`    | query or body | string     | yes      | The site                                                                                         |
| `searchText`    | body          | string     | no       | Matches the name, large text title, description or instruction, without case                     |
| `priorityLevel` | body          | array      | no       | Accepted and ignored: no priority filter is applied                                              |
| `withJobsCount` | body or query | `0` or `1` | no       | Default `1`: adds `jobsColorCount`. The web leaves it out, so its area pickers always get counts |
| `limit`         | query         | integer    | no       | Page size. Without it the whole list comes back. No maximum                                      |
| `offset`        | query         | integer    | no       | Page number from `1`, default `1`. Read only with `limit`                                        |

**Response** `200`

```json
{
  "status": "success",
  "message": "Operation was successful",
  "data": {
    "areas": [ { "uuid": "123", "name": "Lobby", "priorityLevel": 0, "jobsColorCount": { "red": 1, "amber": 0, "green": 4 } } ],
    "totalCount": 12,
    "pagination": { "total": 12, "perPage": 25, "currentPage": 1, "lastPage": 1, "from": 1, "to": 12 }
  }
}
```

`areas` are [area objects](#area-object). `totalCount` counts every area of the site, ignoring `searchText`. `pagination` comes only with `limit`. A site with no building gets an empty list and `totalCount` 0.

**Errors:** `422` when `parentUuid` is missing, or `limit` or `offset` isn't a whole number.

**Side effects:** none.

## GET /v1/app/areas/mark-as-visited/{areaUuid}

Records that the caller viewed an area, so its count of tasks with new activity starts again from now.

* **Auth:** user token; no check that the area exists or that the caller is in its site.
* **Used by:** web: the [area](https://docs.snapfix.com/how-the-apps-work/screens/rooms/area.md) task list, when the user leaves it and it had new activity (`task-list.component.ts:139-149`, through `task-http.service.ts:119-136`).

**Request**

| Name       | In   | Type   | Required | Rules                                                |
| ---------- | ---- | ------ | -------- | ---------------------------------------------------- |
| `areaUuid` | path | string | yes      | The area. Not checked: an unknown ID is recorded too |

**Response** `200`: `data` is `null`, `message` "Operation was successful".

**Errors:** only the shared ones.

**Side effects:** inserts one [`tPri_Log_AreaViewedUser`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_log_areavieweduser.md) row for the caller, with the current time. This is a `GET` that changes data.

## GET /v1/app/areas/templates/list

Lists the area names offered in the create-area dialog. The list is fixed in the server code: "Ballroom", "Bar", "Business Centre", "Cafe" and "Car Park" (api\_php\_live\_v2 @ ef3c4319f6, `resources/other/area_templates.php`).

* **Auth:** user token; any signed-in user.
* **Used by:** web: the create-area dialog of [Areas & rooms](https://docs.snapfix.com/how-the-apps-work/screens/rooms/areas-and-rooms.md) (`account-settings-manage-area-create-dialog.component.ts:499`).

**Request:** none.

**Response** `200`

```json
{
  "status": "success",
  "message": "Operation was successful",
  "data": [ { "name": "Ballroom" }, { "name": "Bar" }, { "name": "Business Centre" }, { "name": "Cafe" }, { "name": "Car Park" } ]
}
```

**Errors:** only the shared ones.

**Side effects:** none.

## GET /v1/app/areas/{uuid}

Gets one area, with its task counts and its site.

* **Auth:** user token; no site check.
* **Used by:** web: the header of the [area](https://docs.snapfix.com/how-the-apps-work/screens/rooms/area.md) task list (`task-list.component.ts:315`), the task's room and area picker (`task-room-and-area.component.ts:156`), the planned task's room picker (`planned-task-room.component.ts:105`), and the task page opened from an area (`task.component.ts:315`).

**Request**

| Name   | In   | Type   | Required | Rules    |
| ------ | ---- | ------ | -------- | -------- |
| `uuid` | path | string | yes      | The area |

**Response** `200`: `data` is an [area object](#area-object) with `parentUuid` and `jobsColorCount`.

```json
{
  "status": "success",
  "message": "Operation was successful",
  "data": { "uuid": "123", "buildingUuid": "200", "parentUuid": "300", "name": "Lobby", "priority": 0, "priorityLevel": 0, "jobsColorCount": { "red": 1, "amber": 0, "green": 4 } }
}
```

**Errors:** `404` when the area doesn't exist or is deleted.

**Side effects:** none.

## PUT /v1/app/areas/{uuid}

Changes an area's name, texts or priority.

* **Auth:** user token; the caller must belong to the area's site ([permissions](#room-and-area-permissions)).
* **Used by:** web: the area edit dialog of [Areas & rooms](https://docs.snapfix.com/how-the-apps-work/screens/rooms/areas-and-rooms.md), which sends `name` and `description` (`account-settings-manage-area-edit-dialog.component.ts:74`).

**Request** (JSON body)

| Name             | In   | Type           | Required | Rules                                                                                                        |
| ---------------- | ---- | -------------- | -------- | ------------------------------------------------------------------------------------------------------------ |
| `uuid`           | path | string         | yes      | The area                                                                                                     |
| `name`           | body | string         | no       | Unique among the site's areas that aren't deleted, compared without case: "The name has already been taken." |
| `largeTextTitle` | body | string or null | no       | Large text shown in place of a photo (`fLargeTextTitle`)                                                     |
| `description`    | body | string or null | no       | Stored as `fDescription`                                                                                     |
| `instruction`    | body | string or null | no       | Stored as `fInstruction`                                                                                     |
| `priority`       | body | integer        | no       | `0`, `1`, `5`, `10`, `20` or `30`; anything else: "The selected priority is invalid."                        |

**Response** `200`: `data` is the [area object](#area-object) after the change, without `jobsColorCount`.

**Errors:** `403` "Access denied" when the caller doesn't belong to the site; `404` when the area doesn't exist; `422` as in the table.

**Side effects:** updates the [`tPri_Area`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_area.md) row. A priority above `0` sets `fPriority` to `1` and stores the level in `fPriorityLevel`; `0` clears both. Nothing is sent to a PMS.

## DELETE /v1/app/areas/{uuid}

Deletes one area.

* **Auth:** user token; the caller must belong to the area's site. Any member can delete one area, while the bulk delete needs a site admin ([permissions](#room-and-area-permissions)).
* **Used by:** web: the area's delete on [Areas & rooms](https://docs.snapfix.com/how-the-apps-work/screens/rooms/areas-and-rooms.md) (`account-settings-manage-rooms-header.component.ts:156`).

**Request**

| Name   | In   | Type   | Required | Rules    |
| ------ | ---- | ------ | -------- | -------- |
| `uuid` | path | string | yes      | The area |

**Response** `200`: `data` is `null`. The message is the bare key `messages.area_deleted`, because the key has no text in any language.

```json
{
  "status": "success",
  "message": "messages.area_deleted",
  "data": null
}
```

**Errors:** `403` "Access denied"; `404` when the area doesn't exist.

**Side effects:** [soft-deletes](#room-and-area-permissions) the area.

## GET /v1/app/areas/{uuid}/business/{businessUuid}/jobs

Lists an area's tasks in one group, for the tasks panel of [Areas & rooms](https://docs.snapfix.com/how-the-apps-work/screens/rooms/areas-and-rooms.md). The area's own task list uses [`POST /v1/app/tasks/list`](https://docs.snapfix.com/engineering-reference/api/tasks.md#post-v1apptaskslist) instead.

* **Auth:** user token; no site check, but the list holds only the tasks the caller can see, in groups the caller is in ([task permissions](https://docs.snapfix.com/engineering-reference/api/tasks.md#task-permissions)). A group the caller isn't in gives an empty list, also for multi-site users.
* **Used by:** web: Areas & rooms, the tasks panel of a selected group (`account-settings-manage-room-tasks.component.ts:73`).

**Request**

| Name           | In    | Type    | Required | Rules                                       |
| -------------- | ----- | ------- | -------- | ------------------------------------------- |
| `uuid`         | path  | string  | yes      | The area                                    |
| `businessUuid` | path  | string  | yes      | The group                                   |
| `limit`        | query | integer | no       | Page size. Without it every task comes back |
| `offset`       | query | integer | no       | Page number from `1`, default `1`           |

Only tasks that aren't deleted or archived, in active task groups, with a task time (`fJobTs`) that isn't in the future, are listed.

**Response** `200`

```json
{
  "status": "success",
  "message": "Operation was successful",
  "data": {
    "jobs": [ { "uuid": "123", "title": "Leaking tap" } ],
    "totalCount": { "red": 1, "amber": 0, "green": 0 }
  }
}
```

`jobs` are [task objects](https://docs.snapfix.com/engineering-reference/api/tasks.md#task-object) with `users` and `status`. `totalCount` counts the colours of the returned tasks only, so with `limit` it counts one page; yellow tasks count as amber. `pagination` comes only with `limit`.

**Errors:** only the shared ones; an unknown area or group gives an empty list.

**Side effects:** none; the last editor of each task is loaded for the answer.

## GET /v1/app/areas/{uuid}/businesses

Lists the groups that have tasks in an area that the caller can see.

* **Auth:** user token; no site check, but only the caller's own groups come back, as in [the area's task list](#get-v1appareasuuidbusinessbusinessuuidjobs).
* **Used by:** web: Areas & rooms, the groups panel of a selected area (`account-settings-manage-room-groups.component.ts:121`).

**Request**

| Name     | In    | Type    | Required | Rules                                                                |
| -------- | ----- | ------- | -------- | -------------------------------------------------------------------- |
| `uuid`   | path  | string  | yes      | The area                                                             |
| `limit`  | query | integer | no       | Page size. The answer then holds the page only, with no `pagination` |
| `offset` | query | integer | no       | Page number from `1`                                                 |

**Response** `200`: `data` is a list of [group objects](#group-object), one per group.

```json
{
  "status": "success",
  "message": "Operation was successful",
  "data": [ { "uuid": "400", "name": "Housekeeping", "image": null, "address": null, "inActive": null, "purpose": null, "instructions": null, "notificationDisabled": null } ]
}
```

**Errors:** only the shared ones; an unknown area gives an empty list.

**Side effects:** none.

## GET /v1/app/parents/{uuid}/room-statuses

Lists a site's room status catalog: its sections, each with its main and secondary statuses. The status pickers and the status filter offer these.

* **Auth:** user token; no site check.
* **Used by:** web: the room status filter of the filter drawer (`filter-room-status.component.ts:71`), and the status picker of the room status dialog and the bulk status dialog on [Room status](https://docs.snapfix.com/how-the-apps-work/screens/rooms/room-status.md) (`room-status-section-list-partial.component.ts:50`). The web keeps the answer per site for the rest of the page session (`room-http.service.ts:179-192`). Simon (rooms by status, `src/agent/tools/rooms/__init__.py:52`).

**Request**

| Name   | In   | Type   | Required | Rules    |
| ------ | ---- | ------ | -------- | -------- |
| `uuid` | path | string | yes      | The site |

**Response** `200`: `data` is a list of [room status sections](#room-status-section-object).

```json
{
  "status": "success",
  "message": "Operation was successful",
  "data": [
    {
      "uuid": "40",
      "name": "Cleaning status",
      "statuses": [
        { "uuid": "41", "name": "CLEANED", "color": "green", "statusIcon": null, "iconUrl": null, "readOnly": "0", "type": "main" },
        { "uuid": "42", "name": "Vacant", "color": null, "statusIcon": null, "iconUrl": null, "readOnly": 0, "type": "secondary" }
      ]
    }
  ]
}
```

**Errors:** `404` "Resource not found" when the site has no building.

**Side effects:** none.

## POST /v1/app/rooms

Creates rooms in a site. Names the site already has are skipped; the request fails only when every name is taken.

* **Auth:** user token; the caller must belong to the site ([permissions](#room-and-area-permissions)).
* **Used by:** web: the review step of the create-rooms dialog on [Areas & rooms](https://docs.snapfix.com/how-the-apps-work/screens/rooms/areas-and-rooms.md), which sends a range of numbers (`manage-rooms-create-review.component.ts:65`).

**Request** (JSON body)

| Name         | In   | Type                        | Required | Rules                                                                                                                                                                                                                   |
| ------------ | ---- | --------------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `parentUuid` | body | string                      | yes      | The site                                                                                                                                                                                                                |
| `rooms`      | body | array of strings or numbers | yes      | Room names, none empty. A name the site already has is skipped. The check finds names that differ only by case, but then compares the exact text, so such a name is created as a second room. Repeated names count once |

**Response** `200`: `data` is `null`, `message` "Operation was successful".

**Errors:** `403` "Access denied" when the caller doesn't belong to the site; `422` "The rooms has already been taken." when every name is in the site already; `422` for a missing `parentUuid` or an empty name.

**Side effects:** inserts one [`tPri_Room`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_room.md) row per new name, with no status and `enum_Origin` from the `fOrigin` header, as for [areas](#post-v1appareas). A site with no building gets one first, as for areas.

## POST /v1/app/rooms/delete/multi

Deletes several rooms of one site.

* **Auth:** user token; site admins only ([permissions](#room-and-area-permissions)).
* **Used by:** web: "Delete Selected" on the Rooms tab of [Areas & rooms](https://docs.snapfix.com/how-the-apps-work/screens/rooms/areas-and-rooms.md) (`account-settings-manage-room-list.component.ts:479`).

**Request** (JSON body)

| Name         | In   | Type             | Required | Rules                                                                       |
| ------------ | ---- | ---------------- | -------- | --------------------------------------------------------------------------- |
| `parentUuid` | body | string           | yes      | The site                                                                    |
| `uuids`      | body | array of strings | yes      | At least one room ID. IDs of rooms outside the site are skipped. No maximum |

**Response** `200`: `data` is a [bulk result](#bulk-result-object); the message reads, for example, "2 rooms deleted successfully".

**Errors:** `403` "Access denied" for a caller who isn't a site admin; `404` when the site has no building; `422` when `uuids` is missing or empty.

**Side effects:** [soft-deletes](#room-and-area-permissions) each room, each with its own queries.

## POST /v1/app/rooms/get-updates

Counts, for each room, the tasks with new activity since the caller last viewed the room. A room the caller has never viewed is marked viewed now, so its count is 0.

* **Auth:** user token; no site check.
* **Used by:** web: [Room tasks](https://docs.snapfix.com/how-the-apps-work/screens/rooms/room-tasks.md), after each page of the list (`room-list.component.ts:204`).

**Request** (JSON body)

| Name        | In   | Type             | Required | Rules    |
| ----------- | ---- | ---------------- | -------- | -------- |
| `roomUuids` | body | array of strings | yes      | Room IDs |

**Response** `200`: `data` is a list of [update counts](#update-count-object), one per requested room that exists, isn't deleted and is in a building that isn't deleted. Unknown IDs are left out.

**Errors:** `422` when `roomUuids` is missing or not a list.

**Side effects:** for each requested ID the caller has no view record for, inserts a [`tPri_Log_RoomViewedUser`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_log_roomvieweduser.md) row with the current time, whether or not the room exists.

## POST /v1/app/rooms/list

Lists a site's rooms, with their statuses, task counts and guest reservations, filtered and optionally paged. Names that start with a number come first, in number order, then the rest by name.

* **Auth:** user token; no site check. Each room comes with its reservation, so a caller who knows a site's ID reads its guests' names and stays.
* **Used by:** web: [Room tasks](https://docs.snapfix.com/how-the-apps-work/screens/rooms/room-tasks.md) (`room-list.component.ts:162`), [Room status](https://docs.snapfix.com/how-the-apps-work/screens/rooms/room-status.md) with its filters (`room-status-list.component.ts:191`), [Areas & rooms](https://docs.snapfix.com/how-the-apps-work/screens/rooms/areas-and-rooms.md) (`account-settings-manage-room-list.component.ts:345`), the room picker of the task filters and the task's rooms-and-areas dialog (`room-list-partial.component.ts:157`), the create-task dialog, to see whether the site has rooms (`task-create-dialog.component.ts:1054`), and the room search of the housekeeping create-task dialog (`create-housekeeping-task-dialog.component.ts:688-695`); Simon (room search and rooms by status, `src/agent/tools/rooms/__init__.py:67`, `src/agent/tools/resolve.py:163`, `src/agent/tools/tasks/create.py:386`).

**Request** (JSON body and query string; the web and Simon send `parentUuid`, `limit` and `offset` in the query string)

| Name               | In            | Type              | Required | Rules                                                                                                                                                                                 |
| ------------------ | ------------- | ----------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `parentUuid`       | query or body | string            | yes      | The site                                                                                                                                                                              |
| `searchText`       | body          | string            | no       | Matches the main status's name, or the room's name, large text title, description or instruction, without case                                                                        |
| `priorityLevel`    | body          | array of integers | no       | Only rooms with one of these levels in `fPriorityLevel`. A room with the old flag and level 0 reads as `20` but matches only `0`                                                      |
| `status`           | body          | array of strings  | no       | Only rooms with one of these main statuses                                                                                                                                            |
| `statusSecondary`  | body          | array of strings  | no       | Only rooms with one of these secondary statuses                                                                                                                                       |
| `withStatus`       | body or query | `0` or `1`        | no       | Default `1`: adds `status` and `statusSecondary`                                                                                                                                      |
| `withoutStatus`    | body or query | `0` or `1`        | no       | When sent, wins over `withStatus`: `1` leaves the statuses out, `0` keeps them                                                                                                        |
| `withJobsCount`    | body or query | `0` or `1`        | no       | Default `1`: adds `jobsColorCount`                                                                                                                                                    |
| `withoutJobsCount` | body or query | `0` or `1`        | no       | When sent, wins over `withJobsCount`: `1` leaves the counts out, `0` keeps them. The web's room pickers send `0` here and in `withoutStatus` when they want neither, so they get both |
| `limit`            | query         | integer           | no       | Page size. Without it every room of the site comes back. No maximum                                                                                                                   |
| `offset`           | query         | integer           | no       | Page number from `1`, default `1`. Read only with `limit`                                                                                                                             |

A filter applies whenever it is sent, so an empty list in `priorityLevel`, `status` or `statusSecondary` matches no room. The web and Simon send a filter only when it has values.

**Response** `200`

```json
{
  "status": "success",
  "message": "Operation was successful",
  "data": {
    "rooms": [
      {
        "uuid": "123",
        "name": "Room 101",
        "priority": 0,
        "priorityLevel": 0,
        "occupied": 0,
        "reservation": { "roomName": "Room 101", "occupancy": "Vacant" },
        "status": { "uuid": "41", "name": "CLEANED", "color": "green" },
        "statusSecondary": null,
        "jobsColorCount": { "red": 0, "amber": 1, "green": 0 }
      }
    ],
    "totalCount": 40,
    "pagination": { "total": 40, "perPage": 25, "currentPage": 1, "lastPage": 2, "from": 1, "to": 25 }
  }
}
```

`rooms` are [room objects](#room-object) with their reservation. `totalCount` counts every room of the site, ignoring the filters; `pagination.total` counts the rooms that match them. `pagination` comes only with `limit`. A site with no building gets an empty list and `totalCount` 0.

**Errors:** `422` when `parentUuid` is missing, or `limit` or `offset` isn't a whole number.

**Side effects:** none.

## GET /v1/app/rooms/mark-as-visited/{roomUuid}

Records that the caller viewed a room, so its count of tasks with new activity starts again from now.

* **Auth:** user token; no check that the room exists or that the caller is in its site.
* **Used by:** web: the [room](https://docs.snapfix.com/how-the-apps-work/screens/rooms/room.md) task list, when the user leaves it and it had new activity (`task-list.component.ts:139-149`).

**Request**

| Name       | In   | Type   | Required | Rules                                                |
| ---------- | ---- | ------ | -------- | ---------------------------------------------------- |
| `roomUuid` | path | string | yes      | The room. Not checked: an unknown ID is recorded too |

**Response** `200`: `data` is `null`, `message` "Operation was successful".

**Errors:** only the shared ones.

**Side effects:** inserts one [`tPri_Log_RoomViewedUser`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_log_roomvieweduser.md) row for the caller, with the current time. This is a `GET` that changes data.

## POST /v1/app/rooms/priority/all

Sets the priority of every room of a site that matches the filters and doesn't have that level already.

* **Auth:** user token; the caller must belong to the site ([permissions](#room-and-area-permissions)).
* **Used by:** web: the priority dialog of [Room status](https://docs.snapfix.com/how-the-apps-work/screens/rooms/room-status.md) with all rooms selected (`room-status-multi-actions-priority-dialog.component.ts:79`).

**Request** (JSON body)

| Name                                                       | In   | Type                                                    | Required | Rules                                                                                                                                                                          |
| ---------------------------------------------------------- | ---- | ------------------------------------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `parentUuid`                                               | body | string                                                  | yes      | The site                                                                                                                                                                       |
| `value`                                                    | body | string                                                  | yes      | The new level as text: `0`, `1`, `5`, `10`, `20` or `30`. Anything else: "The selected update priority level is invalid." The web sends `0` when the user removes the priority |
| `searchText`, `priorityLevel`, `status`, `statusSecondary` | body | as in [`POST /v1/app/rooms/list`](#post-v1approomslist) | no       | The filters that pick the rooms. Without them every room of the site matches                                                                                                   |

A room is skipped when its stored `fPriorityLevel` already equals `value`. A room with the old flag `fPriority` 1 and level 0 reads as level 20, but is skipped by `value` 0, so it keeps its priority.

**Response** `200`: `data` is a [bulk result](#bulk-result-object).

```json
{
  "status": "success",
  "message": "Operation was successful",
  "data": { "total": 14 }
}
```

**Errors:** `403` "Access denied" when the caller doesn't belong to the site; `404` when the site has no building; `422` as in the table.

**Side effects:** one update of `fPriority`, `fPriorityLevel`, `fServerTs` and `uuid_tUser_ModifiedBy` for the rooms that change, in [`tPri_Room`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_room.md). No log row.

## POST /v1/app/rooms/priority/multi

Sets the priority of the rooms listed.

* **Auth:** user token; the caller must belong to the site ([permissions](#room-and-area-permissions)).
* **Used by:** web: the priority dialog of [Room status](https://docs.snapfix.com/how-the-apps-work/screens/rooms/room-status.md) with rooms selected (`room-status-multi-actions-priority-dialog.component.ts:79`).

**Request** (JSON body)

| Name         | In   | Type             | Required | Rules                                                                  |
| ------------ | ---- | ---------------- | -------- | ---------------------------------------------------------------------- |
| `parentUuid` | body | string           | yes      | The site                                                               |
| `value`      | body | string           | yes      | As in [`POST /v1/app/rooms/priority/all`](#post-v1approomspriorityall) |
| `uuids`      | body | array of strings | yes      | Room IDs. IDs of rooms outside the site are skipped. No maximum        |

Rooms that already have the level are skipped, as in the `all` route.

**Response** `200`: `data` is a [bulk result](#bulk-result-object).

**Errors:** `403`; `404` when the site has no building; `422` for an invalid `value`, or a missing or empty `uuids`.

**Side effects:** as in the `all` route, for the listed rooms.

## POST /v1/app/rooms/status/all

Sets the main status, and optionally the secondary status, of every room that matches the filters and isn't on that main status already. Rooms already on it are skipped, so they keep their secondary status and get no log row.

* **Auth:** user token; the caller must belong to the site, and each status must be in the site's catalog ([permissions](#room-and-area-permissions)).
* **Used by:** web: the bulk status dialog of [Room status](https://docs.snapfix.com/how-the-apps-work/screens/rooms/room-status.md) with all rooms selected, which sends the main and the secondary status together (`room-status-multi-actions-status-dialog.component.ts:51-58`).

**Request** (JSON body)

| Name                                                       | In   | Type                                                    | Required | Rules                                                                                                                   |
| ---------------------------------------------------------- | ---- | ------------------------------------------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------- |
| `parentUuid`                                               | body | string                                                  | yes      | The site                                                                                                                |
| `value`                                                    | body | string                                                  | yes      | The main status ID. An unknown ID: `404`                                                                                |
| `statusSecondaryUuid`                                      | body | string                                                  | no       | A secondary status ID; an unknown ID: `422`. Leave it out to keep each room's secondary status; `null` fails validation |
| `searchText`, `priorityLevel`, `status`, `statusSecondary` | body | as in [`POST /v1/app/rooms/list`](#post-v1approomslist) | no       | The filters that pick the rooms. Without them every room of the site matches                                            |

**Response** `200`: `data` is a [bulk result](#bulk-result-object): the rooms whose main status changed.

**Errors:** `403` "Access denied" when the caller doesn't belong to the site, or a status is from another site's catalog; `404` for an unknown `value`, or a site with no building; `422` for an unknown `statusSecondaryUuid`.

**Side effects:** updates the rooms' status links in one statement, then runs the [status change side effects](#status-change-side-effects) for each changed room. The per-room work, a few queries and a log insert for each room, runs inside the request, with no limit on the number of rooms.

## POST /v1/app/rooms/status/multi

Sets the main status, and optionally the secondary status, of the rooms listed. Rooms already on that main status are skipped, as in the `all` route.

* **Auth:** as in [`POST /v1/app/rooms/status/all`](#post-v1approomsstatusall).
* **Used by:** web: the bulk status dialog of [Room status](https://docs.snapfix.com/how-the-apps-work/screens/rooms/room-status.md) with rooms selected (`room-status-multi-actions-status-dialog.component.ts:58`).

**Request** (JSON body)

| Name                  | In   | Type             | Required | Rules                                                           |
| --------------------- | ---- | ---------------- | -------- | --------------------------------------------------------------- |
| `parentUuid`          | body | string           | yes      | The site                                                        |
| `value`               | body | string           | yes      | The main status ID, as in the `all` route                       |
| `statusSecondaryUuid` | body | string           | no       | As in the `all` route                                           |
| `uuids`               | body | array of strings | yes      | Room IDs. IDs of rooms outside the site are skipped. No maximum |

**Response** `200`: `data` is a [bulk result](#bulk-result-object).

**Errors:** as in the `all` route, and `422` when `uuids` is missing or empty.

**Side effects:** as in the `all` route, for the listed rooms.

## GET /v1/app/rooms/{uuid}

Gets one room, with its reservation, its statuses and its task counts.

* **Auth:** user token; no site check, and the room's reservation comes with it. Simon checks the room's `parentUuid` itself after the read (snapfix\_ai\_agent @ e5e18caef5, `src/snapfix/rooms/__init__.py:77-84`).
* **Used by:** web: the room status dialog on [Room status](https://docs.snapfix.com/how-the-apps-work/screens/rooms/room-status.md) (`room-status-dialog.component.ts:107`), the header of the [room](https://docs.snapfix.com/how-the-apps-work/screens/rooms/room.md) task list (`task-list.component.ts:289`), the task's room and area picker (`task-room-and-area.component.ts:152`), the planned task's room picker (`planned-task-room.component.ts:101`), and the task page opened from a room (`task.component.ts:294`); Simon (room status, `src/agent/tools/rooms/__init__.py:26`).

**Request**

| Name   | In   | Type   | Required | Rules    |
| ------ | ---- | ------ | -------- | -------- |
| `uuid` | path | string | yes      | The room |

**Response** `200`: `data` is a [room object](#room-object) with `parentUuid`, `reservation`, `status`, `statusSecondary` and `jobsColorCount`.

```json
{
  "status": "success",
  "message": "Operation was successful",
  "data": { "uuid": "123", "buildingUuid": "200", "parentUuid": "300", "name": "Room 101", "priority": 0, "priorityLevel": 0, "occupied": 0, "reservation": { "roomName": "Room 101", "occupancy": "Vacant" }, "status": { "uuid": "41", "name": "CLEANED", "color": "green" }, "statusSecondary": null, "jobsColorCount": { "red": 0, "amber": 1, "green": 0 } }
}
```

**Errors:** `404` when the room doesn't exist or is deleted, or its building is deleted.

**Side effects:** none.

## PUT /v1/app/rooms/{uuid}

Changes a room's name, texts, priority or occupied flag.

* **Auth:** user token; the caller must belong to the room's site ([permissions](#room-and-area-permissions)).
* **Used by:** web: the room edit dialog of [Areas & rooms](https://docs.snapfix.com/how-the-apps-work/screens/rooms/areas-and-rooms.md), which sends `name`, `description` and `instruction` (`account-settings-manage-room-edit-dialog.component.ts:69`); the room status dialog on [Room status](https://docs.snapfix.com/how-the-apps-work/screens/rooms/room-status.md), which sends `priority` (`room-status-dialog.component.ts:120-124`).

**Request** (JSON body)

| Name             | In   | Type           | Required | Rules                                                                                                        |
| ---------------- | ---- | -------------- | -------- | ------------------------------------------------------------------------------------------------------------ |
| `uuid`           | path | string         | yes      | The room                                                                                                     |
| `name`           | body | string         | no       | Unique among the site's rooms that aren't deleted, compared without case: "The name has already been taken." |
| `largeTextTitle` | body | string or null | no       | Large text shown in place of a photo (`fLargeTextTitle`)                                                     |
| `description`    | body | string or null | no       | Stored as `fDescription`                                                                                     |
| `instruction`    | body | string or null | no       | Stored as `fInstruction`                                                                                     |
| `priority`       | body | integer        | no       | As for [areas](#put-v1appareasuuid)                                                                          |
| `occupied`       | body | `0` or `1`     | no       | Stored, but answers that carry a reservation show the reservation's occupancy instead                        |

**Response** `200`: `data` is the [room object](#room-object) after the change, with `status` and `statusSecondary`, `reservation` `null` and no `jobsColorCount`.

**Errors:** `403` "Access denied" when the caller doesn't belong to the site; `404` when the room doesn't exist; `422` as in the table.

**Side effects:** updates the [`tPri_Room`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_room.md) row, with the priority as for areas. No log row, and nothing is sent to a PMS.

## DELETE /v1/app/rooms/{uuid}

Deletes one room.

* **Auth:** user token; the caller must belong to the room's site. Any member can delete one room, while the bulk delete needs a site admin ([permissions](#room-and-area-permissions)).
* **Used by:** web: the room's delete on [Areas & rooms](https://docs.snapfix.com/how-the-apps-work/screens/rooms/areas-and-rooms.md) (`account-settings-manage-rooms-header.component.ts:132`).

**Request**

| Name   | In   | Type   | Required | Rules    |
| ------ | ---- | ------ | -------- | -------- |
| `uuid` | path | string | yes      | The room |

**Response** `200`: `data` is `null`, `message` "Room deleted successfully".

**Errors:** `403` "Access denied"; `404` when the room doesn't exist.

**Side effects:** [soft-deletes](#room-and-area-permissions) the room.

## GET /v1/app/rooms/{uuid}/business/{businessUuid}/jobs

Lists a room's tasks in one group, for the tasks panel of [Areas & rooms](https://docs.snapfix.com/how-the-apps-work/screens/rooms/areas-and-rooms.md). It works as [the area version](#get-v1appareasuuidbusinessbusinessuuidjobs), with the same request, answer and visibility; the room's own task list uses [`POST /v1/app/tasks/list`](https://docs.snapfix.com/engineering-reference/api/tasks.md#post-v1apptaskslist).

* **Auth:** as in the area version.
* **Used by:** web: Areas & rooms, the tasks panel of a selected group (`account-settings-manage-room-tasks.component.ts:74`).

**Request:** `uuid` (the room) and `businessUuid` in the path; `limit` and `offset` in the query, as in the area version.

**Response** `200`: `jobs`, `totalCount` and, with `limit`, `pagination`, as in the area version.

**Errors:** only the shared ones; an unknown room or group gives an empty list.

**Side effects:** none.

## GET /v1/app/rooms/{uuid}/businesses

Lists the groups that have tasks in a room that the caller can see. It works as [the area version](#get-v1appareasuuidbusinesses).

* **Auth:** as in the area version.
* **Used by:** web: Areas & rooms, the groups panel of a selected room (`account-settings-manage-room-groups.component.ts:122`).

**Request:** `uuid` (the room) in the path; `limit` and `offset` in the query, as in the area version.

**Response** `200`: `data` is a list of [group objects](#group-object), with no `pagination`.

**Errors:** only the shared ones; an unknown room gives an empty list.

**Side effects:** none.

## PUT /v1/app/rooms/{uuid}/status

Changes one room's main status and, when it is sent, its secondary status. Unlike the bulk routes, it always writes, even when the status is unchanged.

* **Auth:** user token; the caller must belong to the room's site, and each status must be in the site's catalog ([permissions](#room-and-area-permissions)).
* **Used by:** web: the room status dialog on [Room status](https://docs.snapfix.com/how-the-apps-work/screens/rooms/room-status.md), on save (`room-status-dialog.component.ts:144`).

**Request** (JSON body)

| Name                  | In   | Type   | Required | Rules                                                                                                                                                                                                                                                                                                  |
| --------------------- | ---- | ------ | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `uuid`                | path | string | yes      | The room                                                                                                                                                                                                                                                                                               |
| `statusUuid`          | body | string | yes      | A main status ID that exists. Missing or unknown: `422`, as "The selected status uuid is invalid." for an unknown one                                                                                                                                                                                  |
| `statusSecondaryUuid` | body | string | no       | A secondary status ID that exists; unknown: `422`. Leave it out to keep the room's secondary status \[[ASK-87](https://github.com/snapfix/docs/blob/main/ASK.md#ask-87-should-staff-be-able-to-clear-a-rooms-secondary-status)]. `null` fails validation, so this route can't clear a secondary status |

**Response** `200`: `data` is the [room object](#room-object) after the change, with `status` and `statusSecondary` and `reservation` `null`.

```json
{
  "status": "success",
  "message": "Operation was successful",
  "data": { "uuid": "123", "name": "Room 101", "reservation": null, "status": { "uuid": "41", "name": "CLEANED", "color": "green" }, "statusSecondary": null }
}
```

**Errors:** `403` "Access denied" when the caller doesn't belong to the site, or a status is from another site's catalog; `404` when the room doesn't exist; `422` as in the table.

**Side effects:** updates the room's status links in [`tPri_Room`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_room.md), then the [status change side effects](#status-change-side-effects).

## POST ?action=read\_parent\_area\_data

Reads the area master data of one or more sites for the apps' local database: the buildings, the areas, the area users and assignees, and the task-area links.

* **Auth:** user token, if `JWT_AUTH_ENABLED` is on \[[ASK-12](https://github.com/snapfix/docs/blob/main/ASK.md#ask-12-which-settings-do-the-production-api-servers-use)]. `user_uuid` is checked for presence only and isn't compared with the token's user. Nothing checks that the caller is in the sites.
* **Used by:** iOS: the site download after sign-in (`APIManager.fetchAllParentSubData`, `APIManagers/APIManager.swift:1629-1640`, `:1673-1680`) and the site switcher (`SnapFix/BusinessListing+ParentSwither.swift:209`, `:485`); Android: the sign-in download (`service/LoginSubDataWork.kt:140`) and the site load (`viewModels/BusinessViewModel.java:660`).

**Request** (JSON body)

| Name           | In   | Type             | Required | Rules                                                                                                                                                                        |
| -------------- | ---- | ---------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `user_uuid`    | body | string           | yes      | Must be present and not empty: "user\_uuid must be mentioned in the request!"                                                                                                |
| `parent_uuids` | body | array of strings | yes      | The sites; repeats count once. Missing or empty: "invalid parent uuids". None found: "invalid parent!". Any one unknown: "invalid parent count!". Deleted sites are accepted |

**Response** `200`: `result` `true`, `message` "Values Found", and `data` as a [table data object](https://docs.snapfix.com/engineering-reference/api/tasks.md#table-data-object-php-apis): `tPri_Building` and `tPri_Area`, and, when the sites have a building, `tPri_AreaUser`, `tPri_AreaUserAssigned` and `tPri_JobArea`, empty when there are no areas. Each list holds every column, deleted rows included, in `fServerTs` order.

```json
{
  "result": true,
  "message": "Values Found",
  "data": {
    "tPri_Building": [ { "uuid": "200", "uuid_tParent": "300", "fName": "Main building" } ],
    "tPri_Area": [ { "uuid": "123", "uuid_tBuilding": "200", "fName": "Lobby", "fDeleted": 0 } ],
    "tPri_AreaUser": [],
    "tPri_AreaUserAssigned": [],
    "tPri_JobArea": []
  },
  "serverTs": 1794387600000
}
```

**Errors:** `200` with `result` `false` and the messages above; "Data cannot be blank!" for an empty body. The code also has "No Data found!", which no request can reach.

**Side effects:** none.

## POST ?action=read\_parent\_room\_data

Reads the room master data of one or more sites for the apps' local database: the buildings, room sections, main and secondary statuses and their icons, the rooms, the room users and assignees, the task-room links, the guest stays and their guests, and user accounts.

* **Auth:** as in [`read_parent_area_data`](#post-actionread_parent_area_data). Any signed-in user who knows a site's ID gets its guests' full records and account rows.
* **Used by:** iOS: the site download after sign-in (`APIManager.readRoomJobsData`, `APIManagers/APIManager.swift:1595-1625`, through `:1673-1680`) and the site switcher (`SnapFix/BusinessListing+ParentSwither.swift:208`, `:484`); Android: the sign-in download (`service/LoginSubDataWork.kt:139`) and the site load (`viewModels/BusinessViewModel.java:622`).

**Request** (JSON body): as in [`read_parent_area_data`](#post-actionread_parent_area_data).

**Response** `200`: `result` `true`, `message` "Values Found", and `data` as a [table data object](https://docs.snapfix.com/engineering-reference/api/tasks.md#table-data-object-php-apis), with these lists in `fServerTs` order. The answer is gzip-compressed when the client accepts it (php-apis @ 238ca4414e, `html/api/snapfix/index.php:57-60`).

| Key                                                                                                                                   | Holds                                                                                                                                                                                                                                    |
| ------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `tPri_Building`, `tPri_BuildingRoomSection`, `tPri_BuildingRoomStatusMain`, `tPri_BuildingRoomStatusSecondary`, `tPri_RoomStatusIcon` | The sites' buildings, room sections, statuses and the icons the statuses use, every column                                                                                                                                               |
| `tPri_Room`                                                                                                                           | The rooms, with a fixed list of columns: the status links, names and texts, `fPermanentNotes`, floor, capacity, occupied, priority and the flags. Columns such as `enum_RoomType`, the bed count and the cleaning durations are left out |
| `tPri_RoomUser`, `tPri_RoomUserAssigned`, `tPri_JobRoom`                                                                              | The rooms' users, assignees and task links, every column                                                                                                                                                                                 |
| `tPri_RoomGuestStatus`                                                                                                                | The rooms' stays with a check-out date after two days ago: recent check-outs, current stays and future stays                                                                                                                             |
| `tPri_RoomGuests`                                                                                                                     | Every column of each guest of those stays: first and last name, email, phone, postal address, country, date of birth, VIP flag, nationality and language                                                                                 |
| `tPri_User`                                                                                                                           | Every column of the room users' and assignees' accounts, and of one more account whose ID is written in the code (php-apis @ 238ca4414e, `htmlphp/api/snapfix/class/class.functions.php:30487-30490`)                                    |

```json
{
  "result": true,
  "message": "Values Found",
  "data": {
    "tPri_Building": [ { "uuid": "200", "uuid_tParent": "300", "fName": "Main building" } ],
    "tPri_Room": [ { "uuid": "123", "uuid_tBuilding": "200", "fName": "Room 101", "uuid_tBuildingRoomStatusMain": "41" } ],
    "tPri_RoomGuestStatus": [],
    "tPri_RoomGuests": [],
    "tPri_User": []
  },
  "serverTs": 1794387600000
}
```

**Errors:** as in [`read_parent_area_data`](#post-actionread_parent_area_data).

**Side effects:** none.

## POST ?action=save\_pri\_area

Saves area rows from the apps' sync. A row whose `uuid` is in [`tPri_Area`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_area.md) is updated; any other row is inserted. The server drops `uuid_tParentAreaStatus` from every row.

* **Auth:** user token, if `JWT_AUTH_ENABLED` is on \[[ASK-12](https://github.com/snapfix/docs/blob/main/ASK.md#ask-12-which-settings-do-the-production-api-servers-use)]. The rows can name any area of any site, with any column, and their user columns are trusted. Field values sent as JSON objects reach the SQL.
* **Used by:** iOS: the sync (`Managers/TaskManager.swift:3001`, run from the sync loop at `:294`); Android: the sync (`data/repository/SyncRepository.kt:714`).

**Request** (JSON body)

| Name          | In   | Type             | Required | Rules                                                                                                                   |
| ------------- | ---- | ---------------- | -------- | ----------------------------------------------------------------------------------------------------------------------- |
| `insert_data` | body | array of objects | yes      | Rows of [`tPri_Area`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_area.md), with column names as keys |

**Response** `200`: the [save result object](https://docs.snapfix.com/engineering-reference/api/tasks.md#save-result-object-php-apis).

```json
{
  "result": true,
  "message": "Please find the processed record count",
  "total_record_count": 1,
  "inserted_record_count": 0,
  "updated_record_count": 1,
  "insert_failed_record_count": 0,
  "update_failed_record_count": 0,
  "trigger_auto_archive": [],
  "serverTs": 1794387600000
}
```

**Errors:** `{"result": false, "message": "Data cannot be blank!"}` for an empty body. A row that fails is counted, and `result` is `false`. With the legacy queue on, a failure outside the rows comes back as the exception text, such as "invalid access!".

**Side effects:** writes [`tPri_Area`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_area.md). When the server setting `LEGACY_QUEUE_SUPPORT` is on, the rows go to [`tPri_Queue`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_queue.md), are reported as inserted, and are written after the response \[[ASK-12](https://github.com/snapfix/docs/blob/main/ASK.md#ask-12-which-settings-do-the-production-api-servers-use)]. No push is sent: area rows name no group, and the queue's update push goes only to groups named in the rows.

## POST ?action=save\_pri\_log\_areavieweduser

Saves the apps' "viewed" rows for areas, which the counts of tasks with new activity start from. Every row is inserted with a new `uuid`; a `uuid` sent with a row is replaced.

* **Auth:** as in [`save_pri_area`](#post-actionsave_pri_area).
* **Used by:** iOS: the sync (`Managers/TaskManager.swift:3045`, from `:296`) and the area list (`SnapFix/Areas/ViewModel/AreaViewModel.swift:41`); Android: the sync (`data/repository/SyncRepository.kt:694`) and the area list (`fragment/AreaFragment.kt:385`).

**Request** (JSON body)

| Name          | In   | Type             | Required | Rules                                                                                                                                                             |
| ------------- | ---- | ---------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `insert_data` | body | array of objects | yes      | Rows of [`tPri_Log_AreaViewedUser`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_log_areavieweduser.md): `uuid_tArea`, `uuid_tUser`, `fViewedTs` |

**Response** `200`: the [save result object](https://docs.snapfix.com/engineering-reference/api/tasks.md#save-result-object-php-apis).

**Errors:** as in [`save_pri_area`](#post-actionsave_pri_area).

**Side effects:** inserts the rows in [`tPri_Log_AreaViewedUser`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_log_areavieweduser.md), or in the legacy queue \[[ASK-12](https://github.com/snapfix/docs/blob/main/ASK.md#ask-12-which-settings-do-the-production-api-servers-use)]. No push.

## POST ?action=save\_pri\_log\_roomstatuschange

Saves room status changes made in the apps, then sends each saved change to the PMS the room is mapped to. A row whose `uuid` is in the log is updated; any other row is inserted.

* **Auth:** as in [`save_pri_area`](#post-actionsave_pri_area).
* **Used by:** iOS: the sync of pending status changes (`Managers/TaskManager.swift:3554`, from `:288`); Android: the sync (`data/repository/SyncRepository.kt:662`).

**Request** (JSON body)

| Name          | In   | Type             | Required | Rules                                                                                                                                                                                                                                                                                        |
| ------------- | ---- | ---------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `insert_data` | body | array of objects | yes      | Rows of [`tPri_Log_RoomStatusChange`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_log_roomstatuschange.md): `uuid`, `uuid_tRoom`, `uuid_tBuildingRoomStatusMain`, `uuid_tBuildingRoomStatusSecondary`, `uuid_enum_IntegrationSource`, `uuid_tUser_CreatedBy`, `fCreatedTs` |

**Response** `200`: the [save result object](https://docs.snapfix.com/engineering-reference/api/tasks.md#save-result-object-php-apis).

**Errors:** as in [`save_pri_area`](#post-actionsave_pri_area).

**Side effects:**

* Writes the rows in [`tPri_Log_RoomStatusChange`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_log_roomstatuschange.md), or in the legacy queue \[[ASK-12](https://github.com/snapfix/docs/blob/main/ASK.md#ask-12-which-settings-do-the-production-api-servers-use)]. Unlike the other save actions, this one doesn't run the queue after the response.
* After the response, when the save succeeded, finds the PMS of the changed rooms in the room mapping tables of Guestline, Hotsoft, Opera, Stayntouch, Cloudbeds, Jonas Chorum and Comtrol, in that order. Only the first table that maps any room of the request is used, so rooms of another PMS in the same request are not sent. Each change then goes to that PMS's integration service as a `GET` with the change's ID and the integration's Basic login \[[ASK-13](https://github.com/snapfix/docs/blob/main/ASK.md#ask-13-which-services-and-scheduled-jobs-run-in-production)]. Changes to the main statuses on a fixed list of status IDs in the code are not sent (php-apis @ 238ca4414e, `htmlphp/api/snapfix/class/class.functions.php:45329-45556`; `html/api/snapfix/index.php:4504-4510`).
* The room itself isn't changed here: the apps send the room's new status links with [`save_pri_room`](#post-actionsave_pri_room). No inspection task is created, unlike a web status change \[[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)].

## POST ?action=save\_pri\_log\_roomvieweduser

Saves the apps' "viewed" rows for rooms, so their counts of tasks with new activity start again. Every row is inserted with a new `uuid`, as for [areas](#post-actionsave_pri_log_areavieweduser).

* **Auth:** as in [`save_pri_area`](#post-actionsave_pri_area).
* **Used by:** iOS: the sync (`Managers/TaskManager.swift:3512`, from `:286`) and the room list (`SnapFix/RoomsView/ViewModels/RoomViewModel.swift:46`); Android: the sync (`data/repository/SyncRepository.kt:626`) and the room list (`fragment/RoomFragment.kt:783`).

**Request** (JSON body)

| Name          | In   | Type             | Required | Rules                                                                                                                                                             |
| ------------- | ---- | ---------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `insert_data` | body | array of objects | yes      | Rows of [`tPri_Log_RoomViewedUser`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_log_roomvieweduser.md): `uuid_tRoom`, `uuid_tUser`, `fViewedTs` |

**Response** `200`: the [save result object](https://docs.snapfix.com/engineering-reference/api/tasks.md#save-result-object-php-apis).

**Errors:** as in [`save_pri_area`](#post-actionsave_pri_area).

**Side effects:** inserts the rows in [`tPri_Log_RoomViewedUser`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_log_roomvieweduser.md), or in the legacy queue \[[ASK-12](https://github.com/snapfix/docs/blob/main/ASK.md#ask-12-which-settings-do-the-production-api-servers-use)]. No push.

## POST ?action=save\_pri\_room

Saves room rows from the apps' sync. A row whose `uuid` is in [`tPri_Room`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_room.md) is updated; any other row is inserted. Both apps send the whole room row, status links included, so a status changed in an app reaches the room here.

* **Auth:** as in [`save_pri_area`](#post-actionsave_pri_area).
* **Used by:** iOS: the sync of rooms changed in the app (`Managers/TaskManager.swift:3468`, from `:284`, with the row from `SnapFix/RoomsView/Models/RoomModel.swift:247-254`); Android: the sync (`data/repository/SyncRepository.kt:646`, with the row from `utils/JsonParserUtils.java:611-654`).

**Request** (JSON body)

| Name          | In   | Type             | Required | Rules                                                                                                                   |
| ------------- | ---- | ---------------- | -------- | ----------------------------------------------------------------------------------------------------------------------- |
| `insert_data` | body | array of objects | yes      | Rows of [`tPri_Room`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_room.md), with column names as keys |

**Response** `200`: the [save result object](https://docs.snapfix.com/engineering-reference/api/tasks.md#save-result-object-php-apis).

**Errors:** as in [`save_pri_area`](#post-actionsave_pri_area).

**Side effects:** writes [`tPri_Room`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_room.md), or the legacy queue \[[ASK-12](https://github.com/snapfix/docs/blob/main/ASK.md#ask-12-which-settings-do-the-production-api-servers-use)]. No PMS forward, inspection task or push: the status change reaches the PMS through [`save_pri_log_roomstatuschange`](#post-actionsave_pri_log_roomstatuschange).

## Room and area permissions

The checks the endpoints above name. All api\_php\_live\_v2 routes first check the token and load the caller ([API conventions](https://docs.snapfix.com/engineering-reference/api.md#what-a-user-token-does-not-prove)).

* **Writes check the site.** Creating, changing and deleting one room or area, and the priority and status changes, use the `operate` check of `RoomPolicy` and `AreaPolicy`. The caller passes with a [`tPri_UserParent`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_userparent.md) row for the site, of either user type, or with a current relation ([`tPri_UserBusiness`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_userbusiness.md)) to any group of the site. Relations to deleted groups or deleted sites don't count, nor do sites the caller was removed from. The admin filter in that check is commented out (api\_php\_live\_v2 @ ef3c4319f6, `app/Services/UserParentService.php:21-61`), so any group member can create, rename, delete and re-prioritise rooms and areas, though the web shows these actions only to admins \[[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)]. Failing gives `403` "Access denied".
* **Bulk deletes need a site admin.** The two `delete/multi` routes use the site's `operate` check instead, which needs a `tPri_UserParent` row with user type `admin` (`app/Policies/ParentPolicy.php:19-32`).
* **Statuses must be in the site.** A status change needs statuses from the sections of the site's building; another site's status gives `403` "Access denied". The API doesn't check a status's `readOnly` flag, which only the web and the apps respect.
* **Reads check only the token**. Lists by `parentUuid`, details by ID, the status catalog, the update counts and the visited records work for any site. The group and task lists of a room or area show only the caller's own groups and the tasks the caller can see.
* **A site with no building.** Lists come back empty. The bulk routes and the status catalog answer `404`. Creating a room or an area creates the building.
* **Soft delete.** A deleted room or area keeps its row, with `fDeleted` 1 and `fDeletedTs` set; it stops showing in lists and details. Its task links in [`tPri_JobRoom`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_jobroom.md) and [`tPri_JobArea`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_jobarea.md) are not changed.

## Status change side effects

What `PUT /v1/app/rooms/{uuid}/status` and the two bulk status routes do for each room whose status they change. The apps' sync path works differently: see [`save_pri_log_roomstatuschange`](#post-actionsave_pri_log_roomstatuschange).

* **Log row:** one row per room in [`tPri_Log_RoomStatusChange`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_log_roomstatuschange.md), written inside the request, with the new main status and the secondary status sent, empty when it was left out.
* **Inspection task:** when housekeeping is on for the site (its building's `ai_task_management_enabled`), and the room moves from "OUT OF ORDER" or "OUT OF SERVICE", as its main or secondary status in any case, to statuses that are both available, the server creates a red inspection task for the room. It doesn't when the room already has an open inspection task (red, not deleted or archived). The task goes to the inspection group of the building's first task rule that creates inspections, or else of its first rule that names an inspection group ([`tPri_RoomStatus_TaskRules`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_roomstatus_taskrules.md)); without such a rule, to the site's first task group whose name starts with "HouseKeeping"; with neither, no task is created. It is inserted with its status log and chat lines, and no push. When the caller has no relation to that group, the caller is added to it as an admin (`app/Services/Housekeeping/UnavailableRoomReturnInspectionService.php:73-186`). The [Housekeeping API](https://docs.snapfix.com/engineering-reference/api/housekeeping.md) has the rest of the inspection flow.
* **PMS push:** one queued `MapRoomStatus` job per request, which waits 10 seconds, then sends each change to every PMS integration the building has, as a `GET` with the change's ID and the integration's Basic login. It skips a change that a newer change for the same room has already overtaken (`app/Jobs/MapRoomStatus.php:27-111`) \[[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)]. The integrations are in the [Integrations API](https://docs.snapfix.com/engineering-reference/api/integrations.md).
* **No app push:** the room and area endpoints send no push notifications. Every call is logged as for the [Tasks API](https://docs.snapfix.com/engineering-reference/api/tasks.md#common-side-effects).

## Room object

A room as the room endpoints return it. Timestamps are milliseconds since the epoch.

| Field                                          | Type                                              | Meaning                                                                                                                                                                                                                  |
| ---------------------------------------------- | ------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `uuid`                                         | string                                            | The room's ID                                                                                                                                                                                                            |
| `buildingUuid`                                 | string                                            | The site's building ([`tPri_Building`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_building.md))                                                                                                       |
| `parentUuid`                                   | string or null                                    | The site. Set only by [`GET /v1/app/rooms/{uuid}`](#get-v1approomsuuid); `null` in lists and after changes                                                                                                               |
| `name`                                         | string                                            | The room's name or number (`fName`), such as "Room 101"                                                                                                                                                                  |
| `largeTextTitle`, `description`, `instruction` | string or null                                    | Large text, description and instructions                                                                                                                                                                                 |
| `priority`                                     | integer                                           | The old flag: `1` when the room has a priority, otherwise `0`                                                                                                                                                            |
| `priorityLevel`                                | integer                                           | A priority code (see the table notes); `20` when the flag is `1` and no level is stored                                                                                                                                  |
| `occupied`                                     | integer                                           | `1` or `0`: from the reservation's occupancy when the answer has a reservation, otherwise the stored flag                                                                                                                |
| `image`, `videoHeader`                         | string or null                                    | Photo and video addresses                                                                                                                                                                                                |
| `enumRoomType`                                 | string or null                                    | The room type from the PMS, such as its name                                                                                                                                                                             |
| `enumOrigin`                                   | integer                                           | Where the room was created, as the codes of [`POST /v1/app/areas`](#post-v1appareas)                                                                                                                                     |
| `location`                                     | object                                            | `lat` and `lng`, as stored                                                                                                                                                                                               |
| `priorityNumber`                               | integer                                           | Stored sort number                                                                                                                                                                                                       |
| `inActive`, `archived`, `visible`              | integer                                           | `1` or `0`                                                                                                                                                                                                               |
| `createdTs`, `modifiedTs`                      | integer                                           | When the room was created and last changed                                                                                                                                                                               |
| `archivedTs`                                   | integer or null                                   | As stored                                                                                                                                                                                                                |
| `reservation`                                  | [reservation object](#reservation-object) or null | The room's guests for today; `null` when the endpoint doesn't build it, as after a change                                                                                                                                |
| `status`, `statusSecondary`                    | [room status object](#room-status-object) or null | The main and secondary status; only when the endpoint includes statuses                                                                                                                                                  |
| `jobsColorCount`                               | object                                            | `red`, `amber` (yellow counted as amber) and `green` counts of the room's tasks the caller can see, that aren't deleted or archived, in active task groups and not in the future; only when the endpoint includes counts |

## Reservation object

The `reservation` part of a room, built from the room's guest stays ([`tPri_RoomGuestStatus`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_roomgueststatus.md)), not from the tasks. It holds guests' names, not their contact details.

| Field                                             | Type             | Meaning                                                                                                                                                         |
| ------------------------------------------------- | ---------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `roomName`, `roomType`                            | string or null   | The room's name and type                                                                                                                                        |
| `floor`, `capacity`                               | number or string | The room's floor number and guest capacity; `"NA"` when empty                                                                                                   |
| `occupancy`                                       | string           | `Occupied` or `Vacant`: from the secondary status's name when it says so (such as "Occupied", "Vacant", "Stayover" or "Check-out"), otherwise from today's stay |
| `permanentNotes`                                  | string or null   | The room's permanent notes                                                                                                                                      |
| `departingGuest`, `inHouseGuest`, `arrivingGuest` | object or null   | Today's stays: the one leaving, the one staying, and the one arriving                                                                                           |

Each stay has `guests` (the names, joined with commas), `status` (the stay's status, such as `checked-in` or `reserved`), `eta` and `etd` (check-in and check-out time, with "(Early Check-In Applied)" or "(Late Check-Out Applied)" added when they apply), `bookingReference`, `vipBooking` (`Yes` or `No`), `vipCode`, `adultCount`, `childCount`, `hskTraces` (housekeeping notes) and `preferences`.

```json
{
  "roomName": "Room 101",
  "floor": 1,
  "occupancy": "Occupied",
  "capacity": 2,
  "roomType": "Double",
  "permanentNotes": "Extra towels in wardrobe",
  "departingGuest": null,
  "inHouseGuest": {
    "guests": "Jane Smith",
    "status": "checked-in",
    "eta": "2026-11-12 14:00:00",
    "etd": "2026-11-15 11:00:00",
    "bookingReference": "BK-4471",
    "vipBooking": "No",
    "vipCode": null,
    "adultCount": 1,
    "childCount": 0,
    "hskTraces": null,
    "preferences": "Late check-out"
  },
  "arrivingGuest": null
}
```

## Area object

An area as the area endpoints return it: the fields of the [room object](#room-object) without `occupied`, `reservation`, `status` and `statusSecondary`, and with these.

| Field            | Type    | Meaning                                                                     |
| ---------------- | ------- | --------------------------------------------------------------------------- |
| `enumAreaType`   | integer | The area type, as stored                                                    |
| `jobsColorCount` | object  | As for rooms, over the area's tasks; only when the endpoint includes counts |

`parentUuid` is set only by [`GET /v1/app/areas/{uuid}`](#get-v1appareasuuid), and `null` in lists and after changes.

## Room status object

A main or secondary status of a room, or of the site's catalog.

| Field                   | Type              | Meaning                                                                                                                                              |
| ----------------------- | ----------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
| `uuid`                  | string            | The status ID                                                                                                                                        |
| `name`                  | string            | The status name, such as "CLEANED"                                                                                                                   |
| `color`                 | string or null    | The colour name for the status: `red`, `amber` or `green` for the default statuses; main statuses on staging also use `yellow` and `blue`            |
| `statusIcon`, `iconUrl` | string or null    | The icon's name and address                                                                                                                          |
| `readOnly`              | string or integer | `1` when the web and the apps don't let people pick the status by hand. Main statuses give it as text (`"0"`, `"1"`), secondary statuses as a number |
| `type`                  | string            | `main` or `secondary`; only in the status catalog                                                                                                    |

## Room status section object

A section of the site's room status catalog, from [`GET /v1/app/parents/{uuid}/room-statuses`](#get-v1appparentsuuidroom-statuses).

| Field      | Type   | Meaning                                                                                                                               |
| ---------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------- |
| `uuid`     | string | The section's ID ([`tPri_BuildingRoomSection`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_buildingroomsection.md)) |
| `name`     | string | The section's name                                                                                                                    |
| `statuses` | array  | The section's main and secondary [statuses](#room-status-object), in one list, main first                                             |

## Group object

A group in a room's or area's group list: a group the caller is in that has tasks there the caller can see.

| Field                                                                    | Type           | Meaning                                                                                                       |
| ------------------------------------------------------------------------ | -------------- | ------------------------------------------------------------------------------------------------------------- |
| `uuid`                                                                   | string         | The group's ID ([`tPri_Business`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_business.md)) |
| `name`                                                                   | string         | The group's name                                                                                              |
| `image`                                                                  | string or null | The group's picture                                                                                           |
| `address`, `inActive`, `purpose`, `instructions`, `notificationDisabled` | null           | The group's other fields; these lists don't load them, so they are always `null`                              |

## Update count object

One entry of a `get-updates` answer.

| Field                    | Type    | Meaning                                                                                                                                      |
| ------------------------ | ------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
| `roomUuid` or `areaUuid` | string  | The room or area                                                                                                                             |
| `updatedJobCount`        | integer | The room's or area's tasks the caller can see, not archived, whose activity time (`fJobChatModifiedTs`) is later than the caller's last view |

## Bulk result object

The `data` of a bulk change or delete.

| Field   | Type    | Meaning                                                                                                       |
| ------- | ------- | ------------------------------------------------------------------------------------------------------------- |
| `total` | integer | The rooms or areas changed or deleted. Rooms that already had the new priority or main status are not counted |


---

# 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/engineering-reference/api/rooms.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.
