> 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/housekeeping.md).

# Housekeeping 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/housekeeping.md).
{% endhint %}

The day's housekeeping work: staff sessions and working hours, the unassigned and assigned task lists behind the timeline, assigning, auto-assigning and resetting tasks, manual cleans and inspections, the follow-up pair after a rejected inspection, a room's housekeeping groups, and the Ops Dashboard's housekeeping reports. Rules for tasks in general (who may see or change a task, the task object, the side effects of a change) are in the [Tasks API](https://docs.snapfix.com/engineering-reference/api/tasks.md) and are linked from here, not repeated.

Housekeeping tasks are tasks with `enum_JobType` 45 (clean) or 46 (inspection) in [`tPri_Job`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_job.md). A clean has `fCleaningType` `stayover`, `departure`, `correction` or `standard`, and a `standard` clean also has an `fCleaningSubType`. Each clean links to its inspection in [`tPri_JobLink`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_joblink.md): the clean is the master row, the inspection the tagged one. `assignmentType` is 0 (default), 1 (placed by auto-assign) or 2 (placed by hand).

* **Services:** `api_php_live_v2` at `https://z4.snapfix.com` (`/v1/app/housekeeping/…`, `/v1/app/rooms/{uuid}/hk-businesses`, `/v1/app/tasks/generate-tasks`, and `/v1/reset-tasks` only when `APP_ENV` is `development`); `php-apis web` at `https://z1.snapfix.com/api/snapfix/web/index.php` (its 16 actions have no caller); `ops_dashboard_be` at `https://dashboardapp.snapfix.com` (`/api/reports/…`; the web app's `taskDashboardApiUrl`, web\_app\_v2 @ 0989b8e685, `src/environments/environment.production.ts:18`).
* **Auth:** api\_php\_live\_v2: user token (authpy access JWT in `Authorization: Bearer`). The writes check what their section says: site admin (`ParentPolicy::operate`: the caller's [`tPri_UserParent`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_userparent.md) row has `user_type` admin) for working hours, staff settings, resets and auto-assign; "assign user" in the task's group for reassignment and the bulk routes; "create task" in the group for manual tasks ([task permissions](https://docs.snapfix.com/engineering-reference/api/tasks.md#task-permissions)). Four reads check nothing beyond the token: [`working-hours/list`](#post-v1apphousekeepingworking-hourslist), [`assigned-tasks/list`](#post-v1apphousekeepingassigned-taskslist), [`manual-clean-types`](#get-v1apphousekeepingmanual-clean-types) and [`rooms/{uuid}/hk-businesses`](#get-v1approomsuuidhk-businesses). The auto-assign and manual-task status routes answer anyone who has the task ID. php-apis web: see [Authentication](https://docs.snapfix.com/engineering-reference/api.md#authentication); its actions take the user from the request. ops\_dashboard\_be: user token, an HS256 JWT checked with `JWT_SECRET`, for sites the user administers ([Report scope](#report-scope)).
* **Used by:** web\_app\_v2 (the housekeeping page, the create dialog, the task create and detail flows, the task approval), iOS (timeline, create task, assign, snooze, approval), Android (housekeeping tabs, create sheet, reschedule, snooze, approval, sync), ops\_dashboard\_fe (housekeeping reports), snapfix\_ai\_agent (`housekeeping_hours`); 31 of the 60 endpoints have no known caller \[[ASK-11](https://github.com/snapfix/docs/blob/main/ASK.md#ask-11-which-unused-api-endpoints-are-still-needed)].
* **Answers:** api\_php\_live\_v2 answers `{"status": "success", "message": "Operation was successful", "data": ...}`, or `{"status": "error", "message": "..."}` with the codes in [API conventions](https://docs.snapfix.com/engineering-reference/api.md#responses). ops\_dashboard\_be answers the report JSON as is, and `{"error": "..."}` on failure ([Report scope](#report-scope)).

The product: [Staff schedule](https://docs.snapfix.com/product/features/housekeeping/staff-schedule.md), [Assigning housekeeping tasks](https://docs.snapfix.com/product/features/housekeeping/housekeeping-assignment.md), [Cleaning tasks](https://docs.snapfix.com/product/features/housekeeping/cleaning-tasks.md), [Inspections](https://docs.snapfix.com/product/features/housekeeping/inspections.md) and [Housekeeping reports](https://docs.snapfix.com/product/features/housekeeping/housekeeping-reports.md). The screens: [Housekeeping](https://docs.snapfix.com/how-the-apps-work/screens/housekeeping.md) and the [Ops Dashboard](https://docs.snapfix.com/how-the-apps-work/screens/reports/ops-dashboard.md).

| Method    | Path                                                                                                               | Service            | Purpose                                                                                                                                                                        |
| --------- | ------------------------------------------------------------------------------------------------------------------ | ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| POST      | [`/v1/app/housekeeping/assigned-tasks/list`](#post-v1apphousekeepingassigned-taskslist)                            | api\_php\_live\_v2 | Each person on the schedule with today's assigned tasks                                                                                                                        |
| POST      | `/v1/app/housekeeping/auto-assign-tasks`                                                                           | api\_php\_live\_v2 | Queue an auto-assign run (no caller)                                                                                                                                           |
| POST      | [`/v1/app/housekeeping/auto-assign-tasks-async`](#post-v1apphousekeepingauto-assign-tasks-async)                   | api\_php\_live\_v2 | Auto-assign today's housekeeping tasks; the run finishes inside the request                                                                                                    |
| GET       | [`/v1/app/housekeeping/auto-assign-tasks/status/{taskId}`](#get-v1apphousekeepingauto-assign-tasksstatustaskid)    | api\_php\_live\_v2 | Status of an auto-assign run                                                                                                                                                   |
| GET       | [`/v1/app/housekeeping/bulk-actions/status/{taskId}`](#get-v1apphousekeepingbulk-actionsstatustaskid)              | api\_php\_live\_v2 | Status of a queued housekeeping bulk action                                                                                                                                    |
| POST      | [`/v1/app/housekeeping/bulk-reassignment`](#post-v1apphousekeepingbulk-reassignment)                               | api\_php\_live\_v2 | Assign up to 100 housekeeping tasks in one request                                                                                                                             |
| POST      | [`/v1/app/housekeeping/bulk-reassignment-async`](#post-v1apphousekeepingbulk-reassignment-async)                   | api\_php\_live\_v2 | The same, queued                                                                                                                                                               |
| POST      | `/v1/app/housekeeping/bulk-reset`                                                                                  | api\_php\_live\_v2 | Reset up to 100 housekeeping tasks in one request (no caller) \[[ASK-11](https://github.com/snapfix/docs/blob/main/ASK.md#ask-11-which-unused-api-endpoints-are-still-needed)] |
| POST      | [`/v1/app/housekeeping/bulk-reset-async`](#post-v1apphousekeepingbulk-reset-async)                                 | api\_php\_live\_v2 | Move up to 100 housekeeping tasks back to the unassigned pool, queued                                                                                                          |
| GET       | [`/v1/app/housekeeping/manual-clean-types`](#get-v1apphousekeepingmanual-clean-types)                              | api\_php\_live\_v2 | The clean types a site offers for manual tasks                                                                                                                                 |
| POST      | [`/v1/app/housekeeping/manual-hk-task/bulk`](#post-v1apphousekeepingmanual-hk-taskbulk)                            | api\_php\_live\_v2 | One manual housekeeping task per room, queued                                                                                                                                  |
| GET       | [`/v1/app/housekeeping/manual-hk-task/bulk/status/{taskId}`](#get-v1apphousekeepingmanual-hk-taskbulkstatustaskid) | api\_php\_live\_v2 | Status of a bulk creation of manual housekeeping tasks                                                                                                                         |
| PUT       | `/v1/app/housekeeping/move-to/{section}`                                                                           | api\_php\_live\_v2 | Move tasks to a section (`backlogMulti`) (no caller)                                                                                                                           |
| POST      | [`/v1/app/housekeeping/reassignment/{uuid}`](#post-v1apphousekeepingreassignmentuuid)                              | api\_php\_live\_v2 | Assign, move or unassign one housekeeping task                                                                                                                                 |
| POST      | [`/v1/app/housekeeping/reject-tasks`](#post-v1apphousekeepingreject-tasks)                                         | api\_php\_live\_v2 | Create the correction clean and inspection after a rejected inspection                                                                                                         |
| GET       | [`/v1/app/housekeeping/reset-tasks-async/{parentUuid}`](#get-v1apphousekeepingreset-tasks-asyncparentuuid)         | api\_php\_live\_v2 | Reset a site's red tasks, queued (`resetRedJobsAsync`)                                                                                                                         |
| GET       | `/v1/app/housekeeping/reset-tasks/{parentUuid}`                                                                    | api\_php\_live\_v2 | Reset a site's red tasks at once (`resetRedJobs`) (no caller)                                                                                                                  |
| GET       | [`/v1/app/housekeeping/reset-user-tasks-async/{userUuid}`](#get-v1apphousekeepingreset-user-tasks-asyncuseruuid)   | api\_php\_live\_v2 | Reset one person's red tasks, queued (`resetUserRedJobsAsync`)                                                                                                                 |
| GET       | `/v1/app/housekeeping/reset-user-tasks/{userUuid}`                                                                 | api\_php\_live\_v2 | Reset one person's red tasks at once (`resetUserRedJobs`) (no caller)                                                                                                          |
| POST      | [`/v1/app/housekeeping/staff-work-settings`](#post-v1apphousekeepingstaff-work-settings)                           | api\_php\_live\_v2 | Save each person's default hours and self-check limit                                                                                                                          |
| POST      | [`/v1/app/housekeeping/tasks`](#post-v1apphousekeepingtasks)                                                       | api\_php\_live\_v2 | The site's unassigned housekeeping tasks                                                                                                                                       |
| POST      | [`/v1/app/housekeeping/working-hours`](#post-v1apphousekeepingworking-hours)                                       | api\_php\_live\_v2 | Replace the sessions of the staff in the request                                                                                                                               |
| POST      | [`/v1/app/housekeeping/working-hours/list`](#post-v1apphousekeepingworking-hourslist)                              | api\_php\_live\_v2 | A site's staff sessions for one weekday                                                                                                                                        |
| GET       | [`/v1/app/rooms/{uuid}/hk-businesses`](#get-v1approomsuuidhk-businesses)                                           | api\_php\_live\_v2 | The cleaning and inspection groups of a room                                                                                                                                   |
| POST      | `/v1/app/tasks/generate-tasks`                                                                                     | api\_php\_live\_v2 | Generate the day's room tasks for a site and auto-assign them (`generateTasks`) (no caller)                                                                                    |
| GET       | `/v1/reset-tasks/{parentUuid}`                                                                                     | api\_php\_live\_v2 | Reset a site's red tasks; exists only when `APP_ENV` is `development`, and has no login middleware (no caller)                                                                 |
| ANY       | `?action=create_hk_tasks`                                                                                          | php-apis web       | Create housekeeping tasks (no caller)                                                                                                                                          |
| ANY       | `?action=hkbuildingrooms`                                                                                          | php-apis web       | List a building's rooms for housekeeping (no caller)                                                                                                                           |
| ANY       | `?action=hkbuildings`                                                                                              | php-apis web       | List buildings for housekeeping (no caller)                                                                                                                                    |
| ANY       | `?action=hkroomdetail`                                                                                             | php-apis web       | Get a room's housekeeping details (no caller)                                                                                                                                  |
| ANY       | `?action=hkroomsoverview`                                                                                          | php-apis web       | Housekeeping rooms overview (no caller)                                                                                                                                        |
| ANY       | `?action=hkroomsquery`                                                                                             | php-apis web       | Query rooms for housekeeping (no caller)                                                                                                                                       |
| ANY       | `?action=hkstayoverschedule`                                                                                       | php-apis web       | Housekeeping stayover schedule (no caller)                                                                                                                                     |
| ANY       | `?action=housekeeping_b2b_guests_report`                                                                           | php-apis web       | B2B guests report (no caller)                                                                                                                                                  |
| ANY       | `?action=housekeeping_properties`                                                                                  | php-apis web       | List housekeeping properties (no caller)                                                                                                                                       |
| ANY       | `?action=housekeeping_room_details`                                                                                | php-apis web       | Get a room's details (no caller)                                                                                                                                               |
| ANY       | `?action=housekeeping_room_guests`                                                                                 | php-apis web       | Get a room's guests (no caller)                                                                                                                                                |
| ANY       | `?action=housekeeping_room_tasks`                                                                                  | php-apis web       | Get a room's tasks (no caller)                                                                                                                                                 |
| ANY       | `?action=housekeeping_room_timeline`                                                                               | php-apis web       | Get a room's timeline (no caller)                                                                                                                                              |
| ANY       | `?action=housekeeping_rooms`                                                                                       | php-apis web       | List a property's rooms (no caller)                                                                                                                                            |
| ANY       | `?action=housekeeping_stayover_schedule_report`                                                                    | php-apis web       | Stayover schedule report (no caller)                                                                                                                                           |
| ANY       | `?action=housekeeping_turnover_report`                                                                             | php-apis web       | Room turnover report (no caller)                                                                                                                                               |
| POST      | [`/api/reports/accessible-properties`](#post-apireportsaccessible-properties)                                      | ops\_dashboard\_be | The sites the user can open in the housekeeping reports                                                                                                                        |
| GET, POST | `/api/reports/at-a-glance/avg-clean-duration`                                                                      | ops\_dashboard\_be | At a glance: average clean duration (no caller)                                                                                                                                |
| GET, POST | `/api/reports/at-a-glance/avg-inspection-duration`                                                                 | ops\_dashboard\_be | At a glance: average inspection duration (no caller)                                                                                                                           |
| GET, POST | `/api/reports/at-a-glance/guest-turnaround`                                                                        | ops\_dashboard\_be | At a glance: guest turnaround (no caller)                                                                                                                                      |
| GET, POST | `/api/reports/at-a-glance/inspection-pass-rate`                                                                    | ops\_dashboard\_be | At a glance: inspection pass rate (no caller)                                                                                                                                  |
| GET, POST | `/api/reports/at-a-glance/inspector-turnaround`                                                                    | ops\_dashboard\_be | At a glance: inspector turnaround (no caller)                                                                                                                                  |
| GET, POST | `/api/reports/at-a-glance/mobile-completion`                                                                       | ops\_dashboard\_be | At a glance: mobile completion (no caller)                                                                                                                                     |
| POST      | [`/api/reports/at-a-glance/summary`](#post-apireportsat-a-glancesummary)                                           | ops\_dashboard\_be | All eight At a glance tiles at once                                                                                                                                            |
| GET, POST | `/api/reports/at-a-glance/total-cleans`                                                                            | ops\_dashboard\_be | At a glance: total cleans (no caller)                                                                                                                                          |
| GET, POST | `/api/reports/at-a-glance/variance-by-clean-type`                                                                  | ops\_dashboard\_be | At a glance: variance by clean type (no caller)                                                                                                                                |
| POST      | [`/api/reports/b2b-guests`](#post-apireportsb2b-guests)                                                            | ops\_dashboard\_be | Guests leaving one stay and arriving for another on the same day                                                                                                               |
| POST      | [`/api/reports/cleaning-history/housekeeper-summary`](#post-apireportscleaning-historyhousekeeper-summary)         | ops\_dashboard\_be | Cleaning history: summary per housekeeper                                                                                                                                      |
| POST      | [`/api/reports/cleaning-history/tasks`](#post-apireportscleaning-historytasks)                                     | ops\_dashboard\_be | Cleaning history: completed cleans, paged                                                                                                                                      |
| POST      | [`/api/reports/cleans-by-room-type`](#post-apireportscleans-by-room-type)                                          | ops\_dashboard\_be | Completed cleans per room type                                                                                                                                                 |
| POST      | [`/api/reports/housekeeper-benchmark`](#post-apireportshousekeeper-benchmark)                                      | ops\_dashboard\_be | Housekeeper benchmark report                                                                                                                                                   |
| POST      | [`/api/reports/inspector-benchmark`](#post-apireportsinspector-benchmark)                                          | ops\_dashboard\_be | Inspector benchmark report                                                                                                                                                     |
| POST      | [`/api/reports/room-status-log`](#post-apireportsroom-status-log)                                                  | ops\_dashboard\_be | Room status changes of the last seven days                                                                                                                                     |
| POST      | [`/api/reports/training-needs`](#post-apireportstraining-needs)                                                    | ops\_dashboard\_be | Training needs report \[[ASK-94](https://github.com/snapfix/docs/blob/main/ASK.md#ask-94-should-dummy1-show-invented-training-needs-data-in-production)]                       |

Notes on the table:

* A row marked "(no caller)" has no caller in the pinned clones. Each path, action name and endpoint key was searched in every clone; the iOS `ApiEndpointManager.swift` and Android `APIEndPointUtils.java` registries and uncalled client functions are not callers. The PMS services call `/v1/internal/rooms/{uuid}/generate-tasks`, not `/v1/app/tasks/generate-tasks`.
* The three synchronous resets, `bulk-reset`, `reset-tasks` and `reset-user-tasks`, have no caller: the web calls only their `-async` versions, and iOS and Android call neither version \[[ASK-11](https://github.com/snapfix/docs/blob/main/ASK.md#ask-11-which-unused-api-endpoints-are-still-needed)].
* `generate-tasks` creates the day's tasks and then fails before it assigns them, and `/v1/reset-tasks/{parentUuid}` fails for lack of a signed-in user.
* The reassignment and bulk routes also exist under `/v1/internal/housekeeping/` for scripts, with no caller; they are in the [Internal API](https://docs.snapfix.com/engineering-reference/api/internal.md).
* The ten called `/api/reports` rows show `POST`, the method ops\_dashboard\_fe sends (ops\_dashboard\_fe @ bbb2959b3b, `api/hkReports.js:14-22`). Every `/api/reports` route also accepts `GET`; the eight single-tile routes keep "GET, POST" because no client calls them. The dashboard reads all eight tiles from [`at-a-glance/summary`](#post-apireportsat-a-glancesummary).
* The 16 php-apis actions are the newer housekeeping queries of \[[ASK-11](https://github.com/snapfix/docs/blob/main/ASK.md#ask-11-which-unused-api-endpoints-are-still-needed)]. The SQL of the three `housekeeping_room_*` actions still holds at php-apis @ 238ca4414e (`htmlphp/api/snapfix/class/housekeeping.functions.php:129-130`, `:284`, `:908`).
* The timeline's print calls `?action=user_tasks_schedule_report` and polls `?action=user_reports` on php-apis web, and the create dialog's room search calls [`POST /v1/app/rooms/list`](https://docs.snapfix.com/engineering-reference/api/rooms.md#post-v1approomslist). They are documented with the [Reports](https://docs.snapfix.com/engineering-reference/api/reports.md) and [Rooms](https://docs.snapfix.com/engineering-reference/api/rooms.md) groups.

## POST /v1/app/housekeeping/assigned-tasks/list

Lists the staff on the schedule for a weekday and, for each person, the tasks assigned to them with a start time today, with their rooms, guests and the room's stays. The web, iOS and Android timelines use it.

* **Auth:** user token. No membership check: any signed-in user can read another site's staff, tasks and guest details by naming its `parentUuid`.
* **Used by:** web\_app\_v2 (`HousekeepingHttpService.getHousekeepingAssignedTasksData`, the timeline board), iOS (`HOUSEKEEPING_ASSIGNED_TASKS_LIST`: `HousekeepingTimelineViewModel` and `TimelineReassignmentService`, the timeline), Android (`HousekeepingTasksRepository.getAssignedTasksEnvelope`, the assigned tab and timeline; `getAssignedUserTasksBlocks`, the assign sheet).

**Request** (form data or JSON; the server reads the query string and the body alike)

| Name                                                                                                                                  | In            | Type             | Required | Rules                                                                                                                                       |
| ------------------------------------------------------------------------------------------------------------------------------------- | ------------- | ---------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
| `parentUuid`                                                                                                                          | query or body | string           | yes      | The site. Not checked to exist: an unknown site gives an empty list                                                                         |
| `date`, `role`, `roles`, `userUuid`                                                                                                   | body          |                  | no       | As in [working-hours/list](#post-v1apphousekeepingworking-hourslist). `date` picks the sessions' weekday only; the tasks are always today's |
| `userUuids`                                                                                                                           | body          | array of string  | no       | Only these people                                                                                                                           |
| `colors`                                                                                                                              | body          | array of string  | no       | `red`, `amber` or `green`; `amber` also matches the old `yellow`                                                                            |
| `priorityLevel`                                                                                                                       | body          | array of integer | no       | `0`, `1`, `5`, `10`, `20` or `30`; `20` also matches tasks with the old star flag                                                           |
| `roomStatus`                                                                                                                          | body          | array of string  | no       | Room main status UUIDs                                                                                                                      |
| `queued`                                                                                                                              | body          | `0` or `1`       | no       | `1`: only tasks whose room is in the reservation queue                                                                                      |
| `stayoverClean`, `departureClean`, `correctionClean`, `touchupClean`, `studioTidy`, `trashAndTowel`, `preArrivalBlitz`, `inspections` | body          | `0` or `1`       | no       | Only these clean kinds; each flag set adds its kind                                                                                         |
| `occupied`, `arrival`                                                                                                                 | body          | `0` or `1`       | no       | Only tasks whose room is occupied (`occupied`) or has an arriving guest (`arrival`); with both, the room must match both                    |
| `sortBy`                                                                                                                              | query or body | string           | no       | `start`, `roomNumber`, `priorityLevel` or `taskStatus`                                                                                      |
| `orderBy`                                                                                                                             | query or body | `asc` or `desc`  | no       | Default `asc`                                                                                                                               |

Each person's tasks are always ordered by start time first, so `start`, `priorityLevel` and `taskStatus` only order tasks that start at the same moment, and `desc` does not reverse the start order. `roomNumber` sorts each person's tasks by the name of their first room.

**Response** `200`: `data` is a list of [staff schedule objects](#staff-schedule-object), one per person with a session that weekday, ordered by their earliest session. Each has `user` (with `totalTime`), `staffWorkSettings` (always `null` here) and `assignedJobs`, a list of [assigned task objects](#assigned-task-object). There is no `sessions` key.

```json
{
  "status": "success",
  "message": "Operation was successful",
  "data": [
    {
      "user": { "uuid": "user-100", "name": "Jane", "image": null, "username": "jane", "sessionRole": "hk", "totalTime": 5400000 },
      "staffWorkSettings": null,
      "assignedJobs": [
        {
          "uuid": "job-400",
          "title": "Room 101 - Stayover Clean",
          "enumType": 45,
          "inspectJobUuid": "job-401",
          "cleaningJobUuid": null,
          "shortTitle": "101",
          "assignmentType": 1,
          "cleaningType": "stayover",
          "cleaningSubType": null,
          "status": { "uuid": "status-201", "name": "amber" },
          "businessInfo": { "businessUuid": "group-200", "businessName": "Housekeeping", "businessImage": null },
          "priorityLevel": 10,
          "start": 1794387600000,
          "end": 1794389400000,
          "rooms": [{ "uuid": "room-500", "name": "Room 101" }],
          "reservation": null
        }
      ]
    }
  ]
}
```

**Errors:** `422` for a missing `parentUuid`, a `date` that is not `Y-m-d`, or an unknown `role`, `colors`, `priorityLevel` or `sortBy` value.

**Side effects:** none. The rooms' stays are loaded for display only.

## POST /v1/app/housekeeping/auto-assign-tasks-async

Assigns today's unassigned housekeeping tasks to the staff on today's schedule, and answers with a task ID for the status route once the run has finished. Despite its name it runs the whole assignment inside the request; the caller-less `auto-assign-tasks` queues the same run instead.

* **Auth:** user token; the caller must be the site's admin (`operate` on `parentUuid`), otherwise `403` "Access denied".
* **Used by:** web\_app\_v2 (`HousekeepingHelperService`, through `HousekeepingHttpService.autoAssignTasksAsync`: the "Auto Assign Tasks" button). iOS and Android do not call it.

**Request** (form data)

| Name         | In   | Type       | Required | Rules                                                                                                                                                                                                              |
| ------------ | ---- | ---------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `parentUuid` | body | string     | yes      | The site                                                                                                                                                                                                           |
| `keepManual` | body | `0` or `1` | no       | Default `1`: cleans placed by hand, and their linked inspections, keep their assignees. `0`: they go back to the pool too. The web asks "Do you want to auto-assign manually assigned tasks?" and sends the answer |

The run first unassigns the red tasks with a start time today of everyone on today's schedule, except the ones `keepManual` protects. It then picks the site's housekeeping tasks as [POST /v1/app/housekeeping/tasks](#post-v1apphousekeepingtasks) does, in the groups the caller can see, cleans before inspections, and asks the assignment provider for a plan. The provider is the server setting `AUTOASSIGN_PROVIDER` (`config/autoassign.php`, default `ai_optimized`); the production value is not in the repo \[[ASK-91](https://github.com/snapfix/docs/blob/main/ASK.md#ask-91-which-auto-assign-provider-runs-in-production-and-may-it-send-data-to-an-ai-service)].

**Response** `200`: the run has finished when this answers; the status route then reports `completed`, or `failed` with the error.

```json
{
  "status": "success",
  "message": "Operation was successful",
  "data": { "taskId": "{uuid}", "message": "Auto assignment started" }
}
```

**Errors:** `403` "Access denied" for a caller who is not the site's admin; `422` for a missing `parentUuid` or a `keepManual` other than 0 or 1.

**Side effects:**

* The unassigned red tasks lose their time range, their `assignmentType` goes back to 0 and their [`tPri_JobUserAssigned`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_jobuserassigned.md) rows are soft-deleted.
* Each planned task gets its start, duration, priority and `assignmentType` 1 in [`tPri_Job`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_job.md), a `tPri_JobUserAssigned` row and an audit line in [`tPri_JobChat`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_jobchat.md). Silent `JOB_MODIFY` updates are queued for both steps.
* When at least one task was assigned, one silent `BULK_ACTION_COMPLETED` push with `action` `auto_assign` goes to the other members of the site's groups ([Common side effects](#common-side-effects)). The caller does not get it.
* The result is kept for one hour under `job_status_{taskId}`.

## GET /v1/app/housekeeping/auto-assign-tasks/status/{taskId}

Returns the stored status of an auto-assign run.

* **Auth:** user token. The status is not tied to the caller who started the run, so any signed-in user who has the `taskId` can read it.
* **Used by:** web\_app\_v2 (`HousekeepingHelperService`, through `getAutoAssignStatus`, polled every five seconds until the run ends).

**Request**

| Name     | In   | Type   | Required | Rules                           |
| -------- | ---- | ------ | -------- | ------------------------------- |
| `taskId` | path | string | yes      | The ID the start route returned |

**Response** `200`: `data` is a [bulk status object](#bulk-status-object) without `taskId` and `action`. A completed `result` lists the task UUIDs that were `assigned` and those left `unassigned`. Runs of the caller-less `auto-assign-tasks` can also read `pending`. An unknown or expired `taskId` reads `running`.

```json
{
  "status": "success",
  "message": "Operation was successful",
  "data": { "status": "completed", "result": { "assigned": ["job-400", "job-402"], "unassigned": ["job-404"] } }
}
```

**Errors:** only the [token errors](https://docs.snapfix.com/engineering-reference/api.md#authentication).

**Side effects:** none.

## GET /v1/app/housekeeping/bulk-actions/status/{taskId}

Returns the status of a queued housekeeping bulk action: a bulk reassignment, a bulk reset, a site reset or a person's reset.

* **Auth:** user token. Only the user who started the action gets its status (`ownerUuid`); anyone else gets `403` "Access denied". An unknown or expired `taskId` has no owner and reads `running` for anyone.
* **Used by:** web\_app\_v2 (`HousekeepingBulkActionService`, through `getBulkActionStatus`, polled while a bulk action runs), iOS (`HOUSEKEEPING_BULK_ACTION_STATUS`: `CreateTaskViewModel`, after it assigns new tasks), Android (`HousekeepingTasksRepository.getBulkActionStatus`: the create sheet and the sync of queued reassignments).

**Request**

| Name     | In   | Type   | Required | Rules                           |
| -------- | ---- | ------ | -------- | ------------------------------- |
| `taskId` | path | string | yes      | The ID the start route returned |

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

```json
{
  "status": "success",
  "message": "Operation was successful",
  "data": {
    "taskId": "{uuid}",
    "action": "bulk_reassignment",
    "status": "completed",
    "result": { "successfulJobs": [], "failed": [{ "jobUuid": "job-404", "code": "no_free_slot", "message": "Cannot assign job: no free slot after the current time fits this job duration." }] },
    "error": null
  }
}
```

**Errors:** `403` "Access denied" for another user's action; the [token errors](https://docs.snapfix.com/engineering-reference/api.md#authentication).

**Side effects:** none.

## POST /v1/app/housekeeping/bulk-reassignment

Assigns up to 100 housekeeping tasks to one person, or several, in one request, now or from a set time. The answer lists the tasks that were placed and the ones that failed.

* **Auth:** user token. Each task is checked as [reassignment](#post-v1apphousekeepingreassignmentuuid) checks it: the caller needs "assign user" in the task's group. A task the caller may not change is reported in `failed` as `forbidden`, and the others still run. A task of another site fails as `parent_mismatch`.
* **Used by:** web\_app\_v2 (`HousekeepingAssignmentService.fireBulkReassignment`, when a task of a housekeeping site gets an assignee or a room in the task create dialog or the task detail), iOS (`TaskManager.callBulkReassignment`, from the task sync; it ignores the answer). Android calls only the [queued version](#post-v1apphousekeepingbulk-reassignment-async).

**Request** (JSON)

| Name                                  | In   | Type                       | Required    | Rules                                                                                                                                                                                                       |
| ------------------------------------- | ---- | -------------------------- | ----------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `parentUuid`                          | body | string                     | yes         | An existing site                                                                                                                                                                                            |
| `jobUuids`                            | body | array of string            | yes         | 1 to 100 distinct task UUIDs. More: "You can assign up to 100 tasks at a time. Please select fewer tasks and try again." The linked cleans and inspections are added to the run and count against the limit |
| `assignUserUuid` or `assignUserUuids` | body | string, or array of string | one of them | The assignees. With several, all are assigned and the first gets the placement                                                                                                                              |
| `unassignUserUuids`                   | body | array of string            | no          | People to remove from the tasks                                                                                                                                                                             |
| `startTimeMs`                         | body | integer                    | no          | The first task's start, epoch ms. Without it each task goes into the assignee's first free slot in their working hours, except when the assignee is a self-checker                                          |
| `withInspectionTask`                  | body | `0` or `1`                 | no          | `1`, with an assignee who is not a self-checker: each clean's linked inspection goes to the best available inspector. Otherwise the linked inspection follows its clean for its current assignee            |

Inspections named together with their clean are placed after it.

**Response** `200`: `data` has `successfulJobs`, the [assigned task objects](#assigned-task-object) that were placed, and `failed`. Failures on single tasks are reported in `failed` with `200`, not as HTTP errors.

```json
{
  "status": "success",
  "message": "Operation was successful",
  "data": {
    "successfulJobs": [{ "uuid": "job-400", "title": "Room 101 - Stayover Clean", "assignmentType": 2, "start": 1794387600000, "end": 1794389400000 }],
    "failed": [{ "jobUuid": "job-404", "code": "session_role_mismatch", "message": "messages.housekeeping_session_role_job_mismatch" }]
  }
}
```

Each `failed` item has `jobUuid`, `code` and `message`. The codes:

| Code                                       | When                                                                                                               |
| ------------------------------------------ | ------------------------------------------------------------------------------------------------------------------ |
| `parent_mismatch`                          | The task belongs to another site. The message is the untranslated key `messages.housekeeping_bulk_parent_mismatch` |
| `not_found`                                | No such task                                                                                                       |
| `forbidden`                                | The caller lacks "assign user" in the task's group ("Access denied")                                               |
| `cleaning_not_scheduled`                   | A linked inspection whose clean is not placed yet; the message is the `cannot_moved_time` text                     |
| `cannot_moved_time`                        | "Cannot assign job: user is outside of working hours."                                                             |
| `no_free_slot`                             | "Cannot assign job: no free slot after the current time fits this job duration."                                   |
| `session_role_mismatch`                    | The assignee's role today does not fit the task; the message is the untranslated key                               |
| `validation`, `user_error`, `server_error` | Any other failure, with its message                                                                                |

**Errors:** `422` for the body rules. When the linked tasks push the run over 100, the `422` message is the untranslated key `messages.housekeeping_bulk_too_many_jobs`.

**Side effects:** for each task that was placed, the time range and `assignmentType` change in [`tPri_Job`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_job.md), assignees are added to or removed from [`tPri_JobUserAssigned`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_jobuserassigned.md), audit lines go to [`tPri_JobChat`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_jobchat.md), and the assignees are notified. An assignee who is not in the task's group is added to it ([Common side effects](#common-side-effects)). A self-checker's day is rebuilt. The silent `JOB_MODIFY` updates are held and sent together when the request ends. No completion push: only the queued version sends one.

## POST /v1/app/housekeeping/bulk-reassignment-async

The same request as [bulk-reassignment](#post-v1apphousekeepingbulk-reassignment), run by a queued job.

* **Auth:** user token. The body is validated before the answer. Each task is checked when the job runs, as the caller, whose permissions are loaded again; there is no up-front permission check.
* **Used by:** web\_app\_v2 (`HousekeepingHttpService.bulkReassignmentTasksAsync`: the bulk assign dialog, the create dialog, the timeline board), iOS (`HOUSEKEEPING_BULK_REASSIGNMENT_ASYNC`: `CreateTaskViewModel`, to assign the tasks it created), Android (`HousekeepingTasksRepository`: `postBulkReassignment` from the create sheet, `postBulkReassignmentMultiUser` from the sync of queued reassignments).

**Request:** the body of [bulk-reassignment](#post-v1apphousekeepingbulk-reassignment).

**Response** `200`: poll [bulk-actions/status](#get-v1apphousekeepingbulk-actionsstatustaskid); its `action` is `bulk_reassignment` and its `result` the `data` of the synchronous route.

```json
{
  "status": "success",
  "message": "Operation was successful",
  "data": { "taskId": "{uuid}", "message": "Bulk action started" }
}
```

**Errors:** the `422` body errors of [bulk-reassignment](#post-v1apphousekeepingbulk-reassignment), at once. A failure while the job runs shows as `failed` with an `error` in the status.

**Side effects:** stores the status as `pending` with the caller as owner, and queues `HousekeepingBulkActionJob` on the `long-running` queue. One bulk action runs per site at a time; others wait for it. The job runs the synchronous route's code, so its side effects are those of [bulk-reassignment](#post-v1apphousekeepingbulk-reassignment). When it ends it sends one silent `BULK_ACTION_COMPLETED` push to the other members of the site's groups ([Common side effects](#common-side-effects)). The status is kept for 60 minutes after its last change.

## POST /v1/app/housekeeping/bulk-reset-async

Moves up to 100 housekeeping tasks back to the unassigned pool, by a queued job. Each task loses all its assignees, and a clean's linked inspection is reset in the same transaction.

* **Auth:** user token. The job checks each task, and its linked inspection, with "assign user" in the task's group; a task the caller may not change fails as `forbidden`. There is no up-front permission check.
* **Used by:** web\_app\_v2 (`HousekeepingHttpService.bulkResetTasksAsync`: "Unassign All" in the timeline board's header, for the selected tasks). iOS and Android do not call it.

**Request** (JSON)

| Name         | In   | Type            | Required | Rules                                                                        |
| ------------ | ---- | --------------- | -------- | ---------------------------------------------------------------------------- |
| `parentUuid` | body | string          | yes      | An existing site                                                             |
| `jobUuids`   | body | array of string | yes      | 1 to 100 distinct task UUIDs. The linked inspections count against the limit |

**Response** `200`: `data` is `{ "taskId": "{uuid}", "message": "Bulk action started" }`. The status has `action` `bulk_reset`. Its `result` has `successfulJobs`, the UUIDs of the tasks that were reset including linked inspections, and `failed`, with the codes `parent_mismatch`, `not_found`, `validation`, `forbidden`, `user_error` and `server_error`.

**Errors:** `422` for the body rules, at once.

**Side effects:** for each task, the assignees are notified and their [`tPri_JobUserAssigned`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_jobuserassigned.md) rows soft-deleted, with an "unassigned" audit line each; the time range is cleared, `assignmentType` goes back to 0 and `fBacklog` to 0 in [`tPri_Job`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_job.md). The self-checker cadence is re-applied to the day of each self-checker who lost a clean. Silent `JOB_MODIFY` updates are queued, and the job sends the completion push as [bulk-reassignment-async](#post-v1apphousekeepingbulk-reassignment-async) does.

## GET /v1/app/housekeeping/manual-clean-types

Lists the clean types a site offers when it creates manual housekeeping tasks: name, icon, the session roles that may take each type, the default duration, and, for touch-up cleans, the sub types.

* **Auth:** user token. `parentUuid` must exist. No membership check: any signed-in user can read another site's list.
* **Used by:** web\_app\_v2 (`HousekeepingCleanTypeService`, through `getManualCleanTypes`: the create dialog and the clean type filter), iOS (`HOUSEKEEPING_MANUAL_CLEAN_TYPES`: `CleanTypeConfigCache` and `CreateTaskViewModel`), Android (`HousekeepingTasksRepository.getManualCleanTypes`: the create sheet, the timeline filter and the clean type cache).

**Request**

| Name         | In    | Type   | Required | Rules            |
| ------------ | ----- | ------ | -------- | ---------------- |
| `parentUuid` | query | string | yes      | An existing site |

**Response** `200`: `data.cleantypes` is a list. Each entry has `type`, `name`, `icon`, `iconUri`, `userRoles` (the session roles that may take it), `durationInSeconds` (text; empty when there is no default), `customDurationAllowed` (`1` when the creator may set a duration) and `subcleantype`, a list of sub types with the same fields except the last two.

```json
{
  "status": "success",
  "message": "Operation was successful",
  "data": {
    "cleantypes": [
      { "type": "stayover", "icon": "green", "iconUri": "stayover-clean-broom", "name": "Stayover Clean", "userRoles": ["hk", "hk-and-supervisor", "self-checker"], "durationInSeconds": "", "customDurationAllowed": 0, "subcleantype": [] },
      { "type": "inspections", "icon": "blue", "iconUri": "inspection", "name": "Inspections", "userRoles": ["hk-and-supervisor", "self-checker", "hk-supervisor"], "durationInSeconds": "", "customDurationAllowed": 0, "subcleantype": [] }
    ]
  }
}
```

The default list is Stayover, Departure, Correction, Touch Up (with the sub types Deep Clean, Request Clean, Floor Deep Cleaning, 5 and 10 Min Touch Up Clean, and Deep Clean Pet Room) and Inspections. A site with its own list in the server's configuration gets that list instead; those lists rename some types, add Studio Tidy, Trash and towel and Pre Arrival Maintenance Blitz, and set durations. The inspection type is listed as `inspections`; [manual-hk-task/bulk](#post-v1apphousekeepingmanual-hk-taskbulk) takes it as `inspection`.

**Errors:** `422` when `parentUuid` is missing or is not a site.

**Side effects:** none. The lists come from the server's configuration (`config/housekeeping_manual_clean_types.php`), not from the database.

## POST /v1/app/housekeeping/manual-hk-task/bulk

Creates one manual housekeeping task in each of up to 100 rooms of a group, by a queued job, and answers with a task ID to poll.

* **Auth:** user token. The caller needs "create task" in the group `businessUuid` ([task permissions](https://docs.snapfix.com/engineering-reference/api/tasks.md#task-permissions)), otherwise `403` "Access denied".
* **Used by:** web\_app\_v2 (`HousekeepingHttpService.createManualTasksBulk`: the create housekeeping task dialog), iOS (`HOUSEKEEPING_MANUAL_TASK_BULK`: `CreateTaskViewModel`), Android (`HousekeepingTasksRepository.createManualTasksBulk`: the create sheet).

**Request** (JSON)

| Name            | In     | Type            | Required | Rules                                                                                                                                                                                                                                                                                                                                             |
| --------------- | ------ | --------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `businessUuid`  | body   | string          | yes      | The group the tasks are created in                                                                                                                                                                                                                                                                                                                |
| `roomUuids`     | body   | array of string | yes      | 1 to 100 distinct rooms of the group's site. Any other room: `422` "Rooms not found". `roomUUIDS` is accepted too                                                                                                                                                                                                                                 |
| `cleanType`     | body   | string          | yes      | `stayover`, `departure`, `correction`, `standard` or `inspection`. The catalog keys `stayover_clean`, `departure_clean`, `correction_clean` and `touch_up_clean` are mapped to the first four. `studio_tidy`, `trash_and_towel` and `pre_arrival_blitz`, sent with no sub type, become `standard` with that sub type. `cleantype` is accepted too |
| `subCleanType`  | body   | string          | no       | Only with `standard`: `deep_clean`, `request_clean`, `floor_deep_cleaning`, `touch_up_5_min`, `touch_up_10_min`, `deep_clean_pet_room`, `studio_tidy`, `trash_and_towel` or `pre_arrival_blitz`. Catalog keys such as `touch_up_deep_clean` are mapped. `subcleantype` is accepted too                                                            |
| `cleanDuration` | body   | integer         | no       | The duration in seconds, at least 1. Empty: none. Without it the sub type's default applies: 5 or 10 minutes for the two touch-up sub types, otherwise 30 minutes                                                                                                                                                                                 |
| `title`         | body   | string          | no       | Up to 255 characters. Blank: none. When given, it replaces the generated title, the room's name and the clean type                                                                                                                                                                                                                                |
| `priorityLevel` | body   | integer         | no       | `0`, `1`, `5`, `10`, `20` or `30`                                                                                                                                                                                                                                                                                                                 |
| `fOrigin`       | header | string          | no       | The device, for example `web`, `ios` or `android`, which the tasks record as their origin                                                                                                                                                                                                                                                         |

**Response** `200`: poll [manual-hk-task/bulk/status](#get-v1apphousekeepingmanual-hk-taskbulkstatustaskid).

```json
{
  "status": "success",
  "message": "Manual housekeeping tasks are being created",
  "data": { "taskId": "{uuid}", "status": "pending" }
}
```

**Errors:** `403` "Access denied" without "create task" in the group; `404` for an unknown group; `422` for the body rules, and for a room that is not in the group's site.

**Side effects:** stores the status as `pending` for an hour and queues `CreateManualHkTasksBulkJob` on the `long-running` queue. For each room the job creates a red task in the group, unassigned and in the pending list (`fBacklog` 1), with its room link, a status log row, "created" and room audit lines, and the caller as follower: [`tPri_Job`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_job.md), [`tPri_JobRoom`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_jobroom.md), [`tPri_Job_StatusLog`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_job_statuslog.md) and [`tPri_JobChat`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_jobchat.md). Each clean also gets a linked, locked inspection (type 46, [`tPri_JobLink`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_joblink.md)) when housekeeping is on for the room, unless its sub type is `studio_tidy`, `trash_and_towel` or `pre_arrival_blitz` (`config/housekeeping.php`). With `inspection` only inspections are created. The job adds a viewed row per task in [`tPri_Log_JobViewedUser`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_log_jobvieweduser.md) and a visit row in [`tPri_Log_BusinessViewedUser`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_log_businessvieweduser.md), and adds the number of tasks to the site's Firebase `task_count`. It sends no push.

## GET /v1/app/housekeeping/manual-hk-task/bulk/status/{taskId}

Returns the status of a bulk creation of manual housekeeping tasks and, once it has completed, the UUIDs of the tasks it made.

* **Auth:** user token. The status is not tied to the caller who started the job, so any signed-in user who has the `taskId` can read it.
* **Used by:** web\_app\_v2 (`HousekeepingHttpService.getManualTasksBulkStatus`, polled by the create dialog), iOS (`HOUSEKEEPING_MANUAL_TASK_BULK_STATUS`: `CreateTaskViewModel`), Android (`HousekeepingTasksRepository.awaitManualTasksBulkCompletion`, polled by the create sheet).

**Request**

| Name     | In   | Type   | Required | Rules                            |
| -------- | ---- | ------ | -------- | -------------------------------- |
| `taskId` | path | string | yes      | The ID the create route returned |

**Response** `200`: `data` is a [bulk status object](#bulk-status-object) without `taskId` and `action`. A completed `result` lists `cleaningJobUuids` and `inspectionJobUuids`; for the `inspection` clean type only `inspectionJobUuids`. An unknown or expired `taskId` reads `running`.

```json
{
  "status": "success",
  "message": "Operation was successful",
  "data": { "status": "completed", "result": { "cleaningJobUuids": ["job-400", "job-402"], "inspectionJobUuids": ["job-401", "job-403"] } }
}
```

**Errors:** only the [token errors](https://docs.snapfix.com/engineering-reference/api.md#authentication).

**Side effects:** none.

## POST /v1/app/housekeeping/reassignment/{uuid}

Assigns one housekeeping task to a person at a start time, moves it, or removes a person from it. A new assignee replaces whoever else is assigned to the task.

* **Auth:** user token. The caller needs "assign user" in the task's group: its admin, or a member with "assign users" who is not read-only. Otherwise `403` "Access denied".
* **Used by:** web\_app\_v2 (`HousekeepingHttpService.reassignmentTasks`: dropping a task on the timeline, the inspection placement on the board, and unassigning from the task list with `unassignUserUuid` alone), iOS (`HOUSEKEEPING_REASSIGNMENT_DD` in `TimelineReassignmentService`, drag and drop; `HOUSEKEEPING_REASSIGNMENT` in `HouseKeepingViewModel.reassignTaskForDND`, the snooze in the task chat), Android (`HousekeepingTasksRepository.postReassignment`: the reschedule sheet, the timeline and the unassigned assign sheet; `JobChatFragment.callSnoozeApi`, the snooze in the task chat).

**Request** (form data or JSON)

| Name               | In    | Type       | Required                          | Rules                                                                                                          |
| ------------------ | ----- | ---------- | --------------------------------- | -------------------------------------------------------------------------------------------------------------- |
| `uuid`             | path  | string     | yes                               | The task                                                                                                       |
| `assignUserUuid`   | body  | string     | unless `unassignUserUuid` is sent | The person to assign                                                                                           |
| `unassignUserUuid` | body  | string     | no                                | The person to remove                                                                                           |
| `startTimeMs`      | body  | integer    | with `assignUserUuid`             | The start, epoch ms. A past time moves to now                                                                  |
| `autoMove`         | body  | `0` or `1` | no                                | Accepted, but it changes nothing on this route: the other tasks of the assignee move out of the way either way |
| `parentUuid`       | query | string     | no                                | Not read; the site comes from the task. Android sends it                                                       |

An inspection placed for its clean's assignee starts after the clean ends. A start time is not checked against the assignee's working hours; the task must end before midnight.

**Response** `200`: `data` has `job`, the moved [assigned task object](#assigned-task-object); `affectedJobs`, the other tasks that moved with it in the same shape, such as a linked inspection; and `isBulkUpdate`, `1` when there are affected tasks.

```json
{
  "status": "success",
  "message": "Operation was successful",
  "data": {
    "job": { "uuid": "job-400", "title": "Room 101 - Stayover Clean", "start": 1794391200000, "end": 1794393000000 },
    "isBulkUpdate": 0,
    "affectedJobs": []
  }
}
```

**Errors:** `403` "Access denied"; `404` for an unknown task; `422` for the body rules, such as `startTimeMs` missing with `assignUserUuid`; `400` "Cannot assign job: user is outside of working hours." when the task would run past midnight; `400` with the untranslated key `messages.housekeeping_session_role_job_mismatch` when the assignee's sessions today do not fit the task type.

**Side effects:** changes the task's time range and `assignmentType` (2 on assign, 0 on unassign) in [`tPri_Job`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_job.md), and adds or soft-deletes rows in [`tPri_JobUserAssigned`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_jobuserassigned.md). An assignee who is not in the task's group is added to it as a User with an active onboarding ([`tPri_UserBusiness`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_userbusiness.md)). Audit lines for the assign, the unassign and the time change go to [`tPri_JobChat`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_jobchat.md), and the people assigned and removed are notified. Other tasks of the assignee shift to make room, a clean's linked inspection follows it, and self-checkers' days are rebuilt; the moved tasks are in `affectedJobs`. The silent `JOB_MODIFY` updates go out when the request ends ([Common side effects](#common-side-effects)).

## POST /v1/app/housekeeping/reject-tasks

After an inspection is rejected, creates the follow-up pair: a correction clean and a new inspection for the same room, linked, and assigns both.

* **Auth:** user token. The caller must be an admin of the inspection's group (`operateAsAdmin`) or be assigned to the inspection. Anyone else gets `403` "Access denied".
* **Used by:** web\_app\_v2 (`HousekeepingHttpService.rejectInspectionTask`: the task approval request, on reject), iOS (`HOUSEKEEPING_REJECT_TASKS`: `HouseKeepingViewModel.rejectInspectionTask`, from the approvals in the task chat), Android (`JobChatFragment.callInspectionTaskRejectionApi`, the task chat).

**Request** (JSON)

| Name             | In   | Type   | Required | Rules                                                                                                                 |
| ---------------- | ---- | ------ | -------- | --------------------------------------------------------------------------------------------------------------------- |
| `inspectJobUuid` | body | string | yes      | The rejected inspection. Must exist as a task                                                                         |
| `description`    | body | string | yes      | The rejection note; trimmed, at least one character. It becomes the new tasks' description and a chat message on each |

The correction clean goes to the source clean's first assignee. The new inspection goes to an assignee of the rejected inspection who has an inspector session today (`hk-supervisor` or `hk-and-supervisor`), or else to the first such person on the site's schedule. It starts right after the clean ends.

**Response** `200`: `data` has `cleaningJobUuid` and `inspectJobUuid` (the two new tasks), `parentUuid`, `cleaningAssignUserUuid` and `inspectAssignUserUuid` (who got them), and `successfulJobs`, the two placed tasks as [assigned task objects](#assigned-task-object).

```json
{
  "status": "success",
  "message": "Operation was successful",
  "data": {
    "cleaningJobUuid": "job-410",
    "inspectJobUuid": "job-411",
    "parentUuid": "site-100",
    "cleaningAssignUserUuid": "user-100",
    "inspectAssignUserUuid": "user-101",
    "successfulJobs": [{ "uuid": "job-410", "title": "Room 101 - Correction Clean", "enumType": 45 }]
  }
}
```

**Errors:** `403` "Access denied"; `422` for a missing `description` or an `inspectJobUuid` that is not a task; `400` "Job is not a housekeeping inspection task.", "Inspection task is not linked to a housekeeping cleaning task.", "Linked housekeeping cleaning task must be completed (green) before creating follow-up tasks.", "Source task must have an assigned user before creating follow-up tasks." or "No inspector-capable user is available to assign the correction inspection."; `400` with the [reassignment](#post-v1apphousekeepingreassignmentuuid) message when a placement fails, in which case the new pair is already saved.

**Side effects:** copies the source clean and inspection into two new tasks in [`tPri_Job`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_job.md), with their checklists, tags, assets, rooms, systems and areas; the clean is marked as a correction clean and the inspection is locked. It links the new clean to the new inspection, and the original clean to the new clean, in [`tPri_JobLink`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_joblink.md). Each new task gets a "created" line and the note in [`tPri_JobChat`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_jobchat.md). The caller is added to the group as a User if needed ([`tPri_UserBusiness`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_userbusiness.md)). The clean's assignee gets a task-created notification, and both tasks are then placed as [reassignment](#post-v1apphousekeepingreassignmentuuid) places them. When the site's room status rules say so, starting the clean sets the room's status. The rejected inspection itself is not changed here.

## GET /v1/app/housekeeping/reset-tasks-async/{parentUuid}

Queues a reset of today's red tasks of everyone on the site's schedule for today. Amber and green tasks keep their assignees.

* **Auth:** user token; the caller must be the site's admin (`operate`), otherwise `403` "Access denied".
* **Used by:** web\_app\_v2 (`HousekeepingHttpService.resetTasksAsync`: "Reset All", in the reset assignments dialog). iOS and Android do not call it.

**Request**

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

**Response** `200`: `data` is `{ "taskId": "{uuid}", "message": "Bulk action started" }`. The status has `action` `reset_tasks`, and its `result` is `null`.

**Errors:** `403` "Access denied".

**Side effects:** when the queued job runs, each person on today's schedule is removed from their red tasks with a start time today: the tasks' time range is cleared and `assignmentType` goes back to 0, an "unassigned" audit line is written, the person is notified, and the [`tPri_JobUserAssigned`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_jobuserassigned.md) row is soft-deleted. Silent `JOB_MODIFY` updates are queued and the completion push is sent as for [bulk-reassignment-async](#post-v1apphousekeepingbulk-reassignment-async). A GET request changes data here.

## GET /v1/app/housekeeping/reset-user-tasks-async/{userUuid}

Queues the same reset for one person's red tasks today.

* **Auth:** user token; the caller must be the admin of the site in `parentUuid` (`operate`), otherwise `403` "Access denied".
* **Used by:** web\_app\_v2 (`HousekeepingHttpService.resetUserTasksAsync`: the reset for one staff member, in the reset assignments dialog). iOS and Android do not call it.

**Request**

| Name         | In    | Type   | Required | Rules      |
| ------------ | ----- | ------ | -------- | ---------- |
| `userUuid`   | path  | string | yes      | The person |
| `parentUuid` | query | string | yes      | The site   |

**Response** `200`: as [reset-tasks-async](#get-v1apphousekeepingreset-tasks-asyncparentuuid), with `action` `reset_user_tasks`.

**Errors:** `403` "Access denied"; `422` when `parentUuid` is missing.

**Side effects:** as [reset-tasks-async](#get-v1apphousekeepingreset-tasks-asyncparentuuid), for that person's red tasks only, when they have a session today.

## POST /v1/app/housekeeping/staff-work-settings

Saves each person's default working hours and self-check limit on their site membership row.

* **Auth:** user token; the caller must be the site's admin (`operate`). Every `userUuid` must belong to the site, or the whole request gets `403` "Access denied".
* **Used by:** web\_app\_v2 (`HousekeepingHttpService.updateHousekeepingStaffWorkSettings`: the staff work settings dialog). iOS and Android do not call it.

**Request** (JSON)

| Name                                                                       | In   | Type            | Required | Rules                                                                                                                                                                                           |
| -------------------------------------------------------------------------- | ---- | --------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `parentUuid`                                                               | body | string          | yes      | An existing site                                                                                                                                                                                |
| `usersStaffWorkSettings`                                                   | body | array           | yes      | At least one row                                                                                                                                                                                |
| `usersStaffWorkSettings[].userUuid`                                        | body | string          | yes      | A member of one of the site's groups                                                                                                                                                            |
| `usersStaffWorkSettings[].staffWorkSettings.defaultStartTime`              | body | `H:i` or null   | no       | Empty clears it                                                                                                                                                                                 |
| `usersStaffWorkSettings[].staffWorkSettings.defaultEndTime`                | body | `H:i` or null   | no       | When both are set, after the start: "The default end time must be after the default start time."                                                                                                |
| `usersStaffWorkSettings[].staffWorkSettings.selfCheckerInspectionInterval` | body | integer or null | no       | At least 1. "Maximum Self-Checked Tasks" on the web: a self-checker inspects this many of their own cleans, and the next clean gets an inspection by someone else. Empty: the assignment uses 3 |

A field left out of `staffWorkSettings` keeps its saved value.

**Response** `200`: `data` lists the saved rows.

```json
{
  "status": "success",
  "message": "Operation was successful",
  "data": [
    { "userUuid": "user-100", "staffWorkSettings": { "defaultStartTime": "07:00", "defaultEndTime": "15:30", "selfCheckerInspectionInterval": 4 } }
  ]
}
```

**Errors:** `403` "Access denied" for a caller who is not the site's admin, or a person outside the site; `422` for a time that is not `H:i`, an end time that is not after the start, or an interval below 1.

**Side effects:** updates `default_start_time` and `default_end_time` (stored as `HH:MM:00`) and `fSelfCheckerInspectionInterval` on each person's [`tPri_UserParent`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_userparent.md) row. No task changes; the sessions are saved by [working-hours](#post-v1apphousekeepingworking-hours).

## POST /v1/app/housekeeping/tasks

Lists the site's unassigned housekeeping tasks for the timeline's unassigned list: red tasks that nobody is assigned to and that were not placed by hand, not archived, with at least one room, changed since midnight UTC.

* **Auth:** user token. The list only holds tasks the caller can see, in active groups of the site the caller is a member of ([task permissions](https://docs.snapfix.com/engineering-reference/api/tasks.md#task-permissions)), so a site where the caller is in no group gives an empty list.
* **Used by:** web\_app\_v2 (`HousekeepingHttpService.getHousekeepingTasks`: the timeline board's unassigned list), iOS (`HOUSEKEEPING_UNASSIGNED_TASKS_LIST`: `HousekeepingTimelineViewModel`), Android (`HousekeepingTasksRepository.getUnassignedTasksData`: the unassigned tab).

**Request** (form data; `limit`, `offset` and `sortBy` only in the query string)

| Name         | In            | Type            | Required | Rules                                                                                                                                                                                                                                                                                                                |
| ------------ | ------------- | --------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `parentUuid` | query or body | string          | yes      | The site                                                                                                                                                                                                                                                                                                             |
| filters      | body          |                 | no       | The [task list filters](https://docs.snapfix.com/engineering-reference/api/tasks.md#task-list-filters) for site lists, with the housekeeping filters of [assigned-tasks/list](#post-v1apphousekeepingassigned-taskslist) (`colors`, `priorityLevel`, `roomStatus`, `queued`, the clean flags, `occupied`, `arrival`) |
| `limit`      | query         | integer         | no       | Page size. Without it the whole list comes back; there is no maximum                                                                                                                                                                                                                                                 |
| `offset`     | query         | integer         | no       | Page number, from 1. Used with `limit`                                                                                                                                                                                                                                                                               |
| `sortBy`     | query         | string          | no       | `lastActivity`, `startDate`, `roomNumber` or `jobTitle`                                                                                                                                                                                                                                                              |
| `orderBy`    | query or body | `asc` or `desc` | no       |                                                                                                                                                                                                                                                                                                                      |

**Response** `200`: the shape of [`POST /v1/app/tasks/list-by-parent`](https://docs.snapfix.com/engineering-reference/api/tasks.md#post-v1apptaskslist-by-parent). `data` has `jobs`, [task objects](https://docs.snapfix.com/engineering-reference/api/tasks.md#task-object) with `businessInfo`, `rooms` (with their status and guests), `areas` and `status`; `totalCount`, the unassigned housekeeping tasks that are not archived (archived ones too when `archivedTasks` is sent); and, with `limit`, `pagination`.

```json
{
  "status": "success",
  "message": "Operation was successful",
  "data": {
    "jobs": [{ "uuid": "job-400", "title": "Room 101 - Stayover Clean", "status": { "uuid": "status-200", "name": "red" }, "rooms": [{ "uuid": "room-500", "name": "Room 101" }] }],
    "totalCount": 3
  }
}
```

**Errors:** `422` for the query and body rules.

**Side effects:** none.

## POST /v1/app/housekeeping/working-hours

Replaces the sessions of the staff named in the request: each named person's saved sessions are soft-deleted and the sent rows inserted as new rows.

* **Auth:** user token; the caller must be the site's admin (`operate`), otherwise `403` "Access denied".
* **Used by:** web\_app\_v2 (`HousekeepingHttpService.updateHousekeepingWorkingHours`: save on the timeline board's Schedule tab, the staff work settings dialog, and "Remove Staff"). iOS and Android do not call it.

**Request** (JSON)

| Name                                                                     | In   | Type    | Required         | Rules                                                                                                                     |
| ------------------------------------------------------------------------ | ---- | ------- | ---------------- | ------------------------------------------------------------------------------------------------------------------------- |
| `parentUuid`                                                             | body | string  | yes              | An existing site                                                                                                          |
| `usersWorkingHours`                                                      | body | array   | yes              | The session rows, for one or more people                                                                                  |
| `usersWorkingHours[].userUuid`                                           | body | string  | unless `deleted` | A member of one of the site's groups. Rows for anyone else are left out without an error                                  |
| `usersWorkingHours[].sessionDay`                                         | body | string  | no               | `monday` to `sunday`. Empty means every day                                                                               |
| `usersWorkingHours[].startTime`, `endTime`                               | body | `H:i`   | unless `deleted` | Site-local times. The end must be after the start: "The end time must be after the start time."                           |
| `usersWorkingHours[].sessionType`                                        | body | string  | unless `deleted` | `shift`, `break`, `lunch` or `other`                                                                                      |
| `usersWorkingHours[].sessionRole`                                        | body | string  | unless `deleted` | `hk`, `hk-supervisor`, `hk-and-supervisor`, `self-checker`, `hk-person` or `hk-maintenance`                               |
| `usersWorkingHours[].sessionName`, `sessionDescription`, `userExpertise` | body | string  | no               | Free text                                                                                                                 |
| `usersWorkingHours[].deleted`                                            | body | integer | no               | `1`: the row is not saved. "Remove Staff" sends every session of the person with `1`, so the person ends with no sessions |
| `usersWorkingHours[].uuid`                                               | body | string  | no               | Ignored: every saved row gets a new UUID                                                                                  |

The new sessions of one person may not overlap on the same day.

**Response** `200`: `data` is `null`.

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

**Errors:** `403` "Access denied"; `422` for the rules above, and "New working hour sessions must not overlap for the same day." when two new sessions of one person overlap.

**Side effects:** in one transaction, for each named person who belongs to the site: the person's red tasks with a start time today that fitted the old sessions but not the new ones lose their time range and `assignmentType`, and the person's [`tPri_JobUserAssigned`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_jobuserassigned.md) rows on them are soft-deleted, with no audit line or push \[[ASK-93](https://github.com/snapfix/docs/blob/main/ASK.md#ask-93-should-changing-someones-hours-warn-that-tasks-will-be-unassigned)]. Those tasks are taken from every site the person works on, not only this one. Then the person's saved rows in [`tPri_User_WorkingHours`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_user_workinghours.md) are soft-deleted and the new rows inserted.

## POST /v1/app/housekeeping/working-hours/list

Lists the staff sessions of one site for one weekday, grouped by person, with each person's default hours: who is on duty, in which role and when. The housekeeping page, the timelines and the assign sheets use it, and Simon uses it to answer staffing questions.

* **Auth:** user token. No membership check: any signed-in user can list another site's staff by naming its `parentUuid` \[[ASK-88](https://github.com/snapfix/docs/blob/main/ASK.md#ask-88-who-may-read-a-sites-daily-staff-roster-and-assigned-tasks)].
* **Used by:** web\_app\_v2 (`HousekeepingHttpService.getHousekeepingWorkingHoursData`: the housekeeping page, the timeline board, the staff work settings and the roles helper), iOS (`HOUSEKEEPING_WORKING_HOURS_LIST`: `HousekeepingTimelineViewModel` and `TimelineReassignmentService`), Android (`HousekeepingTasksRepository.getWorkingHoursEnvelope` and its variants: the assigned tab, the assign sheets and the role checks), snapfix\_ai\_agent (`HousekeepingApi.working_hours`, behind Simon's `housekeeping_hours` tool, which checks the caller's access to the site itself).

**Request** (form data or JSON; the server reads the query string and the body alike)

| Name         | In            | Type            | Required | Rules                                                                                                                       |
| ------------ | ------------- | --------------- | -------- | --------------------------------------------------------------------------------------------------------------------------- |
| `parentUuid` | query or body | string          | yes      | The site. Not checked to exist                                                                                              |
| `date`       | body          | `Y-m-d`         | no       | Its weekday picks the sessions, with the sessions that have no day. Default: today's weekday in UTC, the server's time zone |
| `role`       | body          | string          | no       | One session role, as in [working-hours](#post-v1apphousekeepingworking-hours). Ignored when `roles` is sent                 |
| `roles`      | body          | array of string | no       | Up to six session roles                                                                                                     |
| `userUuid`   | body          | string          | no       | Only this person. That person comes back even with no session that day                                                      |

The other fields of the shared filter request ([assigned-tasks/list](#post-v1apphousekeepingassigned-taskslist)) are checked and then ignored here, `userUuids` included.

**Response** `200`: `data` is a list of [staff schedule objects](#staff-schedule-object) with `user`, `staffWorkSettings` and `sessions`, one per person with a session that weekday, ordered by their earliest session.

```json
{
  "status": "success",
  "message": "Operation was successful",
  "data": [
    {
      "user": { "uuid": "user-100", "name": "Jane", "image": null, "username": "jane", "sessionRole": "hk" },
      "staffWorkSettings": { "defaultStartTime": "08:00", "defaultEndTime": "16:00", "selfCheckerInspectionInterval": null },
      "sessions": [
        { "uuid": "session-1", "sessionDate": null, "sessionDay": "monday", "startTime": "08:00", "endTime": "16:00", "sessionType": "shift", "sessionRole": "hk", "sessionName": null, "sessionDescription": null, "userExpertise": null }
      ]
    }
  ]
}
```

**Errors:** `422` for a missing `parentUuid`, a `date` that is not `Y-m-d`, or an unknown role. An unknown site gives an empty list, unless `userUuid` names an existing person.

**Side effects:** none.

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

Returns the groups that clean and inspect a room, from the site's room status task rules, so the create dialogs can put each new task in the right group.

* **Auth:** user token. No check that the caller belongs to the room's site or to either group.
* **Used by:** web\_app\_v2 (`RoomHttpService.getRoomHkBusinesses`: the create housekeeping task dialog, for the first room picked), iOS (`ROOMS_HK_BUSINESSES`: `CreateTaskViewModel.fetchGroupForRoom`), Android (`HousekeepingTasksRepository.getRoomHkBusinesses`: the create sheet).

**Request**

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

**Response** `200`: `data.status.rule` has `cleaningBusiness` and `inspectBusiness`, each a group as `{ "businessUuid", "name", "image" }`, or `null` when the rule names none.

The rule is the one for the room's current main and secondary status pair, then the one for its secondary status alone, then the one for its main status alone. When none of them matches, the building's first rule is used \[[ASK-82](https://github.com/snapfix/docs/blob/main/ASK.md#ask-82-should-a-room-whose-status-has-no-task-rule-get-the-buildings-first-rule)]. With no rule at all, both groups are `null`.

```json
{
  "status": "success",
  "message": "Operation was successful",
  "data": {
    "status": {
      "rule": {
        "cleaningBusiness": { "businessUuid": "group-200", "name": "Housekeeping", "image": null },
        "inspectBusiness": { "businessUuid": "group-201", "name": "Inspections", "image": null }
      }
    }
  }
}
```

**Errors:** `404` "Resource not found" for an unknown room, or a room whose building is deleted.

**Side effects:** none.

## Report scope

What every `/api/reports` route of ops\_dashboard\_be shares (ops\_dashboard\_be @ 0baced9cbf, `analytics/hk/routes.py:37-123`).

* **Methods:** every route accepts `GET` and `POST`. ops\_dashboard\_fe sends `POST`, because the CDN in front of the API drops the `Authorization` header from `GET` requests. The parameters are read from the query string only, with either method.
* **Auth:** `Authorization: Bearer <token>`, an HS256 JWT checked with the server's `JWT_SECRET`. The signature is always checked; an expired token is accepted only when the setting `SKIP_JWT_EXPIRY` is on, which defaults to off (`analytics/settings.py`) \[[ASK-12](https://github.com/snapfix/docs/blob/main/ASK.md#ask-12-which-settings-do-the-production-api-servers-use)]. The user may open a site when their [`tPri_UserParent`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_userparent.md) row there has `user_type` admin and the site has `fTaskDashboardEnabled` on.
* **Answers:** the report JSON as is, with no `status` key. Every report counts "completed" as green, and selects tasks by their creation time (`fCreatedTs`) unless its section says otherwise.

| Name           | In    | Type                     | Required         | Rules                                                                                                                                       |
| -------------- | ----- | ------------------------ | ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
| `parent_uuid`  | query | string                   | one of the three | One site                                                                                                                                    |
| `parent_uuids` | query | string                   | one of the three | Several sites, separated by commas. Wins over `parent_uuid`                                                                                 |
| `all_parents`  | query | `true`, `1` or `yes`     | one of the three | Every site the user may open                                                                                                                |
| `period`       | query | string                   | no               | `today` (default), `this_week` or `week` (from Monday), `this_month` or `month`, `last_7_days` (today and the six days before), or `custom` |
| `start`, `end` | query | epoch ms or `YYYY-MM-DD` | with `custom`    | Both are needed. An `end` date includes the whole day                                                                                       |

Each period is a half-open range, `[start, end)`, in each site's own time zone. The dashboard also sends `tz`, which the routes don't read.

**Errors**, as `{"error": "..."}`:

* `400` "parent\_uuid or parent\_uuids is required" when no site parameter is sent.
* `401` "Missing or invalid Authorization header.", "Missing JWT.", "Invalid token." or "JWT missing user\_uuid/identity." (`analytics/auth.py`).
* `403` "Forbidden." when a named site is not one the user may open; `403` "No accessible properties for this user" when the user may open none (`analytics/db.py`).
* An unknown `period`, or a `custom` period without both dates: `400` with the error text from cleans by room type, the benchmarks and training needs; `500` "Internal server error: unknown period: ..." from the At a glance and cleaning history routes.
* `500` "Internal server error: " for any other exception; the exception's text goes to the client.

## POST /api/reports/accessible-properties

Lists the sites the signed-in user may open in the housekeeping reports.

* **Auth:** user token ([Report scope](#report-scope)). The list is the user's own sites where they are an admin and the task dashboard is on.
* **Used by:** ops\_dashboard\_fe (`fetchAccessibleProperties`: the property picker of the housekeeping dashboard).

**Request:** no parameters.

**Response** `200`: `properties`, ordered by name. `room_count` counts the site's rooms that are not deleted.

```json
{ "properties": [{ "uuid": "site-100", "name": "Example Hotel", "room_count": 84 }] }
```

**Errors:** the `401` and `500` errors of [Report scope](#report-scope).

**Side effects:** none.

## POST /api/reports/at-a-glance/summary

All eight tiles of the "At a glance" page in one response, computed in parallel. The eight single-tile routes return the same objects; nothing calls them.

* **Auth:** user token; the sites as in [Report scope](#report-scope).
* **Used by:** ops\_dashboard\_fe (`fetchAllAtAGlance`: the At a glance tiles).

**Request:** the [Report scope](#report-scope) parameters.

**Response** `200`: one key per tile. Each tile has `metric`, its own value fields, `period` (`type`, `start_ms`, `end_ms`, and `days` or `filter`) and `businesses`.

| Key                     | Fields                                                                                         | Meaning                                                                                                                                                                                |
| ----------------------- | ---------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `totalCleans`           | `value`, `secondary`, `properties`                                                             | Completed cleans; `secondary` compares the period's daily rate with the 30-day baseline before it                                                                                      |
| `avgDuration`           | `value_ms`, `value_minutes`, `sample_size`, `jobs_in_period`, `excluded_no_start`, `secondary` | Amber-to-green time of completed cleans, from the status log, against the scheduled time                                                                                               |
| `passRate`              | `value`, `secondary`                                                                           | Passed inspections over passed plus failed, in percent; `secondary` has the pass, fail and skip counts                                                                                 |
| `avgInspectionDuration` | `value_ms`, `value_minutes`, `inspection_count`                                                | Amber-to-green time of completed inspections                                                                                                                                           |
| `guestTurnaround`       | `value_ms`, `value_minutes`, `value_formatted`, `sample_size`, `excluded`                      | Checkout to the room's first passed inspection                                                                                                                                         |
| `inspectorTurnaround`   | `value_ms`, `value_minutes`, `value_formatted`, `sample_size`, `excluded`                      | Clean done to its first passed inspection                                                                                                                                              |
| `mobileCompletion`      | `value`, `detail`                                                                              | Completed cleans finished on a phone, in percent. The device is guessed from the status log row's UUID: upper case counts as iOS, a UUID starting with "a" as web, the rest as Android |
| `variance`              | `clean_types`                                                                                  | Actual over scheduled time per clean kind (departure, stayover, and the `standard` sub types), with `variance_pct` and a `color`: below 0 green, up to 10% amber, above red            |

```json
{
  "totalCleans": {
    "metric": "total_cleans",
    "value": 42,
    "period": { "type": "today", "start_ms": 1794355200000, "end_ms": 1794441600000, "days": 1 },
    "secondary": { "period_daily_average": 42.0, "baseline_daily_average": 36.0, "baseline_days": 30, "delta_vs_daily_average": 6.0 },
    "businesses": ["group-200"],
    "properties": [{ "uuid": "site-100", "name": "Example Hotel" }]
  }
}
```

**Errors:** [Report scope](#report-scope); an unknown `period` gives `500`.

**Side effects:** none.

## POST /api/reports/b2b-guests

Lists the guests who leave one stay and arrive for another at the same site on the same day (the "Back to Back Reservations" report).

* **Auth:** user token; the sites as in [Report scope](#report-scope).
* **Used by:** ops\_dashboard\_fe (`fetchB2bGuests`: the B2B guests tab).

**Request**

| Name                                         | In    | Type         | Required | Rules                                                     |
| -------------------------------------------- | ----- | ------------ | -------- | --------------------------------------------------------- |
| `parent_uuid`, `parent_uuids`, `all_parents` | query |              | yes      | As in [Report scope](#report-scope). `period` is not read |
| `date`                                       | query | `YYYY-MM-DD` | no       | The day. Default: each site's own today                   |

A departure and an arrival pair up when their guests have the same PMS owner ID or, when neither has one, the same name. Cancelled and no-show stays, and stays that start and end on the same day, are left out.

**Response** `200`: `pairs`; `days`, the day read for each site; and `properties`. Each pair has `property`, `property_uuid`, `guest_name` and `owner_id` (either may be `null`), `matched_by` (`owner_id` or `name`), `current_room` (the departure's room), `reserved_room` (the arrival's room), and `arrival_date` and `departure_date` over both stays. Guest names and PMS IDs are personal data.

```json
{
  "pairs": [
    { "property": "Example Hotel", "property_uuid": "site-100", "guest_name": "Jane Smith", "owner_id": null, "matched_by": "name", "current_room": "Room 101", "reserved_room": "Room 102", "arrival_date": "2026-11-10", "departure_date": "2026-11-16" }
  ],
  "days": { "site-100": "2026-11-13" },
  "properties": [{ "uuid": "site-100", "name": "Example Hotel" }]
}
```

**Errors:** `400` "date must be YYYY-MM-DD"; [Report scope](#report-scope).

**Side effects:** none.

## POST /api/reports/cleaning-history/housekeeper-summary

One row per housekeeper for a period: completed cleans, scheduled and actual time and the average time per clean, with the team average.

* **Auth:** user token; the sites as in [Report scope](#report-scope).
* **Used by:** ops\_dashboard\_fe (`fetchHousekeeperSummary`: the cleaning history tab, with the same filters as the task list).

**Request:** the [Report scope](#report-scope) parameters, and `clean_type`, `room` and `housekeeper_uuids` as in [cleaning-history/tasks](#post-apireportscleaning-historytasks).

**Response** `200`: `housekeepers`, each with `user_uuid`, `housekeeper`, `total_cleans`, `measured_cleans`, `cleans_by_type`, `total_scheduled_ms` and `_minutes`, `total_actual_ms` and `_minutes`, `avg_time_per_clean_ms`, `_minutes` and `_formatted`, and `exceeds_team_avg_by_10pct`; then `team_average_ms`, `team_average_minutes`, `team_average_formatted`, `period` and `businesses`. Actual times come from the status log; a clean with no start in the log is counted but not measured. The team average is `null` when no clean was measured. Formatted times read like "33m" or "1h 5m".

```json
{
  "housekeepers": [
    { "user_uuid": "user-100", "housekeeper": "Jane Smith", "total_cleans": 12, "measured_cleans": 10, "cleans_by_type": { "stayover": 9, "departure": 3 }, "total_scheduled_ms": 21600000, "total_scheduled_minutes": 360, "total_actual_ms": 19800000, "total_actual_minutes": 330, "avg_time_per_clean_ms": 1980000, "avg_time_per_clean_minutes": 33, "avg_time_per_clean_formatted": "33m", "exceeds_team_avg_by_10pct": false }
  ],
  "team_average_ms": 1980000,
  "team_average_minutes": 33,
  "team_average_formatted": "33m",
  "period": { "type": "today", "start_ms": 1794355200000, "end_ms": 1794441600000, "filter": "fCreatedTs" },
  "businesses": ["group-200"]
}
```

**Errors:** [Report scope](#report-scope); an unknown `period` gives `500`.

**Side effects:** none.

## POST /api/reports/cleaning-history/tasks

The completed cleans of a period, one page at a time, each with its room, housekeepers, scheduled and actual times, inspection result and, for departures, the turnaround from checkout to inspection.

* **Auth:** user token; the sites as in [Report scope](#report-scope).
* **Used by:** ops\_dashboard\_fe (`fetchCleaningHistoryTasks`: the cleaning history tab, which loads the whole period in one page and filters in the browser).

**Request**

| Name                | In    | Type    | Required | Rules                                    |
| ------------------- | ----- | ------- | -------- | ---------------------------------------- |
| scope and period    | query |         |          | As in [Report scope](#report-scope)      |
| `page`              | query | integer | no       | Default 1                                |
| `page_size`         | query | integer | no       | Default 50, at most 1000                 |
| `clean_type`        | query | string  | no       | Only this clean type                     |
| `room`              | query | string  | no       | Only rooms whose name contains this text |
| `housekeeper_uuids` | query | string  | no       | Comma-separated housekeepers             |

**Response** `200`: `tasks`, each with `job_uuid`, `property`, `property_uuid`, `room`, `room_type`, `type`, `housekeeper`, `housekeeper_uuids`, `created_date`, `sched_start`, `sched_end`, `actual_start`, `actual_finish`, `actual_start_datetime`, `actual_finish_datetime`, `time_ms`, `time_minutes`, `time_formatted`, `inspection` and the `turnaround_ms`, `_minutes` and `_formatted` fields; then `task_count`, `pagination` (`page`, `page_size`, `total`, `pages`), `period`, `businesses` and `properties`.

```json
{
  "tasks": [
    { "job_uuid": "job-400", "property": "Example Hotel", "property_uuid": "site-100", "room": "Room 101", "room_type": "Double", "type": "stayover", "housekeeper": "Jane Smith", "housekeeper_uuids": ["user-100"], "time_ms": 1800000, "time_minutes": 30, "time_formatted": "30m" }
  ],
  "task_count": 1,
  "pagination": { "page": 1, "page_size": 50, "total": 1, "pages": 1 },
  "period": { "type": "today", "start_ms": 1794355200000, "end_ms": 1794441600000, "filter": "fCreatedTs" },
  "businesses": ["group-200"],
  "properties": [{ "uuid": "site-100", "name": "Example Hotel" }]
}
```

**Errors:** `400` "page and page\_size must be integers"; [Report scope](#report-scope); an unknown `period` gives `500`.

**Side effects:** none.

## POST /api/reports/cleans-by-room-type

Completed cleans of a period per room type and site, split into departure, stayover and others (`standard`), with totals. Correction cleans are left out, and each clean counts under its first room's type.

* **Auth:** user token; the sites as in [Report scope](#report-scope).
* **Used by:** ops\_dashboard\_fe (`fetchCleansByRoomType`: the cleans by room type chart).

**Request:** the [Report scope](#report-scope) parameters.

**Response** `200`: `room_types`, each with `property`, `property_uuid`, `room_type`, `departure`, `stayover`, `others` and `total`; `totals`; `period` (`type`, `start_ms`, `end_ms`); and `properties`.

```json
{
  "room_types": [{ "property": "Example Hotel", "property_uuid": "site-100", "room_type": "Double", "departure": 3, "stayover": 8, "others": 1, "total": 12 }],
  "totals": { "departure": 3, "stayover": 8, "others": 1, "total": 12 },
  "period": { "type": "today", "start_ms": 1794355200000, "end_ms": 1794441600000 },
  "properties": [{ "uuid": "site-100", "name": "Example Hotel" }]
}
```

**Errors:** `400` with the period error, such as "unknown period: ..."; [Report scope](#report-scope).

**Side effects:** none.

## POST /api/reports/housekeeper-benchmark

Compares the housekeepers of a period: cleans, first-pass and quality results, travel time, time use, and the times of their first and last clean.

* **Auth:** user token; the sites as in [Report scope](#report-scope).
* **Used by:** ops\_dashboard\_fe (`fetchHousekeeperBenchmark`: the housekeeper benchmark tab).

**Request:** the [Report scope](#report-scope) parameters.

**Response** `200`: `summary` (`total_housekeepers`, `team_avg_first_pass_pct`); `housekeepers`, each with `user_uuid`, `housekeeper`, `total_cleans`, `skipped_no_amber`, `cleans_by_type`, `productivity`, `quality` and `quality_detail` (`pass`, `fail`), `first_pass_pct` and `first_pass_detail`, `avg_travel_ms`, `_minutes` and `_formatted`, `time_management` (`cleaning_ms`, `travel_ms`, `break_ms`, each with a formatted twin), `first_clean`, `first_clean_ms`, `last_clean`, `last_clean_ms` and `properties`; then `period`, `businesses` and `properties`.

```json
{
  "summary": { "total_housekeepers": 1, "team_avg_first_pass_pct": 90 },
  "housekeepers": [
    { "user_uuid": "user-100", "housekeeper": "Jane Smith", "total_cleans": 12, "skipped_no_amber": 1, "cleans_by_type": { "stayover": 9, "departure": 3 }, "quality_detail": { "pass": 9, "fail": 1 }, "first_pass_pct": 90, "first_clean": "08:05", "last_clean": "15:20" }
  ],
  "period": { "type": "today", "start_ms": 1794355200000, "end_ms": 1794441600000 },
  "businesses": ["group-200"],
  "properties": [{ "uuid": "site-100", "name": "Example Hotel" }]
}
```

**Errors:** `400` for a bad period; [Report scope](#report-scope).

**Side effects:** none.

## POST /api/reports/inspector-benchmark

Compares the inspectors of a period, split into inspectors and self-checkers: inspections, first-pass rate, inspections per hour, time per inspection and turnaround after the clean.

* **Auth:** user token; the sites as in [Report scope](#report-scope).
* **Used by:** ops\_dashboard\_fe (`fetchInspectorBenchmark`: the inspector benchmark tab).

**Request:** the [Report scope](#report-scope) parameters.

**Response** `200`: `summary` (`total_inspectors`, `team_avg_first_pass_pct`, and `groups` with the same figures for `inspectors` and `self_checkers`); `inspectors`, each with `user_uuid`, `inspector`, `total_inspections`, `skipped_no_amber`, `first_pass_pct`, `per_hour`, `avg_time_ms`, `_minutes` and `_formatted`, `pct_inspecting`, `turnaround_ms`, `_minutes` and `_formatted`, `skipped`, the team comparison `team_first_pass_excl_pct`, `first_pass_deviation` and `first_pass_deviation_color`, `vs_group` (the same three fields against the inspector's own group) and `properties`; then `period`, `businesses` and `properties`. The comparisons use the team's, or the group's, first-pass rate without the inspector; the deviation is `red` at 10 points or more and `amber` at 5.

**Errors:** `400` for a bad period; [Report scope](#report-scope).

**Side effects:** none.

## POST /api/reports/room-status-log

Lists the room status changes of the last seven days, newest first, with who made each change (the "Activity Log" report). PMS syncs log a room's unchanged status again; only rows that change the main or secondary status are reported.

* **Auth:** user token; the sites as in [Report scope](#report-scope).
* **Used by:** ops\_dashboard\_fe (`fetchRoomStatusLog`: the room status log tab).

**Request:** `parent_uuid`, `parent_uuids` or `all_parents` as in [Report scope](#report-scope). `period`, `start` and `end` are not read: the range is always today and the six days before, in each site's time zone.

**Response** `200`: `changes`, each with `room`, `property`, `property_uuid`, `previous_status`, `new_status`, `new_statuses`, `changed_by`, `changed_by_type` (`user`, `integration` or `unknown`), `changed_at_ms`, `changed_at` and `day`; `days`, every day of the seven-day range, newest first; `period` (`type` `last_7_days`, `start_ms`, `end_ms`); and `properties`.

```json
{
  "changes": [
    { "room": "Room 101", "property": "Example Hotel", "property_uuid": "site-100", "previous_status": "Dirty", "new_status": "Clean", "new_statuses": ["Clean"], "changed_by": "Jane Smith", "changed_by_type": "user", "changed_at_ms": 1794409200000, "changed_at": "2026-11-13 15:20", "day": "2026-11-13" }
  ],
  "days": ["2026-11-13", "2026-11-12", "2026-11-11", "2026-11-10", "2026-11-09", "2026-11-08", "2026-11-07"],
  "period": { "type": "last_7_days", "start_ms": 1793836800000, "end_ms": 1794441600000 },
  "properties": [{ "uuid": "site-100", "name": "Example Hotel" }]
}
```

**Errors:** [Report scope](#report-scope).

**Side effects:** none.

## POST /api/reports/training-needs

Finds the checklist items that inspections mark down most and least often, with coaching notes, once the period has at least 100 completed cleans.

* **Auth:** user token; the sites as in [Report scope](#report-scope).
* **Used by:** ops\_dashboard\_fe (`fetchTrainingNeeds`: the training needs tab; it sends `dummy=1` when the page's own address has `?dummy=1`).

**Request**

| Name               | In    | Type                 | Required | Rules                                                                                                                                                                                                                                     |
| ------------------ | ----- | -------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| scope and period   | query |                      |          | As in [Report scope](#report-scope)                                                                                                                                                                                                       |
| `housekeeper_uuid` | query | string               | no       | Only the inspections of this housekeeper's cleans                                                                                                                                                                                         |
| `dummy`            | query | `1`, `true` or `yes` | no       | Replaces the checklist results of the real inspections with synthetic ones, and sets `dummy` to `true` \[[ASK-94](https://github.com/snapfix/docs/blob/main/ASK.md#ask-94-should-dummy1-show-invented-training-needs-data-in-production)] |

**Response** `200`: `threshold` (`required` 100, `current`, `met`); `summary` (`total_cleans`, `total_inspections`, `total_markdowns`); `marked_down_items`; `strongest_items`; `insights` (`coaching_focus`, `celebrate`); `shift_position`, the markdown rates of the first three, middle and last three inspections of a shift (`first_3`, `middle`, `last_3`) with an `insight`; `housekeepers`; `properties`; `period`; and `dummy`.

Below the threshold, `met` is `false`, `summary` and `shift_position` are `null`, the lists are empty and `dummy` is `false`, also when `dummy` was sent. When the threshold is met but the period has no completed inspections, `met` is `true` and the lists are empty.

```json
{
  "threshold": { "required": 100, "current": 42, "met": false },
  "summary": null,
  "marked_down_items": [],
  "strongest_items": [],
  "insights": {},
  "shift_position": null,
  "housekeepers": [],
  "properties": [{ "uuid": "site-100", "name": "Example Hotel" }],
  "period": { "type": "today", "start_ms": 1794355200000, "end_ms": 1794441600000 },
  "dummy": false
}
```

**Errors:** `400` for a bad period; [Report scope](#report-scope).

**Side effects:** none.

## Staff schedule object

One person with their day, as [working-hours/list](#post-v1apphousekeepingworking-hourslist) and [assigned-tasks/list](#post-v1apphousekeepingassigned-taskslist) return it.

| Field               | Type           | Meaning                                                                                                                                                                                                                                                                                            |
| ------------------- | -------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `user`              | object         | `uuid`, `name` (the user's `fName`), `image`, `username`, `sessionRole` (the role of the person's first session that day, or `null`). From `assigned-tasks/list` also `totalTime`: the milliseconds that today's started tasks that are not red have run, from `fAmberTs` to `fGreenTs`, or to now |
| `staffWorkSettings` | object or null | `defaultStartTime` and `defaultEndTime` (`HH:MM` or `null`) and `selfCheckerInspectionInterval` (integer or `null`). Always an object from `working-hours/list`, with `null` values when the person has no site row; always `null` from `assigned-tasks/list`                                      |
| `sessions`          | list           | Only from `working-hours/list`. Each session has `uuid`, `sessionDate`, `sessionDay` (a weekday, or `null` for every day), `startTime` and `endTime` (`HH:MM`, site-local), `sessionType`, `sessionRole`, `sessionName`, `sessionDescription` and `userExpertise`                                  |
| `assignedJobs`      | list           | Only from `assigned-tasks/list`: [assigned task objects](#assigned-task-object)                                                                                                                                                                                                                    |

## Assigned task object

A housekeeping task as the timeline, the reassignment, bulk and reject answers return it (`AssignedJobsTimeLineResource`).

| Field                             | Type           | Meaning                                                                                                                                    |
| --------------------------------- | -------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
| `uuid`, `title`, `shortTitle`     | string         | The task                                                                                                                                   |
| `enumType`                        | integer        | `45` for a clean, `46` for an inspection                                                                                                   |
| `inspectJobUuid`                  | string or null | On a clean: its linked inspection                                                                                                          |
| `cleaningJobUuid`                 | string or null | On an inspection: its linked clean                                                                                                         |
| `assignmentType`                  | integer        | `0` default, `1` placed by auto-assign, `2` placed by hand                                                                                 |
| `cleaningType`, `cleaningSubType` | string or null | The clean type and sub type                                                                                                                |
| `status`                          | object         | `uuid` of the status, and `name`: the colour, `red`, `amber` or `green`                                                                    |
| `businessInfo`                    | object         | The group: `businessUuid`, `businessName`, `businessImage`                                                                                 |
| `priorityLevel`                   | integer        | The priority level                                                                                                                         |
| `start`, `end`                    | integer        | Epoch ms: the start, and the start plus the duration. The column is named `timerange_startAfterMidnightMs`, but it holds a timestamp       |
| `rooms`                           | list           | Each room with its status and, for an occupied room, `guestsInfo`: the guests' names, email, phone, address, date of birth and nationality |
| `reservation`                     | object or null | The room's stays: `primary`, `departing`, `arriving` and `inHouse`, each with its guests                                                   |

## Bulk status object

What the three status routes answer for a background run: [bulk-actions](#get-v1apphousekeepingbulk-actionsstatustaskid), [manual-hk-task](#get-v1apphousekeepingmanual-hk-taskbulkstatustaskid) and [auto-assign](#get-v1apphousekeepingauto-assign-tasksstatustaskid).

| Field              | Type           | Meaning                                                                                                                                                                                                          |
| ------------------ | -------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `taskId`, `action` | string         | Only from the bulk-actions route. `action` is `bulk_reassignment`, `bulk_reset`, `reset_tasks` or `reset_user_tasks`, or `null` for an unknown ID                                                                |
| `status`           | string         | `pending` (accepted, not started), `running`, `completed` or `failed`. An unknown or expired ID reads `running`                                                                                                  |
| `result`           | object or null | Set when `completed`: the bulk route's `data` (`successfulJobs` and `failed`), `null` for the two resets, the created task UUIDs for manual tasks, or the `assigned` and `unassigned` task UUIDs for auto-assign |
| `error`            | string or null | Set when `failed`: the exception's message, which can include internal text                                                                                                                                      |

The bulk-action status is kept for 60 minutes after its last change, the other two for one hour.

## Common side effects

What the sections above mean by these words. The task-wide definitions are in the [Tasks API](https://docs.snapfix.com/engineering-reference/api/tasks.md#common-side-effects).

* **Audit line:** a row in [`tPri_JobChat`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_jobchat.md) for an assign, an unassign or a time change, written as the caller. Queued jobs write them as the caller too.
* **Group membership:** assigning someone who is not in the task's group adds them to [`tPri_UserBusiness`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_userbusiness.md) as a User with an active onboarding.
* **Assignee notification:** the person assigned to or removed from a task gets the task's assignee notification.
* **`JOB_MODIFY` updates:** silent pushes (103) that tell the apps to refresh the moved tasks, queued through `JobModifyNotificationService`; the bulk routes hold them and send them together when the run ends.
* **Completion push:** one silent `BULK_ACTION_COMPLETED` push (117), with the site and the action, to the members of the site's groups except the caller (`HousekeepingBulkCompletedNotificationService`). The queued bulk actions send it when they end, and auto-assign when it assigned at least one task.


---

# 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/housekeeping.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.
