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

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

Dashboards, analytics, task and checklist reports and exports, and wallboards.

Most web reports are queued: the request writes a row of [`report_userreports`](https://docs.snapfix.com/engineering-reference/db/tables/report_userreports.md) and answers with it at once, and the same PHP process builds the file after the answer ([Report object](#report-object), [Common side effects](#common-side-effects)). The apps' checklist and completed-tasks exports, the task report for the apps and the time and cost statement answer with the file's link after building it. The area, group and room PDFs answer with their link at once and are built after the answer. Report files go to the reports bucket as public files, except the compliance report, which goes to a private bucket \[[ASK-115](https://github.com/snapfix/docs/blob/main/ASK.md#ask-115-can-compliance-documents-report-files-and-the-comply-report-be-opened-from-their-link-without-signing-in)].

* **Services:** `api_php_live_v2` at `https://z4.snapfix.com` (`/v1/app`); `php-apis` at `https://z1.snapfix.com`: actions at `/api/snapfix/index.php?action=<name>`, pages at their own path; `php-apis web` at `https://z1.snapfix.com/api/snapfix/web/index.php`; `apipy` at `https://z2.snapfix.com`; `ops_dashboard_be` at `https://dashboardapp.snapfix.com` (`/api/analytics`)
* **Auth:** api\_php\_live\_v2: user token (authpy JWT in `Authorization: Bearer`); the compliance report also checks that the caller may operate the site. php-apis: user token (Bearer JWT, if `JWT_AUTH_ENABLED` is on \[[ASK-12](https://github.com/snapfix/docs/blob/main/ASK.md#ask-12-which-settings-do-the-production-api-servers-use)]); actions use the `user_uuid` in the request, not the token's user; the report builders read any group, site or task named in the request, with no membership check; the two report pages that php-apis calls need only the task UUID in the URL; the pages without a query parameter need no login; the wallboard pages need only the board UUID in the URL; `daily_group_report` takes HTTP Basic with `AUTH_USERNAME` instead \[[ASK-12](https://github.com/snapfix/docs/blob/main/ASK.md#ask-12-which-settings-do-the-production-api-servers-use)]. apipy: user token (authpy JWT in `Authorization: Bearer`) on the dashboards, which take `user_uuid` from the form and don't compare it with the token; app basic auth (the shared login built into the apps) on `/daily-group-report`. ops\_dashboard\_be: user token (HS256 with `JWT_SECRET`); it answers only for sites where the user is a site admin and the task dashboard is on ([Analytics request](#analytics-request)).
* **Used by:** web\_app\_v2 (dashboard; task, asset and site reports; the task report and statement of fees; the compliance report; the housekeeping schedule print), ops\_dashboard\_fe (analytics, inside the Ops Dashboard frame), iOS and Android (group, room and area task PDFs, the checklist and completed-tasks exports, the task report), apipy (`daily_group_report`), php-apis (the task report and statement pages); 30 of the 73 endpoints have no known caller
* **Answers:** each service uses its envelope from [API conventions](https://docs.snapfix.com/engineering-reference/api.md#responses). On php-apis the web dispatcher adds `serverTs` and `request_serial` to every answer, the app dispatcher adds `serverTs` except to the area, group and room PDFs, and the two pages add neither.

| Method | Path                                                                                          | Service            | Purpose                                                                                                                                                      |
| ------ | --------------------------------------------------------------------------------------------- | ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| GET    | [`/v1/app/report/comply`](#get-v1appreportcomply)                                             | api\_php\_live\_v2 | Build the compliance dashboard PDF for a site and return its link                                                                                            |
| ANY    | `/api/snapfix/business_job_report.php?report_data=`                                           | php-apis           | Group task report page (`class/business_job_report.php`); renders a fixed sample file (no caller)                                                            |
| ANY    | `/api/snapfix/business_job_report_index.php?id=`                                              | php-apis           | Redirect to a generated report in the reports bucket (no caller)                                                                                             |
| ANY    | `/api/snapfix/daily_group_email_report_v1.php`                                                | php-apis           | Daily group email report page (no caller)                                                                                                                    |
| ANY    | `/api/snapfix/job_inspection_report.php?uuid_tJob=`                                           | php-apis           | Task inspection report page (no caller)                                                                                                                      |
| ANY    | `/api/snapfix/job_report.php?uuid_tJob=`                                                      | php-apis           | Task report page (no caller)                                                                                                                                 |
| ANY    | `/api/snapfix/job_report_dev.php?uuid_tJob=`                                                  | php-apis           | Task report page, development copy (no caller)                                                                                                               |
| ANY    | `/api/snapfix/job_report_v2.php?uuid_tJob=`                                                   | php-apis           | Task report page (v2) (no caller)                                                                                                                            |
| ANY    | `/api/snapfix/job_report_v3.php?uuid_tJob=`                                                   | php-apis           | Task report page (v3) (no caller)                                                                                                                            |
| ANY    | `/api/snapfix/job_report_v4-dev.php?uuid_tJob=`                                               | php-apis           | Task report page (v4), development copy (no caller)                                                                                                          |
| POST   | [`/api/snapfix/job_report_v4.php?uuid_tJob=`](#post-apisnapfixjob_report_v4phpuuid_tjob)      | php-apis           | Task report page (v4): build a task's PDF and return its link; php-apis calls it                                                                             |
| POST   | [`/api/snapfix/job_tc_report.php?uuid_tJob=`](#post-apisnapfixjob_tc_reportphpuuid_tjob)      | php-apis           | Task time and cost report page: build the statement PDF and return its link; php-apis calls it                                                               |
| ANY    | `/api/snapfix/snapboard.php?uuid=`                                                            | php-apis           | Snapboard page for a board \[[ASK-12](https://github.com/snapfix/docs/blob/main/ASK.md#ask-12-which-settings-do-the-production-api-servers-use)] (no caller) |
| ANY    | `/api/snapfix/wallboard.php?uuid=`                                                            | php-apis           | Wallboard page for a board \[[ASK-12](https://github.com/snapfix/docs/blob/main/ASK.md#ask-12-which-settings-do-the-production-api-servers-use)] (no caller) |
| POST   | [`?action=area_job_report`](#post-actionarea_job_report)                                      | php-apis           | Area task report (PDF): link now, file built after the answer                                                                                                |
| POST   | [`?action=business_job_report`](#post-actionbusiness_job_report)                              | php-apis           | Group task report (PDF): link now, file built after the answer                                                                                               |
| POST   | [`?action=checklist_report`](#post-actionchecklist_report)                                    | php-apis           | Checklist report (Excel) for whole groups, built in the request                                                                                              |
| POST   | [`?action=export_jobs_report`](#post-actionexport_jobs_report)                                | php-apis           | "Tasks Completed Report" (Excel) for a group and a date range, built in the request                                                                          |
| POST   | [`?action=get_job_report`](#post-actionget_job_report)                                        | php-apis           | Task report (PDF) for the apps, built in the request                                                                                                         |
| ANY    | `?action=me_group_schedules`                                                                  | php-apis           | Once-off schedule list (Excel) for a fixed set of groups written into the code (`getOnceOffScheduleReportForMeGroup`) (no caller)                            |
| ANY    | `?action=parent_job_asset_report`                                                             | php-apis           | Generate a site's asset task report (no caller)                                                                                                              |
| POST   | [`?action=room_job_report`](#post-actionroom_job_report)                                      | php-apis           | Room task report (PDF): link now, file built after the answer                                                                                                |
| ANY    | `?action=save_wallboard`                                                                      | php-apis           | Create a wallboard and return its link; its only client code is an iOS screen that nothing opens (no caller)                                                 |
| ANY    | `?action=save_wallboard_no_login`                                                             | php-apis           | Create a wallboard (`webCreateWallboardNoLogin`) (no caller)                                                                                                 |
| ANY    | `?action=web_save_wallboard`                                                                  | php-apis           | Create a wallboard (`webCreateWallboard`) (no caller)                                                                                                        |
| ANY    | `?action=webcust_business_job_report`                                                         | php-apis           | Generate a group task report (`getWebCustBusinessJobReportV2`) (no caller)                                                                                   |
| ANY    | `?action=webcust_business_job_report_v2`                                                      | php-apis           | Generate a group task report (`getWebCustBusinessJobReport`) (no caller)                                                                                     |
| POST   | [`?action=checklist_report_excel`](#post-actionchecklist_report_excel)                        | php-apis web       | Queue a checklist report (Excel)                                                                                                                             |
| POST   | [`?action=completed_tasks_report_excel`](#post-actioncompleted_tasks_report_excel)            | php-apis web       | Queue a completed tasks by user report (Excel)                                                                                                               |
| POST   | [`?action=daily_group_report`](#post-actiondaily_group_report)                                | php-apis web       | Queue the daily group report (PDF), for apipy                                                                                                                |
| POST   | [`?action=delete_user_report`](#post-actiondelete_user_report)                                | php-apis web       | Delete one of a user's reports                                                                                                                               |
| POST   | [`?action=inspection_report`](#post-actioninspection_report)                                  | php-apis web       | Queue an inspection report (PDF)                                                                                                                             |
| POST   | [`?action=job_report_v2`](#post-actionjob_report_v2)                                          | php-apis web       | Queue a single task report (PDF)                                                                                                                             |
| POST   | [`?action=job_tc_report`](#post-actionjob_tc_report)                                          | php-apis web       | Build a task's time and cost statement (PDF) and return its link                                                                                             |
| ANY    | `?action=job_tc_report_v2`                                                                    | php-apis web       | Queue a single task's statement of fees (PDF) (`generateSingleTaskReport`) (no caller)                                                                       |
| POST   | [`?action=multi_asset_report_excel`](#post-actionmulti_asset_report_excel)                    | php-apis web       | Queue a multi-asset report (Excel)                                                                                                                           |
| ANY    | `?action=multi_tasks_report_excel`                                                            | php-apis web       | Queue a multi-task report (Excel) (no caller)                                                                                                                |
| POST   | [`?action=multi_tasks_report_pdf`](#post-actionmulti_tasks_report_pdf)                        | php-apis web       | Queue a multi-task report (PDF)                                                                                                                              |
| POST   | [`?action=performance_report_excel`](#post-actionperformance_report_excel)                    | php-apis web       | Queue a performance report (Excel)                                                                                                                           |
| POST   | [`?action=performance_reports`](#post-actionperformance_reports)                              | php-apis web       | List the user's performance reports                                                                                                                          |
| POST   | [`?action=report_task_detail_excel`](#post-actionreport_task_detail_excel)                    | php-apis web       | Queue a task details report (Excel)                                                                                                                          |
| ANY    | `?action=report_task_detail_excel_mobile`                                                     | php-apis web       | Generate a task detail report (Excel), mobile version (no caller)                                                                                            |
| POST   | [`?action=report_time_excel`](#post-actionreport_time_excel)                                  | php-apis web       | Queue a time report (Excel)                                                                                                                                  |
| ANY    | `?action=tasks_images_excel`                                                                  | php-apis web       | Queue a task images report (Excel) (no caller)                                                                                                               |
| POST   | [`?action=user_asset_reports`](#post-actionuser_asset_reports)                                | php-apis web       | List the user's asset reports                                                                                                                                |
| ANY    | `?action=user_report_status`                                                                  | php-apis web       | Get the status of a user's report (`getUserReport`) (no caller)                                                                                              |
| POST   | [`?action=user_reports`](#post-actionuser_reports)                                            | php-apis web       | List the user's reports, or get one report's status                                                                                                          |
| POST   | [`?action=user_tasks_schedule_report`](#post-actionuser_tasks_schedule_report)                | php-apis web       | Queue a site's staff schedule report (PDF) for housekeeping                                                                                                  |
| ANY    | `?action=webcust_job_report`                                                                  | php-apis web       | Generate a task report (no caller)                                                                                                                           |
| ANY    | `?action=webcust_jobs_report`                                                                 | php-apis web       | Generate a tasks report (no caller)                                                                                                                          |
| POST   | `/daily-group-report`                                                                         | apipy              | Generate the daily group report (no caller)                                                                                                                  |
| POST   | `/web/dashboard/compare_summary_datewise`                                                     | apipy              | Dashboard: compare status history by date (no caller)                                                                                                        |
| POST   | [`/web/dashboard/compare_summary_statuswise`](#post-webdashboardcompare_summary_statuswise)   | apipy              | Dashboard: compare status history by status                                                                                                                  |
| POST   | [`/web/dashboard/group_summary`](#post-webdashboardgroup_summary)                             | apipy              | Dashboard: summary by group                                                                                                                                  |
| POST   | [`/web/dashboard/location_summary`](#post-webdashboardlocation_summary)                       | apipy              | Dashboard: tasks with their map position                                                                                                                     |
| POST   | [`/web/dashboard/status_summary`](#post-webdashboardstatus_summary)                           | apipy              | Dashboard: status history by day                                                                                                                             |
| POST   | [`/web/dashboard/tag_summary`](#post-webdashboardtag_summary)                                 | apipy              | Dashboard: summary by tag                                                                                                                                    |
| POST   | [`/web/dashboard/tasks_summary`](#post-webdashboardtasks_summary)                             | apipy              | Dashboard: task summary                                                                                                                                      |
| POST   | [`/web/dashboard/user_summary`](#post-webdashboarduser_summary)                               | apipy              | Dashboard: summary by user                                                                                                                                   |
| POST   | [`/api/analytics/drill-down`](#post-apianalyticsdrill-down)                                   | ops\_dashboard\_be | Analytics: the task rows behind a chart value                                                                                                                |
| POST   | [`/api/analytics/drill-down/export`](#post-apianalyticsdrill-downexport)                      | ops\_dashboard\_be | Analytics: export a drill-down as CSV or Excel                                                                                                               |
| POST   | `/api/analytics/filter-options`                                                               | ops\_dashboard\_be | Analytics: filter options (no caller)                                                                                                                        |
| POST   | [`/api/analytics/room-area-analytics`](#post-apianalyticsroom-area-analytics)                 | ops\_dashboard\_be | Analytics by room and area                                                                                                                                   |
| GET    | `/api/analytics/saved-views`                                                                  | ops\_dashboard\_be | List saved views; the client uses POST instead (no caller)                                                                                                   |
| POST   | [`/api/analytics/saved-views`](#post-apianalyticssaved-views)                                 | ops\_dashboard\_be | List saved views, or create one when the body has a name                                                                                                     |
| PUT    | [`/api/analytics/saved-views/{view_id}`](#put-apianalyticssaved-viewsview_id)                 | ops\_dashboard\_be | Change a saved view                                                                                                                                          |
| DELETE | [`/api/analytics/saved-views/{view_id}`](#delete-apianalyticssaved-viewsview_id)              | ops\_dashboard\_be | Delete a saved view                                                                                                                                          |
| POST   | [`/api/analytics/saved-views/{view_id}/access`](#post-apianalyticssaved-viewsview_idaccess)   | ops\_dashboard\_be | Record that a saved view was opened                                                                                                                          |
| POST   | [`/api/analytics/saved-views/{view_id}/default`](#post-apianalyticssaved-viewsview_iddefault) | ops\_dashboard\_be | Set or clear the default saved view                                                                                                                          |
| POST   | [`/api/analytics/tag-analytics`](#post-apianalyticstag-analytics)                             | ops\_dashboard\_be | Analytics by tag                                                                                                                                             |
| POST   | `/api/analytics/task-summary`                                                                 | ops\_dashboard\_be | Analytics: task summary (no caller)                                                                                                                          |
| POST   | [`/api/analytics/timeseries`](#post-apianalyticstimeseries)                                   | ops\_dashboard\_be | Analytics: time series for the dashboard's charts                                                                                                            |
| POST   | [`/api/analytics/user-analytics`](#post-apianalyticsuser-analytics)                           | ops\_dashboard\_be | Analytics by user                                                                                                                                            |

Notes on the table:

* Rows marked "(no caller)" have no caller in the pinned clones. The only references are registry entries (iOS `ApiEndpointManager.swift`, Android `APIEndPointUtils.java`), the web's endpoint enum, constants or commented-out code. Whether to remove them is open \[[ASK-11](https://github.com/snapfix/docs/blob/main/ASK.md#ask-11-which-unused-api-endpoints-are-still-needed)].
* The no-caller `.php` pages show `ANY`: no code requests them. A server job outside the repos may call the daily email page \[[ASK-13](https://github.com/snapfix/docs/blob/main/ASK.md#ask-13-which-services-and-scheduled-jobs-run-in-production)], and the wallboard pages are made to be opened from links people share. Which wallboard page the links point at is a server setting (`WALLBOARD_URL`) \[[ASK-12](https://github.com/snapfix/docs/blob/main/ASK.md#ask-12-which-settings-do-the-production-api-servers-use)].
* `business_job_report.php` reads a fixed sample file and no request input; its `report_data` read is commented out (php-apis @ 238ca4414e, `htmlphp/api/snapfix/class/business_job_report.php:22`, `:30`). `business_job_report_index.php` redirects to `http://<reports bucket>/<base64-decoded id>`, or shows "REPORT YET TO BE GENERATED !"; the `BUSINESS_REPORT_INDEX` links to it are only built in commented-out code.
* `save_wallboard`'s only client code is iOS `WallboardVC.callGenerateAPI`. The one line that opens that screen is commented out, and its storyboard has no segues into it (ios @ aa31967ac8, `SnapFix/BusinessDetailsVC.swift:1290`, `SnapFix/WallboardVC.swift:763`). The handler requires the named user to be an admin of the named group, saves the request as a row of [`wallboard_instance`](https://docs.snapfix.com/engineering-reference/db/tables/wallboard_instance.md) with the request's field names as column names, and answers `{"result": true, "message": "Wallboard created", "url": "<WALLBOARD_URL><uuid>"}` (php-apis @ 238ca4414e, `htmlphp/api/snapfix/class/class.functions.php:12202-12331`).
* The housekeeping report actions and the `/api/reports/*` routes of ops\_dashboard\_be are in the [Housekeeping group](https://docs.snapfix.com/engineering-reference/api/housekeeping.md), and the admin dashboard actions are in [Staff](https://docs.snapfix.com/engineering-reference/api/staff.md).

## GET /v1/app/report/comply

Builds the compliance dashboard PDF for one site, stores it, and returns its link.

* **Auth:** user token. The caller must be allowed to operate the site (`operate` on the site), or the answer is `403` "Access denied".
* **Used by:** web\_app\_v2 (`ComplyHttpService.getReport`, from the Comply dashboard tab's "Download" button; the page downloads the link, and opens it in a new window when the download fails).

**Request**

| Name               | In     | Type   | Required | Rules                                                                                                         |
| ------------------ | ------ | ------ | -------- | ------------------------------------------------------------------------------------------------------------- |
| `parentUuid`       | query  | string | yes      | The site. Missing: `422`. Unknown: `404`                                                                      |
| `device-tz-offset` | header | string | no       | The caller's offset, such as `GMT+0100`; sets the overdue, due-today and due-soon windows. Default `GMT+0000` |

**Response** `200`

```json
{
  "status": "success",
  "message": "Operation was successful",
  "data": { "url": "https://reports.example.com/report/compliance_dashboard_report1794387600000.pdf" }
}
```

**Errors:** `401` not signed in; `403` "Access denied"; `404` no such site; `422` `parentUuid` missing.

**Side effects:**

* Builds an A4 PDF (DomPDF, view `pdf.complyReport`) of the site's compliance systems by type and status, the counts of overdue, due-today, due-soon and medium and high priority tasks, and the counts of expired and expiring documents. The date and time on it are in the site's time zone.
* The pie chart is an image from quickchart.io; its counts are in the image URL.
* Writes the file to the default disk (`s3-bo`, bucket `AWS_BO_BUCKET`) under `report/`, named `compliance_dashboard_report<epoch ms>.pdf`, and removes the temporary local copy. That disk is configured `private`, and the returned link is a plain bucket URL with no signature, so whether the link opens is not known from the code \[[ASK-115](https://github.com/snapfix/docs/blob/main/ASK.md#ask-115-can-compliance-documents-report-files-and-the-comply-report-be-opened-from-their-link-without-signing-in)].
* Every call stores a new file; nothing in the code removes old ones.
* Loads every counted task with its tags and users, only to count them. The expired documents and the priority tasks are each read twice.
* Writes no database rows.

## POST /api/snapfix/job\_report\_v4.php?uuid\_tJob=

The task report page. It builds one task's PDF, uploads it, and answers with its link, with no login. php-apis calls it itself with `POST`, an empty body, the IDs in the query string and a `Device-tz` header.

* **Auth:** none. Anyone who knows a task's ID gets its PDF.
* **Used by:** php-apis: `getJobReport` (the apps' [`get_job_report`](#post-actionget_job_report)) and `generateJobReportPdfBatchV2` (the web's [`job_report_v2`](#post-actionjob_report_v2)).

**Request**

| Name           | In            | Type    | Required | Rules                                                                                                                                                                                                             |
| -------------- | ------------- | ------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `uuid_tJob`    | query or body | string  | yes      | The task. Missing: "Invalid Request". Unknown or deleted: "Invalid job info"                                                                                                                                      |
| `uuid_tUser`   | query or body | string  | no       | The user the PDF is built for. Default: the task's creator. Not checked against a token                                                                                                                           |
| `report_name`  | query         | string  | no       | The file name; spaces become `_`. Default: the task title with every character other than letters, digits, `_` and `-` replaced by `_` (at most 150 characters, "Task-Report" when empty), then `_<epoch ms>.pdf` |
| `debug_status` | query or body | integer | no       | `1` sends the PDF itself and uploads nothing                                                                                                                                                                      |
| `device-tz`    | header        | string  | no       | The time zone for dates when the task's site has none. Default `UTC`                                                                                                                                              |

**Response** `200`

```json
{ "result": true, "report_http_link": "https://reports.example.com/Leaking_tap_1794387600000.pdf", "report_name": "Leaking_tap_1794387600000.pdf" }
```

On failure: `{"result": false, "message": "...", "report_name": "..."}` with the exception text, for example "PDF file was not written". A fatal PHP error answers `{"result": false, "message": "<error> in <file>:<line>"}`.

**Errors:** "Invalid Request", "Invalid job info", "PDF file was not written", and PHP errors (above), all with HTTP `200`.

**Side effects:**

* Uploads the PDF to the reports bucket (`AWS_S3_BUCKET_REPORTS`) as a public file and deletes the local copy.
* The page sets no memory or time limit and keeps running when the caller disconnects.
* Writes no database rows; its callers update `report_userreports`.

## POST /api/snapfix/job\_tc\_report.php?uuid\_tJob=

The task time and cost page. It builds the statement of fees PDF for one task, uploads it, and answers with its link, with no login. php-apis calls it like the [task report page](#post-apisnapfixjob_report_v4phpuuid_tjob).

* **Auth:** none.
* **Used by:** php-apis: `generateTimeCostReportPdfBatch` (the web's [`job_tc_report`](#post-actionjob_tc_report)). `generateJobTimeCostReportPdfBatchV2` (`job_tc_report_v2`, no caller) calls it too.

**Request**

| Name           | In            | Type    | Required | Rules                                                                                                                                                                                                          |
| -------------- | ------------- | ------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `uuid_tJob`    | query or body | string  | yes      | The task. Missing: "Invalid Request". Unknown or deleted: "Invalid job info"                                                                                                                                   |
| `uuid_tUser`   | query or body | string  | no       | The user the statement is built for. Default: the task's creator                                                                                                                                               |
| `report_name`  | query         | string  | no       | The file name; spaces become `_`. Default: the title with spaces as `-` and every character other than letters, digits and `-` removed, cut to 18 characters when it is longer than 20, then `_<epoch ms>.pdf` |
| `debug_status` | query or body | integer | no       | `1` sends the PDF itself and uploads nothing                                                                                                                                                                   |
| `device-tz`    | header        | string  | no       | The time zone for dates when the task's site has none. Default `UTC`                                                                                                                                           |

**Response** `200`

```json
{ "result": true, "report_http_link": "https://reports.example.com/Leaking-tap_1794387600000.pdf", "report_name": "Leaking-tap_1794387600000.pdf" }
```

**Errors:** "Invalid Request" and "Invalid job info" as `{"result": false, "message": ...}`. The page shows PHP errors as text, so a failure can answer with no JSON.

**Side effects:**

* Uploads the PDF to the reports bucket as a public file.
* Writes the PDF to the server's report folder and does not delete it after the upload.
* Writes no database rows.

## POST ?action=area\_job\_report

Checks an area and its tasks, answers with the link of the area's task PDF at once, and builds the PDF after the answer.

* **Auth:** user token. The area is not checked against the caller.
* **Used by:** iOS (`APIManager.exportJobPDF`, when the current context is an area); Android (`TaskListingActivity`, area listing).

**Request** (JSON body)

| Name          | In   | Type            | Required | Rules                                                                                           |
| ------------- | ---- | --------------- | -------- | ----------------------------------------------------------------------------------------------- |
| `uuid_tArea`  | body | string          | yes      | The area. Unknown: "Invalid Area"                                                               |
| `uuid_tJob`   | body | array of string | yes      | The tasks. Every one must be linked to the area: "Few of the jobs seems to be from other area!" |
| `filter_text` | body | string          | yes      | The filter description printed on the report. Must be present; its value is not checked         |

A missing field answers "Invalid Params".

**Response** `200` (no `serverTs`)

```json
{ "result": true, "report_http_link": "https://reports.example.com/9f1c2e3a-0000-4000-8000-000000000001.pdf", "report_name": "9f1c2e3a-0000-4000-8000-000000000001.pdf" }
```

The name is a new UUID. The link works once the build has finished.

**Errors:** `200` with `result: false`: "Invalid Params", "Invalid Area", "Few of the jobs seems to be from other area!". An empty body: `{"success": "0", "message": "Data cannot be blank!"}`.

**Side effects:** writes no row. After the answer, builds the PDF (`business_job_report_v5.php`) and uploads it under the returned name as a public file.

## POST ?action=business\_job\_report

The same for a group: answers with the link at once and builds the PDF after the answer.

* **Auth:** user token. The row is owned by the token's user. The group is not checked against the caller.
* **Used by:** iOS (`APIManager.exportJobPDF`, when the context is neither a room nor an area); Android (`TaskListingActivity` and `AssetListingActivity`).

**Request** (JSON body)

| Name             | In   | Type            | Required | Rules                                                                                         |
| ---------------- | ---- | --------------- | -------- | --------------------------------------------------------------------------------------------- |
| `uuid_tBusiness` | body | string          | yes      | The group. Unknown: "Invalid Business"                                                        |
| `uuid_tJob`      | body | array of string | yes      | The tasks. Every one must be in the group: "Few of the jobs seems to be from other business!" |
| `filter_text`    | body | string          | yes      | As in [`area_job_report`](#post-actionarea_job_report)                                        |

**Response** `200` (no `serverTs`): as [`area_job_report`](#post-actionarea_job_report). The file name is `<report uuid>.pdf`.

**Errors:** "Invalid Params", "Invalid Business", "Few of the jobs seems to be from other business!".

**Side effects:**

* Inserts a [`report_userreports`](https://docs.snapfix.com/engineering-reference/db/tables/report_userreports.md) row with `reportType` `multi_tasks_report_getBusinessJobReportV2`, `reportFormat` `pdf`, `reportStatus` `new` and the token's user as `uuid_tUser`. Nothing updates the row afterwards, so it stays `new`.
* After the answer, builds the PDF and uploads it as a public file.

## POST ?action=checklist\_report

Builds a checklist report (Excel) of whole groups in the request, uploads it, and answers with its link.

* **Auth:** user token. The request names no user, and the groups are not checked against the caller.
* **Used by:** iOS (`JobNewVC`, `JobsVC` and `AssetListVC` menus, `exportChecklistReport`); Android (`TaskListingActivity`, `AssetListingActivity`).

**Request** (JSON body)

| Name             | In   | Type            | Required | Rules                                                                                                                                                              |
| ---------------- | ---- | --------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `business_uuids` | body | array of string | yes      | The groups. Missing or empty: "invalid business uuids". A JSON array here; the web builders read JSON text instead ([Report filter fields](#report-filter-fields)) |

**Response** `200`

```json
{ "result": true, "message": "success", "serverTs": 1794387600000, "data": { "url": "https://reports.example.com/6b1f0c9e-0000-4000-8000-000000000002.xlsx" } }
```

**Errors:** `200` with `result: false`: "invalid business uuids", "No data found!".

**Side effects:** builds a workbook of every checklist item of every task in the groups, with no date limit, and uploads it as a public file under a new random name. Writes no row.

## POST ?action=export\_jobs\_report

The "Tasks Completed Report" (Excel): the count of tasks each member of a group changed to green, by day and week, in a date range.

* **Auth:** user token. The request names no user, and the group is not checked against the caller.
* **Used by:** iOS (`JobNewVC`, `JobsVC` and `AssetListVC` menus, through `formDataApicall`); Android (`TaskListingActivity`, `AssetListingActivity`), which sends `business_id` and lets `ApiUtils.doPostFormData` send it as `business_uuid`.

**Request** (form data)

| Name                     | In   | Type                 | Required | Rules                                                                             |
| ------------------------ | ---- | -------------------- | -------- | --------------------------------------------------------------------------------- |
| `business_uuid`          | body | string               | yes      | The group. It must exist, not be deleted and not be inactive: "Invalid Business." |
| `start_date`, `end_date` | body | string               | yes      | `DD-MM-YYYY`. Missing or another format: "Invalid parameters."                    |
| `user_ids`               | body | JSON array of string | no       | User emails; only these members are counted. The emails are put into the SQL text |

**Response** `200`

```json
{ "result": true, "message": "Report generated successfully.", "serverTs": 1794387600000, "report_download_link": "https://reports.example.com/2c4e6a8b-0000-4000-8000-000000000003.xlsx" }
```

The link is in `report_download_link`.

**Errors:** `200` with `result: false`: "Invalid parameters.", "Invalid Business.", "No User associated with the selected business.", "Job data not found for the selected business.", "The parameters are too broad which resulted in over 10000 records. Please reduce your date or user requirements".

**Side effects:** builds the workbook in the request and uploads it as a public file under a new random name. Writes no row.

## POST ?action=get\_job\_report

The task report (PDF) for the apps. It calls the [task report page](#post-apisnapfixjob_report_v4phpuuid_tjob) on the same server, waits for it, and answers with the page's answer.

* **Auth:** user token. The row is owned by the token's user; the PDF is built for the `uuid_tUser` in the body, and the page needs no login.
* **Used by:** iOS (`APIManager.reportAPI`, with a 300-second timeout, from the task chat `MessagesVC` and the asset detail `AssetDetailMainVC`); Android (`JobChatFragment`, `AssetMessageActivity`, `AssetDetailsActivity`).

**Request** (JSON body)

| Name             | In   | Type   | Required | Rules                                                      |
| ---------------- | ---- | ------ | -------- | ---------------------------------------------------------- |
| `uuid_tJob`      | body | string | yes      | The task                                                   |
| `uuid_tUser`     | body | string | yes      | The user the PDF is built for. Not compared with the token |
| `uuid_tBusiness` | body | string | yes      | Must be present; not used                                  |

A missing field answers "The required parameters were not included in the API call".

A task is too large when it has more than 50 drawings, images and videos in its chat ([chat item types](https://docs.snapfix.com/engineering-reference/api/chat.md#chat-item-types) 2 to 5) or more than 100 checklist items. Then the answer is `result: false` with "This task is too large. Please generate the Task Report using the web app: <https://web.snapfix.com>".

**Response** `200`: the page's answer, as in the [task report page](#post-apisnapfixjob_report_v4phpuuid_tjob), with `serverTs` added.

```json
{ "result": true, "report_http_link": "https://reports.example.com/Leaking_tap_1794387600000.pdf", "report_name": "Leaking_tap_1794387600000.pdf", "serverTs": 1794387600000 }
```

**Errors:** the messages above, and the page's errors.

**Side effects:**

* Inserts a [`report_userreports`](https://docs.snapfix.com/engineering-reference/db/tables/report_userreports.md) row with `reportType` `job_report_getJobReport` and `reportStatus` `new`. Its `reportUrl` is the page's own URL, not the file's link.
* Sets that row to `completed` at 100% when the page answers, even when the answer is a failure.
* The page uploads the PDF as a public file.

## POST ?action=room\_job\_report

The same as [`area_job_report`](#post-actionarea_job_report) for a room.

* **Auth:** user token. The room is not checked against the caller.
* **Used by:** iOS (`APIManager.exportJobPDF`, when the current context is a room); Android (`TaskListingActivity`, room listing).

**Request** (JSON body)

| Name          | In   | Type            | Required | Rules                                                                                               |
| ------------- | ---- | --------------- | -------- | --------------------------------------------------------------------------------------------------- |
| `uuid_tRoom`  | body | string          | yes      | The room. Unknown: "Invalid Business" (the code's text for a room)                                  |
| `uuid_tJob`   | body | array of string | yes      | The tasks. Every one must be linked to the room: "Few of the jobs seems to be from other business!" |
| `filter_text` | body | string          | yes      | As in [`area_job_report`](#post-actionarea_job_report)                                              |

**Response** `200` (no `serverTs`): as [`area_job_report`](#post-actionarea_job_report), with a new UUID as the file name.

**Errors:** "Invalid Params", "Invalid Business", "Few of the jobs seems to be from other business!".

**Side effects:** writes no row. After the answer, builds the PDF and uploads it as a public file.

## POST ?action=checklist\_report\_excel

Queues a checklist report (Excel) of the filtered tasks.

* **Auth:** user token. `user_uuid` is read from the body, and the groups are read without a membership check.
* **Used by:** web\_app\_v2 (task reports page, "Checklist report", through `DashboardReportsHttpService.createReport`).

**Request** (form data): the [report filter fields](#report-filter-fields).

**Response** `200`: a queued [Report object](#report-object) with `reportType` `checklist_report` and `reportFormat` `xlsx`, named `Checklist-report-<YmdHis>-<first name><last name>.xlsx`.

```json
{
  "result": true,
  "message": "Report generation is in progress",
  "serverTs": 1794387600000,
  "request_serial": "",
  "data": {
    "uuid": "report-123",
    "uuid_tUser": "user-100",
    "reportType": "checklist_report",
    "reportFormat": "xlsx",
    "reportUrl": "https://reports.example.com/Checklist-report-20261113093000-JaneSmith.xlsx",
    "reportStatus": "new",
    "completionPercent": 0,
    "request": { "user_uuid": "user-100", "filename": "Checklist-report-20261113093000-JaneSmith.xlsx", "uuid_report": "report-123" }
  }
}
```

**Errors:** `200` with `result: false`: "Data cannot be blank!" for an empty form, and the filter errors in [Report filter fields](#report-filter-fields).

**Side effects:** one row in [`report_userreports`](https://docs.snapfix.com/engineering-reference/db/tables/report_userreports.md). After the answer, builds the workbook and uploads it as a public file; the row goes through `initated` and `in-progress` to `completed`, or ends at `no tasks found` (`-1`).

## POST ?action=completed\_tasks\_report\_excel

Queues a completed tasks by user report (Excel).

* **Auth:** as [`checklist_report_excel`](#post-actionchecklist_report_excel).
* **Used by:** web\_app\_v2 (task reports page, "Completed tasks by user report").

**Request** (form data): the [report filter fields](#report-filter-fields).

**Response** `200`: a queued [Report object](#report-object) with `reportType` `completed_tasks_report`, `reportFormat` `xlsx`, named `Completed-Tasks-report-<YmdHis>-<first name><last name>.xlsx`.

**Errors:** as [`checklist_report_excel`](#post-actionchecklist_report_excel).

**Side effects:** one row; the workbook is built after the answer and uploaded as a public file.

## POST ?action=daily\_group\_report

Queues the daily group report (PDF) for one group. apipy's `POST /daily-group-report` is its only caller, and no code calls that route; what triggers it each day, and who gets the email the group setting promises, is not in the repos \[[ASK-121](https://github.com/snapfix/docs/blob/main/ASK.md#ask-121-what-sends-the-daily-group-email-and-to-whom)].

* **Auth:** HTTP Basic with `AUTH_USERNAME`: the action is on the web dispatcher's no-token list, so no user token is checked \[[ASK-12](https://github.com/snapfix/docs/blob/main/ASK.md#ask-12-which-settings-do-the-production-api-servers-use)].
* **Used by:** apipy (`featurePhpApi.generateDailyGroupReport`, behind `POST /daily-group-report`, which checks the shared app login).

**Request** (JSON body)

| Name            | In   | Type   | Required | Rules                                                    |
| --------------- | ---- | ------ | -------- | -------------------------------------------------------- |
| `business_uuid` | body | string | yes      | The group. Stored as the row's `uuid_tUser`. Not checked |
| `parent_name`   | body | string | yes      | The site's name, used in the file name. Not checked      |
| `business_name` | body | string | yes      | The group's name, used in the file name. Not checked     |
| `report_date`   | body | string | no       | The day the report covers. Default: yesterday            |

**Response** `200`: a queued [Report object](#report-object) with `reportType` `daily_group_report`, `reportFormat` `pdf` and `reportUrl` `https://<reports bucket>/Daily-Group-Report-<site>-<group>-<YmdHis>.pdf`.

**Errors:** none of its own: missing fields are not reported.

**Side effects:**

* One row in [`report_userreports`](https://docs.snapfix.com/engineering-reference/db/tables/report_userreports.md), created by `api`.
* After the answer, builds the PDF from the group's tasks with activity on the report day, in the site's time zone, and uploads it as a public file. The row is set to `completed` whatever the build answers, also when the day has no tasks and no file is written. The build sends no email.

## POST ?action=delete\_user\_report

Deletes one report from the user's lists. The file stays in the bucket.

* **Auth:** user token. The report must belong to the `user_uuid` in the body, which is not compared with the token.
* **Used by:** web\_app\_v2 (the report lists' trash button, after a confirmation).

**Request** (form data)

| Name          | In   | Type   | Required | Rules                                                          |
| ------------- | ---- | ------ | -------- | -------------------------------------------------------------- |
| `user_uuid`   | body | string | yes      | Missing: "invalid params". Unknown: "invalid user"             |
| `report_uuid` | body | string | yes      | Missing: "invalid params". Unknown: "invalid report to delete" |

**Response** `200`

```json
{ "result": true, "message": "Report deleted successfully!", "serverTs": 1794387600000, "request_serial": "" }
```

**Errors:** `200` with `result: false`: "invalid params", "invalid user", "invalid report to delete", "user not associated with this report!" (the report belongs to someone else).

**Side effects:** sets `fDeleted` to 1, `fModifiedTs`, `fServerTs` and `uuid_tUser_ModifiedBy` on the [`report_userreports`](https://docs.snapfix.com/engineering-reference/db/tables/report_userreports.md) row.

## POST ?action=inspection\_report

Queues an inspection report (PDF).

* **Auth:** as [`checklist_report_excel`](#post-actionchecklist_report_excel).
* **Used by:** web\_app\_v2 (task reports page, "Inspection report").

**Request** (form data): the [report filter fields](#report-filter-fields).

**Response** `200`: a queued [Report object](#report-object) with `reportType` `inspection_report`, `reportFormat` `pdf`, named `Inspection-report-<YmdHis>-<first name><last name>.pdf`.

**Errors:** as [`checklist_report_excel`](#post-actionchecklist_report_excel).

**Side effects:** one row; the PDF is built after the answer and uploaded as a public file.

## POST ?action=job\_report\_v2

Queues a task report (PDF) for one task. The web's task share dialog starts it, and the result appears in the report list.

* **Auth:** user token. `user_uuid` is read from the body, and the task is not checked against the caller.
* **Used by:** web\_app\_v2 (`TaskHttpService.generateTaskReport`, from the task share dialog's "Task Report").

**Request** (JSON body)

| Name            | In   | Type   | Required | Rules                                                                |
| --------------- | ---- | ------ | -------- | -------------------------------------------------------------------- |
| `job_uuid`      | body | string | yes      | The task. Missing: "invalid task". Unknown or deleted: "invalid job" |
| `user_uuid`     | body | string | yes      | An existing, not deleted user: "invalid user"                        |
| `business_uuid` | body | string | no       | The web sends it; not checked                                        |

**Response** `200`: a queued [Report object](#report-object) with `reportType` `job_report` and `reportFormat` `pdf`. The file name is the task title with every character other than letters, digits, `_` and `-` replaced by `_`, then `_<YmdHis>.pdf`.

```json
{ "result": true, "message": "Report generation is in progress", "serverTs": 1794387600000, "request_serial": "", "data": { "uuid": "report-124", "reportType": "job_report", "reportFormat": "pdf", "reportStatus": "new", "completionPercent": 0, "request": { "job_uuid": "job-300", "user_uuid": "user-100", "filename": "Leaking_tap_20261113093000.pdf", "uuid_report": "report-124" } } }
```

**Errors:** `200` with `result: false`: "invalid task", "invalid user", "invalid job".

**Side effects:**

* One row in [`report_userreports`](https://docs.snapfix.com/engineering-reference/db/tables/report_userreports.md).
* After the answer, sets the row to `in-progress` (50%), calls the [task report page](#post-apisnapfixjob_report_v4phpuuid_tjob) with the file name, and sets the row to `completed` (100%) whatever the page answers.

## POST ?action=job\_tc\_report

Builds the time and cost statement ("Statement Of Fees") PDF for one task and answers with its link. Nothing is queued.

* **Auth:** user token. `user_uuid` is read from the body, and the page needs no login.
* **Used by:** web\_app\_v2 (`TimeCostHttpService.generateTaskStatementFeesReport`, from the task's time and cost "Download Statement Of Fees").

**Request** (form data)

| Name        | In   | Type   | Required | Rules                                                    |
| ----------- | ---- | ------ | -------- | -------------------------------------------------------- |
| `job_uuid`  | body | string | yes      | The task. Missing: "invalid params"                      |
| `user_uuid` | body | string | yes      | Missing: "invalid params". Not checked against the token |

**Response** `200`: the [time and cost page's](#post-apisnapfixjob_tc_reportphpuuid_tjob) answer, passed on with `serverTs` and `request_serial` added. The file has the page's default name.

```json
{ "result": true, "report_http_link": "https://reports.example.com/Leaking-tap_1794387600000.pdf", "report_name": "Leaking-tap_1794387600000.pdf", "serverTs": 1794387600000, "request_serial": "" }
```

**Errors:** "Data cannot be blank!" for an empty form; "invalid params"; the page's "Invalid Request" and "Invalid job info". When the page fails with a PHP error, the answer has no `result`.

**Side effects:** the page uploads the PDF as a public file and keeps a local copy. Writes no row.

## POST ?action=multi\_asset\_report\_excel

Queues a multi-asset report (Excel) for the filtered asset registers.

* **Auth:** as [`checklist_report_excel`](#post-actionchecklist_report_excel).
* **Used by:** web\_app\_v2 (asset reports page, "Multi-Asset Report (export)").

**Request** (form data): the [report filter fields](#report-filter-fields), with `business_uuids` holding asset registers.

**Response** `200`: a queued [Report object](#report-object) with `reportType` `multi_asset_report`, `reportFormat` `xlsx`, named `Multiasset-report-<YmdHis>-<first name><last name>.xlsx`.

**Errors:** as [`checklist_report_excel`](#post-actionchecklist_report_excel).

**Side effects:** one row; the workbook is built after the answer and uploaded as a public file.

## POST ?action=multi\_tasks\_report\_pdf

Queues a multi-task report (PDF) of the filtered tasks.

* **Auth:** as [`checklist_report_excel`](#post-actionchecklist_report_excel).
* **Used by:** web\_app\_v2 (task reports page, "Multi-Task Report (PDF)"; the task list's "Share Multi Task Report (PDF)", which polls the report list every 6 seconds, up to 60 times, and downloads the file when it is ready).

**Request** (form data): the [report filter fields](#report-filter-fields).

**Response** `200`: a queued [Report object](#report-object) with `reportType` `multi_tasks_report`, `reportFormat` `pdf`, named `Multitask-report-<YmdHis>-<first name><last name>.pdf`.

**Errors:** as [`checklist_report_excel`](#post-actionchecklist_report_excel).

**Side effects:** one row; the PDF is built after the answer and uploaded as a public file.

## POST ?action=performance\_report\_excel

Queues a performance report (Excel) for a site or multi-site.

* **Auth:** user token; `user_uuid` from the body; groups not checked. The server checks no role. The page that calls it shows it to site admins in its menu, and its route also admits group admins.
* **Used by:** web\_app\_v2 (site reports page, "Performance report").

**Request** (form data): the [report filter fields](#report-filter-fields). The site reports page sends `user_uuid`, `business_uuids`, `created_start_date`, `created_end_date` and `period`, the number of days between the two dates. On a single site, `business_uuids` holds every group of the user, in every site, because the page asks for the group list without a site \[[ASK-117](https://github.com/snapfix/docs/blob/main/ASK.md#ask-117-should-site-reports-on-one-site-list-only-that-sites-groups)].

The builder reads only `period` or `start_date` with `end_date`: "DateRange/Period is mandatory for this report" otherwise. It ignores `created_start_date` and `created_end_date`, so the report covers the `period` days before today, whatever dates were chosen.

**Response** `200`: a queued [Report object](#report-object) with `reportType` `performance_report`, `reportFormat` `xlsx`. The file name is a new random UUID with `.xlsx`.

**Errors:** as [`checklist_report_excel`](#post-actionchecklist_report_excel). The date error ends the row at `-1` after the answer.

**Side effects:** one row; the workbook is built after the answer and uploaded as a public file.

## POST ?action=performance\_reports

Lists the user's performance reports, newest first, with no date limit.

* **Auth:** user token; `user_uuid` from the body, not compared with the token.
* **Used by:** web\_app\_v2 (site reports page, `DashboardReportsHttpService.getReportList` with `isAccountAdminReports`; while a report made today is below 100%, it polls at intervals growing from 3 to 12 seconds, then every 10).

**Request** (form data)

| Name        | In   | Type   | Required | Rules                                              |
| ----------- | ---- | ------ | -------- | -------------------------------------------------- |
| `user_uuid` | body | string | yes      | Missing: "invalid params". Unknown: "invalid user" |

**Response** `200`: `data` is a list of [Report objects](#report-object), without `requestPayload` and `reportName`.

```json
{ "result": true, "message": "Please find your reports", "serverTs": 1794387600000, "request_serial": "", "data": [ { "id": 7, "uuid": "report-125", "reportType": "performance_report", "reportFormat": "xlsx", "reportStatus": "completed", "completionPercent": 100, "reportUrl": "https://reports.example.com/1e2d3c4b-0000-4000-8000-000000000004.xlsx" } ] }
```

**Errors:** `200` with `result: false`: "invalid params", "invalid user", "no reports found!" (an empty list is an error, not an empty `data`).

**Side effects:** none.

## POST ?action=report\_task\_detail\_excel

Queues the task details report (Excel), one row per task.

* **Auth:** as [`checklist_report_excel`](#post-actionchecklist_report_excel).
* **Used by:** web\_app\_v2 (task reports page, "Multi-Task Report (export)").

**Request** (form data): the [report filter fields](#report-filter-fields).

**Response** `200`: a queued [Report object](#report-object) with `reportType` `task_detail_report`, `reportFormat` `xlsx`, named `Task-details-report-<YmdHis>-<first name><last name>.xlsx`.

**Errors:** as [`checklist_report_excel`](#post-actionchecklist_report_excel).

**Side effects:** one row; the workbook is built after the answer and uploaded as a public file.

## POST ?action=report\_time\_excel

Queues a time report (Excel).

* **Auth:** as [`checklist_report_excel`](#post-actionchecklist_report_excel).
* **Used by:** web\_app\_v2 (task reports page, "Time report").

**Request** (form data): the [report filter fields](#report-filter-fields).

**Response** `200`: a queued [Report object](#report-object) with `reportType` `time_report`, `reportFormat` `xlsx`, named `Task-time-report-<YmdHis>-<first name><last name>.xlsx`.

**Errors:** as [`checklist_report_excel`](#post-actionchecklist_report_excel).

**Side effects:** one row; the workbook is built after the answer and uploaded as a public file.

## POST ?action=user\_asset\_reports

Lists the user's asset reports (`multi_asset_report` and `single_asset_report`) from the last 30 days, newest first, or one report's status.

* **Auth:** as [`user_reports`](#post-actionuser_reports).
* **Used by:** web\_app\_v2 (asset reports page, `getReportList` with `isAssetReports`).

**Request** (form data): as [`user_reports`](#post-actionuser_reports), with `reportUUID` working the same way.

**Response** `200`: as [`user_reports`](#post-actionuser_reports), with only the two asset report types.

**Errors:** as [`user_reports`](#post-actionuser_reports).

**Side effects:** none.

## POST ?action=user\_reports

Lists the user's reports from the last 30 days, newest first, or the status and link of one report.

* **Auth:** user token; `user_uuid` from the body, not compared with the token, so a signed-in user who knows another user's ID gets that user's report links. With `reportUUID`, the report's owner is not checked at all.
* **Used by:** web\_app\_v2 (task reports page, `DashboardReportsHttpService.getReportList`, polled every 8 seconds while a report made today is below 100%; the task list's multi-task PDF poll; the housekeeping timeline board's print, `HousekeepingHttpService.getReportStatus`, which sends `reportUUID` every 5 seconds, up to 6 times).

**Request** (form data)

| Name         | In   | Type   | Required | Rules                                                                                                  |
| ------------ | ---- | ------ | -------- | ------------------------------------------------------------------------------------------------------ |
| `user_uuid`  | body | string | yes      | Missing or empty: "invalid params". No user with that UUID: "invalid user"; deleted users are accepted |
| `reportUUID` | body | string | no       | One report. Unknown: "invalid report". Not checked against `user_uuid`                                 |

**Response** `200`: without `reportUUID`, `data` is a list of [Report objects](#report-object) with `requestPayload` and `reportName`. It leaves out the `performance_report`, `multi_asset_report`, `single_asset_report` and `tasks_images_report` types, and has no page size.

```json
{ "result": true, "message": "Please find your reports", "serverTs": 1794387600000, "request_serial": "", "data": [ { "id": 8, "uuid": "report-126", "uuid_tUser": "user-100", "reportType": "multi_tasks_report", "reportName": "multi_tasks_report", "reportFormat": "pdf", "reportStatus": "completed", "completionPercent": 100, "reportUrl": "https://reports.example.com/Multitask-report-20261113093000-JaneSmith.pdf", "requestPayload": "{\"user_uuid\":\"user-100\"}" } ] }
```

With `reportUUID`, the message is "Please find your report" and `data` is `{"uuid": "...", "completionPercent": 100, "reportStatus": "completed", "reportUrl": "..."}`.

**Errors:** `200` with `result: false`: "invalid params", "invalid user", "invalid report", "no reports found!".

**Side effects:** none. Each listed task report needs one lookup for its task's title.

## POST ?action=user\_tasks\_schedule\_report

Queues a PDF of today's tasks for the staff of a site who have working hours (the housekeeping schedule report).

* **Auth:** the token must name a user: "You are not authorized to generate this report" otherwise. The site is not checked against the caller.
* **Used by:** web\_app\_v2 (`HousekeepingHttpService.generateScheduleReport`, from the housekeeping timeline board's print action, which then polls [`user_reports`](#post-actionuser_reports) with `reportUUID` and opens the file).

**Request** (JSON body)

| Name         | In   | Type   | Required | Rules                                                                                                   |
| ------------ | ---- | ------ | -------- | ------------------------------------------------------------------------------------------------------- |
| `parentUUID` | body | string | yes      | The site. Missing: "invalid parentUUID". Unknown: "invalid parent". An empty body: "Invalid parameters" |

The staff are the site's users with a working-hours row, of any date, although the error says today: "no user work schedules found for today". The tasks are those created today (in the `device-tz` header's time zone, default `UTC`) in the site's groups, not deleted or archived, assigned to those staff and with a room or area: "no tasks assigned to users for today" when there are none.

**Response** `200`

```json
{ "result": true, "message": "Report generation is in progress", "serverTs": 1794387600000, "request_serial": "", "data": { "reportURL": "https://reports.example.com/Example_Site-user_tasks_schedules-20261113095200.pdf", "filename": "Example_Site-user_tasks_schedules-20261113095200.pdf", "uuid": "report-127" } }
```

**Errors:** `200` with `result: false`: the messages above.

**Side effects:**

* One row in [`report_userreports`](https://docs.snapfix.com/engineering-reference/db/tables/report_userreports.md) with `reportType` `housekeeping_schedule_report`, whose `uuid_tUser` is the site's UUID, created by the token's user.
* After the answer, builds the PDF, uploads it as a public file, and sets the row to `completed` whatever the build answers.

## POST /web/dashboard/compare\_summary\_statuswise

The status history of the selected period next to the period before it, one series per colour.

* **Auth:** user token (authpy JWT). `user_uuid` is read from the form and not compared with the token. The groups in `business_uuids` are not checked against the caller.
* **Used by:** web\_app\_v2 (dashboard comparison charts, `DashboardReportsHttpService.getTasksCompareSummary`).

**Request** (form data): the [report filter fields](#report-filter-fields), as apipy reads them. `period`, or both `start_date` and `end_date`, is required: "date range must be mentioned inorder to fetch the results". The web always sends `period`.

**Response** `200`: `data` has `red`, `amber` and `green`; each holds `actual` (the period) and `previous` (the period before it), lists of `{label, date, count}` per day. `label` is `Mon DD`.

```json
{ "result": true, "message": "success", "serverTs": 1794387600000, "data": { "red": { "actual": [ { "label": "Nov 01", "date": "2026-11-01", "count": 3 } ], "previous": [ { "label": "Oct 01", "date": "2026-10-01", "count": 5 } ] }, "amber": { "actual": [], "previous": [] }, "green": { "actual": [], "previous": [] } } }
```

**Errors:** `200` with `result: false` and the message: the [filter errors](#report-filter-fields), "date range must be mentioned inorder to fetch the results", and the exception text of any other failure.

**Side effects:** none. Like every dashboard summary, it loads every matching task and counts them in memory.

## POST /web/dashboard/group\_summary

The dashboard's summary by group: one row per group that has matching tasks, sorted by interactions.

* **Auth:** as [`compare_summary_statuswise`](#post-webdashboardcompare_summary_statuswise).
* **Used by:** web\_app\_v2 (dashboard group overview, `getGroupSummary`).

**Request** (form data): the [report filter fields](#report-filter-fields), and:

| Name            | In   | Type    | Required | Rules                                                                   |
| --------------- | ---- | ------- | -------- | ----------------------------------------------------------------------- |
| `no_of_records` | body | integer | no       | At most this many groups. Zero or missing: all. The web doesn't send it |

**Response** `200`: `data` is a list of groups.

```json
{ "result": true, "message": "success", "serverTs": 1794387600000, "data": [ { "business_uuid": "group-200", "business_name": "Maintenance", "business_address": "1 Example Street", "parent_name": "Example Site", "parent_address": "2 Example Road", "business_image": "https://img.example.com/200.jpg", "red": 4, "amber": 7, "green": 20, "new_red": 1, "new_amber": 2, "new_green": 5, "interactions": 312, "last_updated": 1794387600000 } ] }
```

`new_red`, `new_amber` and `new_green` count the matching tasks by colour. `red`, `amber` and `green` count all the group's tasks, with only the archived choice applied, `interactions` counts all the group's chat items, and `last_updated` is the group's own change time.

**Errors:** as [`compare_summary_statuswise`](#post-webdashboardcompare_summary_statuswise), without the date range rule.

**Side effects:** none. It runs one count query per group, one of them over all of the group's chat items.

## POST /web/dashboard/location\_summary

Every matching task with its map position.

* **Auth:** as [`compare_summary_statuswise`](#post-webdashboardcompare_summary_statuswise).
* **Used by:** web\_app\_v2 (dashboard map, `getLocationSummary`).

**Request** (form data): the [report filter fields](#report-filter-fields).

**Response** `200`: `data` is a list of tasks, newest first, with no limit, each with `uuid`, `color`, `fTitle`, `fLargeTextTitle`, `fDescription`, `fImage`, `fPriority`, `fLat`, `fLng` and `fCreatedTs`.

```json
{ "result": true, "message": "success", "serverTs": 1794387600000, "data": [ { "uuid": "job-300", "color": "red", "fTitle": "Leaking tap", "fLargeTextTitle": "Leaking tap, Room 101", "fDescription": "Drips at night", "fImage": "https://img.example.com/300.jpg", "fPriority": 0, "fLat": 53.34, "fLng": -6.26, "fCreatedTs": 1794387600000 } ] }
```

**Errors:** as [`group_summary`](#post-webdashboardgroup_summary).

**Side effects:** none.

## POST /web/dashboard/status\_summary

The status history: a count per colour for each day of the period.

* **Auth:** as [`compare_summary_statuswise`](#post-webdashboardcompare_summary_statuswise).
* **Used by:** web\_app\_v2 (dashboard status history, `getTasksStatusSummary`).

**Request** (form data): as [`compare_summary_statuswise`](#post-webdashboardcompare_summary_statuswise), with the same date range rule.

**Response** `200`: `data` is a list with one item per day. A task counts on the day it got its current colour. `label` is `DD/MM`.

```json
{ "result": true, "message": "success", "serverTs": 1794387600000, "data": [ { "date": "2026-11-01", "label": "01/11", "red": { "count": 3, "percent": 25.0 }, "amber": { "count": 6, "percent": 50.0 }, "green": { "count": 3, "percent": 25.0 } } ] }
```

**Errors:** as [`compare_summary_statuswise`](#post-webdashboardcompare_summary_statuswise).

**Side effects:** none.

## POST /web/dashboard/tag\_summary

The dashboard's summary by tag: one row per tag, sorted by total.

* **Auth:** as [`compare_summary_statuswise`](#post-webdashboardcompare_summary_statuswise).
* **Used by:** web\_app\_v2 (dashboard tag summary, `getTagSummary`).

**Request** (form data): the [report filter fields](#report-filter-fields), with `tagname` (text matched against tag names) and `no_of_records` (at most this many tags; zero or missing returns all). The web sends neither.

**Response** `200`: `data` is a list of tags, each with `uuid`, `tag`, `tag_header`, `tag_header_position`, `red`, `amber`, `green`, `new_green` and `total`.

```json
{ "result": true, "message": "success", "serverTs": 1794387600000, "data": [ { "uuid": "tag-900", "tag": "Hot water", "tag_header": "Issue", "tag_header_position": 1, "red": 2, "amber": 1, "green": 5, "new_green": 0, "total": 8 } ] }
```

**Errors:** as [`group_summary`](#post-webdashboardgroup_summary).

**Side effects:** none.

## POST /web/dashboard/tasks\_summary

The dashboard's task summary: the matching tasks counted by colour.

* **Auth:** as [`compare_summary_statuswise`](#post-webdashboardcompare_summary_statuswise).
* **Used by:** web\_app\_v2 (dashboard task summary, `getTaskSummary`).

**Request** (form data): the [report filter fields](#report-filter-fields).

**Response** `200`: `red`, `amber`, `green` and `unknown` (tasks with no colour), each `{count, percent}`, with the percent rounded to two decimals.

```json
{ "result": true, "message": "success", "serverTs": 1794387600000, "data": { "red": { "count": 12, "percent": 20.0 }, "amber": { "count": 30, "percent": 50.0 }, "green": { "count": 18, "percent": 30.0 }, "unknown": { "count": 0, "percent": 0.0 } } }
```

**Errors:** as [`group_summary`](#post-webdashboardgroup_summary).

**Side effects:** none.

## POST /web/dashboard/user\_summary

The dashboard's summary by user: one row per user who wrote in the matching tasks' chats or is assigned to them, sorted by total.

* **Auth:** as [`compare_summary_statuswise`](#post-webdashboardcompare_summary_statuswise).
* **Used by:** web\_app\_v2 (dashboard user summary, `getUserSummary`).

**Request** (form data): the [report filter fields](#report-filter-fields), with `no_of_records` (at most this many users; zero or missing returns all). `my_tasks` is compared with the number `1`, so as form text it never applies.

**Response** `200`: `data` is a list of users, each with `uuid`, `fName`, `fFirstName`, `fLastName`, `fImage`, `red`, `amber`, `green`, `new_green` and `total`.

```json
{ "result": true, "message": "success", "serverTs": 1794387600000, "data": [ { "uuid": "user-100", "fName": "Jane Smith", "fFirstName": "Jane", "fLastName": "Smith", "fImage": "https://img.example.com/100.jpg", "red": 3, "amber": 1, "green": 6, "new_green": 2, "total": 10 } ] }
```

**Errors:** as [`group_summary`](#post-webdashboardgroup_summary).

**Side effects:** none.

## POST /api/analytics/drill-down

The task rows behind one chart value, for the drill-down table.

* **Auth:** as in [Analytics request](#analytics-request).
* **Used by:** ops\_dashboard\_fe (`fetchDrillDown`, from the drill-down modal, which the tasks dashboard and the tag and user charts open, and from the tasks dashboard itself).

**Request** (JSON body): the scope and dates of the [Analytics request](#analytics-request), and:

| Name                  | In   | Type   | Required | Rules                                                               |
| --------------------- | ---- | ------ | -------- | ------------------------------------------------------------------- |
| `drill_type`          | body | string | no       | The measure, such as `tasks_created` (default) or `tasks_completed` |
| `drill_date`          | body | string | no       | One day or period of the chart. Without it, the whole range         |
| `group_by`            | body | string | no       | `day` (default), `week` or `month`                                  |
| `initial_parent_uuid` | body | string | no       | The site the dashboard shows first                                  |

**Response** `200`: `data` is `{rows, total, drill_type, drill_date}`. Each row has the drill-down columns, such as `job_reference`, `task_title`, `group`, `property`, `status`, `priority`, `created_by_name`, `assignee_name`, `created_at`, `completion_timestamp`, `due_at`, `room_name`, `area_name`, `tag_name` and `tag_category`. Nothing caps the number of rows.

```json
{ "success": true, "request_id": "a1b2c3d4", "data": { "rows": [ { "job_reference": "T-101", "task_title": "Leaking tap", "status": "red", "room_name": "Room 101" } ], "total": 1, "drill_type": "tasks_created", "drill_date": null } }
```

When the caller administers no site with the dashboard on, `rows` is empty.

**Errors:** see [Analytics request](#analytics-request).

**Side effects:** may build the site's cache file; writes nothing to the database.

## POST /api/analytics/drill-down/export

The drill-down rows as a file.

* **Auth:** as in [Analytics request](#analytics-request).
* **Used by:** ops\_dashboard\_fe (`downloadDrillDown`, the drill-down modal's CSV and Excel buttons).

**Request** (JSON body): as [`drill-down`](#post-apianalyticsdrill-down), and `format`: `xlsx` for Excel, anything else for CSV.

**Response** `200`: the file, with `Content-Disposition: attachment; filename=drill_down_<drill type>_<drill date or all>.csv` (or `.xlsx`) and the type `text/csv` or `application/vnd.openxmlformats-officedocument.spreadsheetml.sheet`. The columns have readable names ("Job Reference", "Task Title" and so on), and a cell that starts with `=`, `+`, `-`, `@`, a tab or a carriage return gets a leading `'`, so spreadsheets don't run it as a formula.

**Errors:** a JSON error as in [Analytics request](#analytics-request).

**Side effects:** builds the file in the request; writes nothing to the database.

## POST /api/analytics/room-area-analytics

Task counts by room and by area over time, for the Rooms and Areas tab.

* **Auth:** as in [Analytics request](#analytics-request).
* **Used by:** ops\_dashboard\_fe (`fetchRoomAreaAnalytics`, the room and area charts).

**Request** (JSON body): `from` and `to` (or `from_ms` and `to_ms`), `granularity` (`day`, `week` or `month`; anything else becomes `day`), `limit` (default 10, at most 20), `filters`, and the site fields of the [Analytics request](#analytics-request). With no site field, every accessible site is used.

**Response** `200`: `data` has `room_distribution`, `room_trend`, `room_completion`, `area_distribution`, `area_trend`, `area_completion`, `summary` (`total_rooms`, `total_areas`, `total_room_tasks`, `total_area_tasks`, `busiest_room`, `busiest_area`, `avg_completion_rate`) and `filter_options` (`rooms`, `areas`).

```json
{ "success": true, "request_id": "a1b2c3d4", "data": { "room_distribution": [], "room_trend": [], "summary": { "total_rooms": 40, "busiest_room": "Room 101" }, "filter_options": { "rooms": ["Room 101"], "areas": ["Lobby"] } } }
```

**Errors:** `400` "Date range is required (from/to)"; `403` "No accessible accounts found"; see [Analytics request](#analytics-request).

**Side effects:** may build the site's cache file; writes nothing to the database.

## POST /api/analytics/saved-views

Lists the caller's saved views, or creates one when the body has a non-blank `name`. The route also takes `GET`, which no client sends: the client lists with `POST` and `{"action": "list"}`, because a proxy or CDN strips the `Authorization` header from `GET` requests (its comment in `api/savedViews.js`).

* **Auth:** user token ([Analytics request](#analytics-request)). Views belong to the token's user.
* **Used by:** ops\_dashboard\_fe (`fetchSavedViews` and `createSavedView`, from the saved views menu).

**Request** (JSON body): for a list, no `name`. For a create:

| Name                                        | In   | Type    | Required | Rules                                                                                                                        |
| ------------------------------------------- | ---- | ------- | -------- | ---------------------------------------------------------------------------------------------------------------------------- |
| `name`                                      | body | string  | yes      | Trimmed; at most 100 characters: "View name must be 100 characters or less". Unique among the user's views: `DUPLICATE_NAME` |
| `description`                               | body | string  | no       | Trimmed and cut to 500 characters                                                                                            |
| `globalFilters`, `tabStates`, `preferences` | body | object  | no       | Saved as sent. Default `{}`                                                                                                  |
| `activeTab`                                 | body | string  | no       | Default `overview`                                                                                                           |
| `isDefault`                                 | body | boolean | no       | `true` makes this the default and clears the user's other defaults. Default `false`                                          |
| `colorLabel`                                | body | string  | no       | Cut to 20 characters                                                                                                         |
| `sortOrder`                                 | body | integer | no       | Default `0`                                                                                                                  |

A user with 5 views gets `LIMIT_EXCEEDED`.

**Response** `200`: for a list, the [saved views](#saved-view-object) ordered by `sortOrder`, then newest first:

```json
{ "success": true, "views": [ { "id": 7, "uuid": "view-700", "name": "Weekly review", "description": null, "isDefault": true, "globalFilters": {}, "tabStates": {}, "activeTab": "overview", "preferences": {}, "sortOrder": 0, "colorLabel": null, "createdAt": 1794387600000, "modifiedAt": 1794387600000, "lastAccessedAt": null, "accessCount": 0 } ], "count": 1, "maxViews": 5 }
```

For a create, `{"success": true, "message": "View saved successfully", "view": {...}}`, with the view's fields except `lastAccessedAt` and `accessCount`.

**Errors:** `400` `VALIDATION_ERROR` ("View name must be 100 characters or less"); `400` `LIMIT_EXCEEDED` ("Maximum of 5 saved views allowed. Please delete an existing view first.", with `currentCount` and `maxViews` in `details`); `400` `DUPLICATE_NAME` ("A view with this name already exists"); see [Analytics request](#analytics-request).

**Side effects:** a create inserts a row in [`saved_dashboard_views`](https://docs.snapfix.com/engineering-reference/db/tables/saved_dashboard_views.md). A list writes nothing.

## PUT /api/analytics/saved-views/{view\_id}

Changes a saved view: its name, filters, tabs, default flag and so on.

* **Auth:** user token. The view must be the token user's and not deleted, or the answer is `404` "View not found".
* **Used by:** ops\_dashboard\_fe (`updateSavedView`, the rename and save actions).

**Request** (JSON body)

| Name                                                                                                                           | In   | Type    | Required | Rules                                                                                                                                                             |
| ------------------------------------------------------------------------------------------------------------------------------ | ---- | ------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `view_id`                                                                                                                      | path | integer | yes      | The view                                                                                                                                                          |
| any of `name`, `description`, `globalFilters`, `tabStates`, `activeTab`, `preferences`, `isDefault`, `colorLabel`, `sortOrder` | body |         | no       | The create rules of [`saved-views`](#post-apianalyticssaved-views); a blank `name` gives "View name is required". A body with none of them: "No fields to update" |

**Response** `200`: `{"success": true, "message": "View updated successfully", "view": {...}}`, with the [saved view](#saved-view-object) fields except `uuid`.

**Errors:** `404` `NOT_FOUND` ("View not found"); `400` `VALIDATION_ERROR` ("View name is required", "View name must be 100 characters or less", "No fields to update"); `400` `DUPLICATE_NAME`.

**Side effects:** updates the row in [`saved_dashboard_views`](https://docs.snapfix.com/engineering-reference/db/tables/saved_dashboard_views.md). With `isDefault` `true`, clears the default flag on the user's other views first.

## DELETE /api/analytics/saved-views/{view\_id}

Deletes a saved view.

* **Auth:** user token; the view must be the token user's, or the answer is `404`.
* **Used by:** ops\_dashboard\_fe (`deleteSavedView`, after the "Delete View" confirmation, which says "This action cannot be undone.").

**Request**

| Name      | In   | Type    | Required | Rules             |
| --------- | ---- | ------- | -------- | ----------------- |
| `view_id` | path | integer | yes      | The view. No body |

**Response** `200`: `{"success": true, "message": "View deleted successfully", "deletedId": 7}`.

**Errors:** `404` `NOT_FOUND` ("View not found").

**Side effects:** soft-deletes the row in [`saved_dashboard_views`](https://docs.snapfix.com/engineering-reference/db/tables/saved_dashboard_views.md): sets `fDeleted`, `fDeletedts` and `fModifiedts`, and renames the view to `<name>__deleted_<epoch ms>` (cut to 100 characters) so the name can be used again.

## POST /api/analytics/saved-views/{view\_id}/access

Records that the caller opened a saved view.

* **Auth:** user token; the view must be the token user's and not deleted.
* **Used by:** ops\_dashboard\_fe (`recordViewAccess`, when a view is selected). The client ignores failures.

**Request**

| Name      | In   | Type    | Required | Rules             |
| --------- | ---- | ------- | -------- | ----------------- |
| `view_id` | path | integer | yes      | The view. No body |

**Response** `200`: `{"success": true, "viewId": 7, "lastAccessedAt": 1794387600000}`.

**Errors:** `404` `NOT_FOUND` ("View not found").

**Side effects:** sets `last_accessed_at` and adds one to `access_count` in [`saved_dashboard_views`](https://docs.snapfix.com/engineering-reference/db/tables/saved_dashboard_views.md).

## POST /api/analytics/saved-views/{view\_id}/default

Makes a saved view the caller's default, or clears it.

* **Auth:** user token; the view must be the token user's and not deleted.
* **Used by:** ops\_dashboard\_fe (`setDefaultView`, the star button, which always sends `true`).

**Request**

| Name        | In   | Type    | Required | Rules                                           |
| ----------- | ---- | ------- | -------- | ----------------------------------------------- |
| `view_id`   | path | integer | yes      | The view                                        |
| `isDefault` | body | boolean | no       | Default `true`. `false` clears this view's flag |

**Response** `200`: `{"success": true, "message": "View set as default", "viewId": 7, "isDefault": true}`. With `false`, the message is "View removed as default".

**Errors:** `404` `NOT_FOUND` ("View not found").

**Side effects:** with `true`, clears the default flag on all of the user's views and sets it on this one; with `false`, clears it on this one. Both in [`saved_dashboard_views`](https://docs.snapfix.com/engineering-reference/db/tables/saved_dashboard_views.md).

## POST /api/analytics/tag-analytics

Task counts by tag or tag category over time, or the average times to start and to complete, for the tag charts.

* **Auth:** as in [Analytics request](#analytics-request).
* **Used by:** ops\_dashboard\_fe (`fetchTagAnalytics`, the tag charts).

**Request** (JSON body)

| Name                                                                | In   | Type            | Required | Rules                                                                                                                                             |
| ------------------------------------------------------------------- | ---- | --------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
| `from_ms`, `to_ms`                                                  | body | integer         | yes      | Unix ms; `from` and `to`, or `start_date` and `end_date` (dates), also work. Missing: "Date range is required (start\_date/end\_date or from/to)" |
| `granularity`                                                       | body | string          | no       | `day` (default), `week` or `month`; anything else becomes `day`                                                                                   |
| `metric_type`                                                       | body | string          | no       | `task_created` (default), `task_completed`, `avg_time_to_start` or `avg_time_to_complete`; anything else becomes `task_created`                   |
| `group_by`                                                          | body | string          | no       | `tag` (default), `tag_category` or `none`                                                                                                         |
| `tag_categories`, `tags`                                            | body | array of string | no       | Filters on tag categories and tags                                                                                                                |
| `limit`                                                             | body | integer         | no       | Series to return. Default 6, at most 10                                                                                                           |
| `filters`                                                           | body | object          | no       | As in [Analytics request](#analytics-request)                                                                                                     |
| `parent_uuid`, `parent_uuids`, `all_parents`, `initial_parent_uuid` | body |                 | no       | The sites. With no site field, every accessible site                                                                                              |

**Response** `200`: `data` has `trend_data`, `distribution_data`, `performance_data`, `insights` and `meta` (`total_data_points`, `series_count`, `auto_aggregated`, `limited_to_top`, `granularity_used`, `warning`). `filter_options` (`tag_categories`, `tags`) and `meta` (`mode`, `parent_uuids`) sit next to `data`.

```json
{ "success": true, "request_id": "a1b2c3d4", "data": { "trend_data": [], "distribution_data": [], "performance_data": [], "insights": {}, "meta": { "series_count": 6, "limited_to_top": true, "granularity_used": "day" } }, "filter_options": { "tag_categories": ["Issue"], "tags": ["Hot water"] }, "meta": { "mode": "production", "parent_uuids": ["site-500"] } }
```

**Errors:** `400` `VALIDATION_ERROR` for the dates or a `filters` that is not an object; `403` "No accessible accounts found"; see [Analytics request](#analytics-request).

**Side effects:** may build the site's cache file; writes nothing to the database.

## POST /api/analytics/timeseries

The time series and summaries behind the Ops Dashboard's tasks dashboard and account charts, for one or more sites and a date range.

* **Auth:** as in [Analytics request](#analytics-request).
* **Used by:** ops\_dashboard\_fe (`fetchTimeseries`, the tasks dashboard and the account charts).

**Request** (JSON body): the [Analytics request](#analytics-request), and:

| Name                  | In   | Type    | Required | Rules                                                                                                                             |
| --------------------- | ---- | ------- | -------- | --------------------------------------------------------------------------------------------------------------------------------- |
| `include_timeseries`  | body | boolean | no       | Default `true`                                                                                                                    |
| `prefetch_others`     | body | boolean | no       | With `initial_parent_uuid` and several sites: answers that site now and builds the others' caches in the background               |
| `initial_parent_uuid` | body | string  | no       | The site to answer first. When it is not accessible, the first accessible site is used and `meta.parent_fallback_warning` says so |
| `split_by_parent`     | body | boolean | no       | Adds `by_parent`, one answer per site                                                                                             |

The client also sends `progress_id`, which the server doesn't read.

**Response** `200`

```json
{
  "success": true,
  "request_id": "a1b2c3d4",
  "data": [ { "date": "2026-11-13", "tasks_created": 12, "tasks_completed": 9 } ],
  "checklist_series": [],
  "meta": {
    "group_by": "day",
    "mode": "production",
    "filter_options": { "accounts": [ { "uuid": "site-500", "name": "Example Site", "room_count": 40 } ] },
    "summary_by": {},
    "parent_uuids": ["site-500"],
    "current_parent_uuid": "site-500",
    "current_parent_name": "Example Site"
  }
}
```

When the caller administers no site with the dashboard on, `data` is empty and `meta.filter_options.accounts` lists no site.

**Errors:** see [Analytics request](#analytics-request).

**Side effects:**

* Reads each site's tasks, assignees, checklist items, rooms, areas and tags for the range through a cache file per site and range, built on a miss; `filters` apply in memory afterwards.
* With `prefetch_others`, builds the other sites' caches in background threads.
* Writes nothing to the database.

## POST /api/analytics/user-analytics

Task counts by user over time, for the Users tab.

* **Auth:** as in [Analytics request](#analytics-request).
* **Used by:** ops\_dashboard\_fe (`fetchUserAnalytics`, the user charts).

**Request** (JSON body): as [`room-area-analytics`](#post-apianalyticsroom-area-analytics), and `task_type`: `all` (default), `manual` or `planned`.

**Response** `200`: `data` has `table`, `top_completers`, `top_creators`, `user_trend`, `user_trend_completed`, `user_trend_avg_completion`, `user_completion_breakdown` and `summary` (`total_users`, `most_active`, `top_completer`, `most_assigned`, `avg_completion_rate`, `total_completed`, `total_overdue`).

```json
{ "success": true, "request_id": "a1b2c3d4", "data": { "table": [], "top_completers": [], "summary": { "total_users": 12, "most_active": "Jane Smith" } } }
```

**Errors:** as [`room-area-analytics`](#post-apianalyticsroom-area-analytics).

**Side effects:** may build the site's cache file; writes nothing to the database.

## Report object

The [`report_userreports`](https://docs.snapfix.com/engineering-reference/db/tables/report_userreports.md) row that a queued action answers with in `data`, and that the report lists return.

| Field                                           | Type    | Meaning                                                                                                                                                                                                                                                                                                                                                                                                                     |
| ----------------------------------------------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `id`                                            | integer | The row ID (lists only)                                                                                                                                                                                                                                                                                                                                                                                                     |
| `uuid`                                          | string  | The report. Poll it with [`user_reports`](#post-actionuser_reports) and `reportUUID`; delete it with `report_uuid`                                                                                                                                                                                                                                                                                                          |
| `uuid_tUser`                                    | string  | The owner. For the daily group report, the group; for the housekeeping schedule report, the site                                                                                                                                                                                                                                                                                                                            |
| `reportType`                                    | string  | `checklist_report`, `completed_tasks_report`, `inspection_report`, `job_report`, `multi_asset_report`, `multi_tasks_report`, `performance_report`, `task_detail_report`, `time_report`, `daily_group_report`, `housekeeping_schedule_report`, or the apps' `job_report_getJobReport` and `multi_tasks_report_getBusinessJobReportV2`. In the lists, a `job_report` or `single_asset_report` row shows its task's title here |
| `reportName`                                    | string  | Lists of `user_reports` and `user_asset_reports` only: the task's UUID for a `job_report` or `single_asset_report` row, otherwise the type                                                                                                                                                                                                                                                                                  |
| `reportFormat`                                  | string  | `pdf` or `xlsx`                                                                                                                                                                                                                                                                                                                                                                                                             |
| `reportUrl`                                     | string  | The file's link in the reports bucket, set before the file exists (`https` when the bucket name contains `live`, otherwise `http`). For `get_job_report`, the page's own URL                                                                                                                                                                                                                                                |
| `reportStatus`                                  | string  | `new` when made, `initated` (spelled so) at 10%, `in-progress` from 20% to 90%, `completed` at 100%. A failed build keeps its error text instead, such as "no tasks found", "invalid user", "user is not associated with any business yet!", "invalid priority", "invalid archived", "invalid schedule", "invalid start and end dates" or "DateRange/Period is mandatory for this report"                                   |
| `completionPercent`                             | integer | `0` when queued, 10 to 90 while building, `100` when done, `-1` after an error                                                                                                                                                                                                                                                                                                                                              |
| `requestPayload`                                | string  | The request as JSON. In the queue answers, `user_reports` and `user_asset_reports`; not in `performance_reports`                                                                                                                                                                                                                                                                                                            |
| `fCreatedTs`, `fModifiedTs`, `fServerTs`        | integer | Epoch ms                                                                                                                                                                                                                                                                                                                                                                                                                    |
| `fDeleted`                                      | integer | `1` after [`delete_user_report`](#post-actiondelete_user_report)                                                                                                                                                                                                                                                                                                                                                            |
| `uuid_tUser_CreatedBy`, `uuid_tUser_ModifiedBy` | string  | Who made and last changed the row; `api` for the build's updates                                                                                                                                                                                                                                                                                                                                                            |
| `request`                                       | object  | Queue answers only: the request, with `filename` and `uuid_report` (the row's `uuid`) added                                                                                                                                                                                                                                                                                                                                 |

## Report filter fields

The fields the php-apis report builders read (`buildWhereClause` and the builders), sent as form data with arrays as JSON text. The apipy dashboards read the same names, with the differences listed below the table.

| Name                                                            | In   | Type               | Required | Rules                                                                                                                                                                            |
| --------------------------------------------------------------- | ---- | ------------------ | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `user_uuid`                                                     | body | string             | yes      | Missing: "invalid user\_uuid". Not an existing, not deleted user: "invalid user". Not compared with the token                                                                    |
| `business_uuids`                                                | body | JSON array as text | no       | The groups to report on: those that exist, are not deleted or inactive, and whose site is not deleted. Membership is not checked                                                 |
| `parent_uuids`                                                  | body | JSON array as text | no       | Sites; their active groups are used when `business_uuids` gives no group. Membership is not checked                                                                              |
| (neither)                                                       |      |                    |          | The user's active memberships. No group at all: "user is not associated with any business yet!"                                                                                  |
| `period`                                                        | body | integer            | no       | The last N days, through the end of today                                                                                                                                        |
| `start_date`, `end_date`                                        | body | `YYYY-MM-DD`       | no       | Tasks created in the range, both days included                                                                                                                                   |
| `created_start_date`, `created_end_date`                        | body | `YYYY-MM-DD`       | no       | The same; they override `period` and `start_date`                                                                                                                                |
| `activity_start_date`, `activity_end_date`                      | body | `YYYY-MM-DD`       | no       | Tasks changed or with chat activity in the range. When sent, the creation range is not applied                                                                                   |
| `priority`                                                      | body | `0` or `1`         | no       | The old star flag. Other values: "invalid priority", by a loose check after which the value goes into the SQL text. The web sends `priorityLevel` instead, which no report reads |
| `archived`                                                      | body | `0` or `1`         | no       | `0` leaves archived tasks out; `1` includes them. Other values: "invalid archived". Checked and used like `priority`                                                             |
| `normal_tasks`, `archived_tasks`                                | body | `1`                | no       | Read when `archived` is missing: both `1` means all tasks, `archived_tasks` alone archived only; otherwise active only                                                           |
| `schedule`                                                      | body | `1`                | no       | Only tasks made from a schedule. `0` gives "invalid schedule", and other values are ignored                                                                                      |
| `colors`                                                        | body | JSON array as text | no       | Any of `red`, `amber` (`yellow` counts as amber) and `green`                                                                                                                     |
| `with_cost`                                                     | body | `1`                | no       | Only tasks with a time or cost entry                                                                                                                                             |
| `my_tasks`                                                      | body | `1`                | no       | Only the user's own tasks                                                                                                                                                        |
| `user_uuids`, `user_uuids_created_by`, `user_uuids_assigned_to` | body | JSON array as text | no       | People: members, creators and assignees                                                                                                                                          |
| `tagnames`                                                      | body | JSON array as text | no       | Tag UUIDs, despite the name; the web sends the selected tags' UUIDs                                                                                                              |
| `asset_uuids`                                                   | body | JSON array as text | no       | Tasks linked to these assets                                                                                                                                                     |

* A start date after its end date gives "invalid start and end dates".
* The dates are read in the `device-tz` header's time zone, default `UTC`.
* The web always sends `user_uuid` and `period` (30, or the days between the chosen dates), and its filters. Except on the site reports page, it also sends the selected site in `parent_uuids`.

How the apipy dashboards differ:

* `parent_uuids` keeps only the sites' groups where `user_uuid` is an active member; `business_uuids` is still not checked.
* `priorityLevel` (JSON array of levels) filters by priority level.
* `archived` replaces `archived_tasks`: with `normal_tasks`, both `1` means all tasks, `archived` alone archived only, `normal_tasks` alone active only. When either is sent with another value, archived tasks are not filtered at all.
* `period`, `start_date` and `end_date` apply only when no creation or activity range is sent, and then match tasks created, changed or with chat activity in the range. "invalid range for 'created date'" and "invalid range for 'activity date'" are the range errors.
* `with_cost`, `my_tasks` and `schedule` are compared with the number `1`, so as form text they never apply. The web's "tasks with cost" filter therefore does nothing on the dashboard.
* `tagname` (text) matches tag names in every group. `tagnames` holds tag UUIDs as in the reports.
* `user_uuids_assigned_to` or `asset_uuids` that match no task give "no jobs found".
* Every filter value is passed as a query parameter.

## Analytics request

What the ops\_dashboard\_be analytics endpoints share.

* **Token:** `Authorization: Bearer <JWT>`, HS256 with the service's `JWT_SECRET`. The user is the token's `identity` claim, or `user_uuid` or `sub`. Errors: `401` "Missing or invalid Authorization header.", "Missing JWT.", "Invalid token.", "JWT missing user\_uuid/identity.", and `500` when `JWT_SECRET` is not set. The expiry check is skipped while the `SKIP_JWT_EXPIRY` setting is on, which the code marks as local testing only \[[ASK-12](https://github.com/snapfix/docs/blob/main/ASK.md#ask-12-which-settings-do-the-production-api-servers-use)]. The web hands the token to the Ops Dashboard frame in its URL.
* **Sites:** a site is accessible when the user is its admin (`tPri_UserParent.user_type` `admin`) and its `fTaskDashboardEnabled` is on. A requested site that is not accessible gives `403` "Forbidden.".

The body of `timeseries` (and of the no-caller `filter-options` and `task-summary`) is a JSON object:

| Name           | In   | Type            | Required         | Rules                                                                                                                                                                  |
| -------------- | ---- | --------------- | ---------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `parent_uuids` | body | array of string | one of the three | The sites. Not an array, empty, or with an empty value: `400`                                                                                                          |
| `parent_uuid`  | body | string          | one of the three | One site. An array or empty: `400`                                                                                                                                     |
| `all_parents`  | body | boolean         | one of the three | `true` for every accessible site. None of the three: `400`                                                                                                             |
| `from`, `to`   | body | integer         | yes              | Unix ms, `from` not after `to`: "'from' and 'to' must be integers (unix ms).", "'from' must be <= 'to'.". A legacy `date_range` object with the same fields also works |
| `group_by`     | body | string          | no               | `day` (default), `week` or `month`: "group\_by must be one of: day, week, month."                                                                                      |
| `filters`      | body | object          | no               | Dimension filters, applied in memory: "filters must be an object if provided."                                                                                         |

`drill-down` and its export read the same fields with looser checks: `from` and `to` need only be integers ("Missing 'from' and 'to' timestamps." when absent), an unknown `group_by` becomes `day`, and `filters` is not checked. `tag-analytics`, `room-area-analytics` and `user-analytics` read their own body: see their sections.

**Answers:** `{"success": true, "request_id": "...", "data": ...}` with the request ID also in the `X-Request-ID` header. Errors are `{"success": false, "error_code": "...", "message": "...", "request_id": "...", "details": {...}}`; `details` only when there is more to say. The code follows the status: `400` `VALIDATION_ERROR` (also a body that is not a JSON object: "Invalid JSON body.", "Request body must be a JSON object."), `401` `AUTHENTICATION_ERROR`, `403` `AUTHORIZATION_ERROR`, `404` `NOT_FOUND`, `500` `INTERNAL_ERROR` ("An unexpected error occurred. Please try again or contact support."). The saved views add `LIMIT_EXCEEDED` and `DUPLICATE_NAME` with `400`. The service sends no other statuses itself; the client's `DATA_BUILD_IN_PROGRESS`, `SERVICE_BUSY` and `EXPORT_ERROR` codes are its own.

## Saved view object

One saved set of Ops Dashboard filters and tabs, per user, in [`saved_dashboard_views`](https://docs.snapfix.com/engineering-reference/db/tables/saved_dashboard_views.md).

| Field                                       | Type           | Meaning                                                                  |
| ------------------------------------------- | -------------- | ------------------------------------------------------------------------ |
| `id`                                        | integer        | The view; `view_id` in the paths                                         |
| `uuid`                                      | string         | The view's UUID                                                          |
| `name`                                      | string         | 1 to 100 characters, unique per user                                     |
| `description`                               | string or null | Up to 500 characters                                                     |
| `isDefault`                                 | boolean        | The user's default view                                                  |
| `globalFilters`, `tabStates`, `preferences` | object         | The dashboard's filters, tab states and display choices, as sent         |
| `activeTab`                                 | string         | The tab open when saved; default `overview`                              |
| `sortOrder`                                 | integer        | Display order                                                            |
| `colorLabel`                                | string or null | Up to 20 characters                                                      |
| `createdAt`, `modifiedAt`, `lastAccessedAt` | integer        | Epoch ms; `lastAccessedAt` is null until the view is opened              |
| `accessCount`                               | integer        | Opens recorded by [`access`](#post-apianalyticssaved-viewsview_idaccess) |

## Common side effects

What the sections above mean by these words.

* **Report row:** a request that queues a file writes one row to [`report_userreports`](https://docs.snapfix.com/engineering-reference/db/tables/report_userreports.md) with status `new`, and the build updates it ([Report object](#report-object)). `get_job_report` and `business_job_report` write a row without the queue; the second one is never updated.
* **Public file:** files go to the bucket in `AWS_S3_BUCKET_REPORTS` with the `public-read` ACL (php-apis @ 238ca4414e, `html/api/snapfix/s3.php:275-305`), so anyone with the link can open them. The queued reports' names carry the time and the user's name; the daily report's names carry the site's and the group's names.
* **Build after the answer:** the queued actions and the area, group and room PDFs send the answer, close the connection, and build the file in the same PHP process. The dispatchers allow 600 seconds and 3 GB of memory. Nothing queues the builds or limits how many run at once.
* **Polling:** the web re-reads the report list or one report every 3 to 10 seconds while a report is pending; each section says where.
* **Emails and pushes:** none in the report code.
* **Request log:** after every call, as on the [Tasks](https://docs.snapfix.com/engineering-reference/api/tasks.md#common-side-effects) page.

## Common errors

Each backend has its own envelope ([Responses](https://docs.snapfix.com/engineering-reference/api.md#responses)). Each section lists its own messages; these apply to all of them.

* **php-apis:** `{"result": false, "message": "..."}` with HTTP 200, and any exception's text. An empty body gives "Data cannot be blank!"; the app dispatcher answers that as `{"success": "0", "message": ...}` for the area, group, room and task report actions. The token errors and the Basic login error ("You are not authorised to access this API.") are in [API conventions](https://docs.snapfix.com/engineering-reference/api.md#user-tokens).
* **apipy:** `{"result": false, "message": "...", "serverTs": ...}` with the filter error or the exception text. A missing or bad token gives `401`.
* **api\_php\_live\_v2:** `{"status": "error", "message": "..."}`, with the status codes in [API conventions](https://docs.snapfix.com/engineering-reference/api.md#responses).
* **ops\_dashboard\_be:** see [Analytics request](#analytics-request).


---

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