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

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

Creating, listing and changing tasks and their details (assignees, followers, tags, rooms, areas, assets, time, cost, due dates, signatures, reminders), sharing tasks, and the mobile apps' task data loads.

* **Services:** `api_php_live_v2` at `https://z4.snapfix.com` (`/v1/app`); `php-apis` at `https://z1.snapfix.com/api/snapfix/index.php`; `php-apis web` at `https://z1.snapfix.com/api/snapfix/web/index.php`; `apipy` at `https://z2.snapfix.com`
* **Auth:** api\_php\_live\_v2: user token (authpy access JWT in `Authorization: Bearer`); each endpoint then checks the caller's membership and permissions in the task's group, as its section says ([task permissions](#task-permissions)), but five endpoints that change tasks check nothing beyond the token. 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 ID in the request, not the token's user, and don't check that the user may act on the task, group or row they name; some actions take 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`), with the user taken from the URL on the task routes; app basic auth (the shared login built into the apps).
* **Used by:** web\_app\_v2, iOS, Android, webadmin\_angular, web\_tasks, snapfix\_ai\_agent (Simon, the AI assistant), apipy; 90 of the 184 endpoints have no known caller

| Method | Path                                                                                      | Service            | Purpose                                                                                                                                                                                        |
| ------ | ----------------------------------------------------------------------------------------- | ------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| POST   | `/v1/app/read-queue`                                                                      | api\_php\_live\_v2 | Read the queue log (no caller)                                                                                                                                                                 |
| POST   | `/v1/app/save-queue`                                                                      | api\_php\_live\_v2 | Save a batch of queue log entries (no caller)                                                                                                                                                  |
| POST   | [`/v1/app/tasks`](#post-v1apptasks)                                                       | api\_php\_live\_v2 | Create a task                                                                                                                                                                                  |
| POST   | [`/v1/app/tasks/all/archive`](#post-v1apptasksallarchive)                                 | api\_php\_live\_v2 | Archive or unarchive all of a group's tasks that match the filters                                                                                                                             |
| POST   | [`/v1/app/tasks/all/delete`](#post-v1apptasksalldelete)                                   | api\_php\_live\_v2 | Delete all of a group's tasks that match the filters                                                                                                                                           |
| POST   | [`/v1/app/tasks/all/lock`](#post-v1apptasksalllock)                                       | api\_php\_live\_v2 | Lock or unlock all of a group's tasks that match the filters                                                                                                                                   |
| POST   | [`/v1/app/tasks/all/move`](#post-v1apptasksallmove)                                       | api\_php\_live\_v2 | Move all of a group's tasks that match the filters to another group                                                                                                                            |
| POST   | [`/v1/app/tasks/all/priority`](#post-v1apptasksallpriority)                               | api\_php\_live\_v2 | Set the priority of all of a group's tasks that match the filters                                                                                                                              |
| POST   | [`/v1/app/tasks/all/status`](#post-v1apptasksallstatus)                                   | api\_php\_live\_v2 | Set the status of all of a group's tasks that match the filters                                                                                                                                |
| POST   | [`/v1/app/tasks/area-add`](#post-v1apptasksarea-add)                                      | api\_php\_live\_v2 | Set a task's area                                                                                                                                                                              |
| POST   | [`/v1/app/tasks/area-remove`](#post-v1apptasksarea-remove)                                | api\_php\_live\_v2 | Remove an area from a task                                                                                                                                                                     |
| POST   | [`/v1/app/tasks/asset-link`](#post-v1apptasksasset-link)                                  | api\_php\_live\_v2 | Link assets to a task                                                                                                                                                                          |
| POST   | [`/v1/app/tasks/asset-unlink`](#post-v1apptasksasset-unlink)                              | api\_php\_live\_v2 | Unlink assets from a task                                                                                                                                                                      |
| POST   | [`/v1/app/tasks/assign`](#post-v1apptasksassign)                                          | api\_php\_live\_v2 | Assign a user to a task                                                                                                                                                                        |
| POST   | [`/v1/app/tasks/assign/multi`](#post-v1apptasksassignmulti)                               | api\_php\_live\_v2 | Assign and unassign several users on a task                                                                                                                                                    |
| POST   | [`/v1/app/tasks/copy`](#post-v1apptaskscopy)                                              | api\_php\_live\_v2 | Copy a task                                                                                                                                                                                    |
| POST   | [`/v1/app/tasks/data`](#post-v1apptasksdata)                                              | api\_php\_live\_v2 | Get tasks and their related rows by ID, for the mobile apps' local database                                                                                                                    |
| POST   | `/v1/app/tasks/follow`                                                                    | api\_php\_live\_v2 | Follow a task (no caller)                                                                                                                                                                      |
| POST   | [`/v1/app/tasks/follow/multi`](#post-v1apptasksfollowmulti)                               | api\_php\_live\_v2 | Add and remove several followers of a task                                                                                                                                                     |
| POST   | [`/v1/app/tasks/generate-url`](#post-v1apptasksgenerate-url)                              | api\_php\_live\_v2 | Create a share link for a task                                                                                                                                                                 |
| POST   | [`/v1/app/tasks/get-updates`](#post-v1apptasksget-updates)                                | api\_php\_live\_v2 | Get read and update flags for listed tasks                                                                                                                                                     |
| POST   | [`/v1/app/tasks/job-cost`](#post-v1apptasksjob-cost)                                      | api\_php\_live\_v2 | Add a cost to a task                                                                                                                                                                           |
| POST   | [`/v1/app/tasks/job-cost/multi`](#post-v1apptasksjob-costmulti)                           | api\_php\_live\_v2 | Add, change and delete a task's costs                                                                                                                                                          |
| PUT    | `/v1/app/tasks/job-cost/{uuid}`                                                           | api\_php\_live\_v2 | Change a cost entry (no caller)                                                                                                                                                                |
| DELETE | `/v1/app/tasks/job-cost/{uuid}`                                                           | api\_php\_live\_v2 | Delete a cost entry (no caller)                                                                                                                                                                |
| POST   | [`/v1/app/tasks/job-time`](#post-v1apptasksjob-time)                                      | api\_php\_live\_v2 | Add time to a task                                                                                                                                                                             |
| POST   | [`/v1/app/tasks/job-time/multi`](#post-v1apptasksjob-timemulti)                           | api\_php\_live\_v2 | Add, change and delete a task's time entries                                                                                                                                                   |
| PUT    | `/v1/app/tasks/job-time/{uuid}`                                                           | api\_php\_live\_v2 | Change a time entry (no caller)                                                                                                                                                                |
| DELETE | `/v1/app/tasks/job-time/{uuid}`                                                           | api\_php\_live\_v2 | Delete a time entry (no caller)                                                                                                                                                                |
| POST   | [`/v1/app/tasks/list`](#post-v1apptaskslist)                                              | api\_php\_live\_v2 | List a group's, room's or area's tasks                                                                                                                                                         |
| POST   | [`/v1/app/tasks/list-by-multiSite`](#post-v1apptaskslist-by-multisite)                    | api\_php\_live\_v2 | List a multi-site's tasks                                                                                                                                                                      |
| POST   | [`/v1/app/tasks/list-by-parent`](#post-v1apptaskslist-by-parent)                          | api\_php\_live\_v2 | List a site's tasks                                                                                                                                                                            |
| POST   | [`/v1/app/tasks/list-for-checklist`](#post-v1apptaskslist-for-checklist)                  | api\_php\_live\_v2 | List a site's tasks that can get a checklist                                                                                                                                                   |
| POST   | [`/v1/app/tasks/list-for-checklist/uuids`](#post-v1apptaskslist-for-checklistuuids)       | api\_php\_live\_v2 | List the IDs of a site's tasks that can get a checklist                                                                                                                                        |
| GET    | [`/v1/app/tasks/mark-as-read/{type}/{itemUuid}`](#get-v1apptasksmark-as-readtypeitemuuid) | api\_php\_live\_v2 | Mark all tasks of a group or room as read                                                                                                                                                      |
| POST   | [`/v1/app/tasks/move`](#post-v1apptasksmove)                                              | api\_php\_live\_v2 | Move a task to another group                                                                                                                                                                   |
| POST   | [`/v1/app/tasks/multi/archive`](#post-v1apptasksmultiarchive)                             | api\_php\_live\_v2 | Archive or unarchive several tasks                                                                                                                                                             |
| POST   | [`/v1/app/tasks/multi/delete`](#post-v1apptasksmultidelete)                               | api\_php\_live\_v2 | Delete several tasks                                                                                                                                                                           |
| POST   | [`/v1/app/tasks/multi/lock`](#post-v1apptasksmultilock)                                   | api\_php\_live\_v2 | Lock or unlock several tasks                                                                                                                                                                   |
| POST   | [`/v1/app/tasks/multi/move`](#post-v1apptasksmultimove)                                   | api\_php\_live\_v2 | Move several tasks to another group                                                                                                                                                            |
| POST   | [`/v1/app/tasks/multi/priority`](#post-v1apptasksmultipriority)                           | api\_php\_live\_v2 | Set the priority of several tasks                                                                                                                                                              |
| POST   | [`/v1/app/tasks/multi/status`](#post-v1apptasksmultistatus)                               | api\_php\_live\_v2 | Set the status of several tasks                                                                                                                                                                |
| POST   | `/v1/app/tasks/multi/tag`                                                                 | api\_php\_live\_v2 | Add tags to several tasks (`storeMultiple`) (no caller)                                                                                                                                        |
| POST   | [`/v1/app/tasks/notify-contractor`](#post-v1apptasksnotify-contractor)                    | api\_php\_live\_v2 | Email an assigned contractor a link to a task                                                                                                                                                  |
| DELETE | `/v1/app/tasks/reset-signature`                                                           | api\_php\_live\_v2 | Reset a task's signature; never runs, because `DELETE /v1/app/tasks/{uuid}` matches first (no caller)                                                                                          |
| POST   | [`/v1/app/tasks/room-add`](#post-v1apptasksroom-add)                                      | api\_php\_live\_v2 | Set a task's room                                                                                                                                                                              |
| POST   | [`/v1/app/tasks/room-remove`](#post-v1apptasksroom-remove)                                | api\_php\_live\_v2 | Remove a room from a task                                                                                                                                                                      |
| POST   | [`/v1/app/tasks/soft-freeze`](#post-v1apptaskssoft-freeze)                                | api\_php\_live\_v2 | Freeze or unfreeze tasks                                                                                                                                                                       |
| POST   | [`/v1/app/tasks/statuses`](#post-v1apptasksstatuses)                                      | api\_php\_live\_v2 | List a group's approval activity                                                                                                                                                               |
| POST   | [`/v1/app/tasks/statuses-by-parent`](#post-v1apptasksstatuses-by-parent)                  | api\_php\_live\_v2 | List a site's approval activity                                                                                                                                                                |
| POST   | `/v1/app/tasks/tag-add`                                                                   | api\_php\_live\_v2 | Add a tag to a task (no caller)                                                                                                                                                                |
| POST   | `/v1/app/tasks/tag-remove`                                                                | api\_php\_live\_v2 | Remove a tag from a task (no caller)                                                                                                                                                           |
| POST   | [`/v1/app/tasks/tag/multi`](#post-v1apptaskstagmulti)                                     | api\_php\_live\_v2 | Add and remove a task's tags (`multiTag`)                                                                                                                                                      |
| POST   | [`/v1/app/tasks/unassign`](#post-v1apptasksunassign)                                      | api\_php\_live\_v2 | Unassign a user from a task                                                                                                                                                                    |
| POST   | `/v1/app/tasks/unfollow`                                                                  | api\_php\_live\_v2 | Unfollow a task (no caller)                                                                                                                                                                    |
| GET    | [`/v1/app/tasks/{uuid}`](#get-v1apptasksuuid)                                             | api\_php\_live\_v2 | Get a task                                                                                                                                                                                     |
| PUT    | [`/v1/app/tasks/{uuid}`](#put-v1apptasksuuid)                                             | api\_php\_live\_v2 | Change one field of a task                                                                                                                                                                     |
| DELETE | [`/v1/app/tasks/{uuid}`](#delete-v1apptasksuuid)                                          | api\_php\_live\_v2 | Delete a task                                                                                                                                                                                  |
| POST   | [`/v1/app/tasks/{uuid}/due-date`](#post-v1apptasksuuiddue-date)                           | api\_php\_live\_v2 | Set a task's due date                                                                                                                                                                          |
| PUT    | [`/v1/app/tasks/{uuid}/due-date`](#put-v1apptasksuuiddue-date)                            | api\_php\_live\_v2 | Change a task's due date                                                                                                                                                                       |
| DELETE | [`/v1/app/tasks/{uuid}/due-date`](#delete-v1apptasksuuiddue-date)                         | api\_php\_live\_v2 | Remove a task's due date                                                                                                                                                                       |
| POST   | [`/v1/app/tasks/{uuid}/signature`](#post-v1apptasksuuidsignature)                         | api\_php\_live\_v2 | Sign off a task's checklist                                                                                                                                                                    |
| PUT    | [`/v1/app/tasks/{uuid}/signature`](#put-v1apptasksuuidsignature)                          | api\_php\_live\_v2 | Set whether a task's checklist needs a signature                                                                                                                                               |
| POST   | [`/v1/app/tasks/{uuid}/time-range`](#post-v1apptasksuuidtime-range)                       | api\_php\_live\_v2 | Set a task's time range                                                                                                                                                                        |
| PUT    | `/v1/app/tasks/{uuid}/time-range`                                                         | api\_php\_live\_v2 | Change a task's time range (no caller)                                                                                                                                                         |
| DELETE | [`/v1/app/tasks/{uuid}/time-range`](#delete-v1apptasksuuidtime-range)                     | api\_php\_live\_v2 | Remove a task's time range                                                                                                                                                                     |
| PUT    | [`/v1/app/tasks/{uuid}/todo-name`](#put-v1apptasksuuidtodo-name)                          | api\_php\_live\_v2 | Change a task's checklist name                                                                                                                                                                 |
| ANY    | `?action=copy_job_from_business`                                                          | php-apis           | Copy a task from a group (no caller)                                                                                                                                                           |
| POST   | [`?action=copy_job_v2`](#post-actioncopy_job_v2)                                          | php-apis           | Copy a task within its group or to another group of the same site                                                                                                                              |
| POST   | [`?action=copy_job_v2_multiselect`](#post-actioncopy_job_v2_multiselect)                  | php-apis           | Copy several tasks to a group, after answering                                                                                                                                                 |
| ANY    | `?action=create_pri_job`                                                                  | php-apis           | Create tasks, generic table action (no caller)                                                                                                                                                 |
| ANY    | `?action=create_pri_job_notif`                                                            | php-apis           | Create task notifications, generic table action (no caller)                                                                                                                                    |
| ANY    | `?action=create_pri_job_user`                                                             | php-apis           | Create task followers, generic table action (no caller)                                                                                                                                        |
| ANY    | `?action=delete_pri_job`                                                                  | php-apis           | Delete tasks, generic table action (no caller)                                                                                                                                                 |
| ANY    | `?action=delete_pri_job_notif`                                                            | php-apis           | Delete task notifications, generic table action (no caller)                                                                                                                                    |
| ANY    | `?action=delete_pri_job_user`                                                             | php-apis           | Delete task followers, generic table action (no caller)                                                                                                                                        |
| ANY    | `?action=email_task`                                                                      | php-apis           | Create a task from an email (no caller)                                                                                                                                                        |
| POST   | [`?action=generate_task_url`](#post-actiongenerate_task_url)                              | php-apis           | Create a share link for a task                                                                                                                                                                 |
| POST   | [`?action=guest_job_data`](#post-actionguest_job_data)                                    | php-apis           | Get a shared task's data, for apipy's `/g-job`                                                                                                                                                 |
| ANY    | `?action=jobs_v5`                                                                         | php-apis           | Empty handler: answers only `serverTs` (no caller; the apps' `jobs_v5` entry is apipy's `/v5`)                                                                                                 |
| ANY    | `?action=modify_pri_job`                                                                  | php-apis           | Change tasks, generic table action (no caller)                                                                                                                                                 |
| ANY    | `?action=modify_pri_job_notif`                                                            | php-apis           | Change task notifications, generic table action (no caller)                                                                                                                                    |
| ANY    | `?action=modify_pri_job_user`                                                             | php-apis           | Change task followers, generic table action (no caller)                                                                                                                                        |
| POST   | [`?action=move_job_v2`](#post-actionmove_job_v2)                                          | php-apis           | Move a task to another group of the same site                                                                                                                                                  |
| POST   | [`?action=move_job_v2_multiselect`](#post-actionmove_job_v2_multiselect)                  | php-apis           | Move several tasks to another group, after answering                                                                                                                                           |
| ANY    | `?action=read_all_job_data`                                                               | php-apis           | Read all task data (no caller)                                                                                                                                                                 |
| POST   | [`?action=read_area_jobs_new_updates`](#post-actionread_area_jobs_new_updates)            | php-apis           | Count tasks with new activity per area                                                                                                                                                         |
| POST   | [`?action=read_business_jobs_new_updates`](#post-actionread_business_jobs_new_updates)    | php-apis           | Count tasks with new activity per group; always 0                                                                                                                                              |
| POST   | [`?action=read_businessjob_data`](#post-actionread_businessjob_data)                      | php-apis           | Read all of a group's tasks, unpaged                                                                                                                                                           |
| POST   | [`?action=read_businessjob_data_v2`](#post-actionread_businessjob_data_v2)                | php-apis           | Read a group's tasks, paged                                                                                                                                                                    |
| POST   | [`?action=read_businessjob_data_v2_proxy`](#post-actionread_businessjob_data_v2_proxy)    | php-apis           | Read a group's tasks, paged, for apipy's `/v5`                                                                                                                                                 |
| POST   | [`?action=read_data`](#post-actionread_data)                                              | php-apis           | Read the user's data, table by table (`readAllData`)                                                                                                                                           |
| POST   | [`?action=read_data_v2`](#post-actionread_data_v2)                                        | php-apis           | Read the user's data in chosen sites, table by table (v2)                                                                                                                                      |
| POST   | [`?action=read_data_v3`](#post-actionread_data_v3)                                        | php-apis           | Read the user's data in chosen sites, with limits and filters (v3)                                                                                                                             |
| ANY    | `?action=read_job_data`                                                                   | php-apis           | Read task rows (`readJobTableData`) (no caller)                                                                                                                                                |
| POST   | [`?action=read_jobs_last_viewed`](#post-actionread_jobs_last_viewed)                      | php-apis           | List who viewed a task, and when                                                                                                                                                               |
| POST   | [`?action=read_jobs_read_status`](#post-actionread_jobs_read_status)                      | php-apis           | Get the user's read status of tasks                                                                                                                                                            |
| ANY    | `?action=read_parent_data`                                                                | php-apis           | Read a user's master data (`readDataMaster`) (no caller; apipy's `/read-parent-data` would forward here, but fails first)                                                                      |
| POST   | [`?action=read_parent_data_v2`](#post-actionread_parent_data_v2)                          | php-apis           | Read the user's sites and site settings (v2)                                                                                                                                                   |
| POST   | [`?action=read_parent_jobs_new_updates`](#post-actionread_parent_jobs_new_updates)        | php-apis           | Count tasks with new activity per site                                                                                                                                                         |
| ANY    | `?action=read_pri_job`                                                                    | php-apis           | Read tasks by UUID, generic table action (no caller)                                                                                                                                           |
| ANY    | `?action=read_pri_job_asset`                                                              | php-apis           | Read task assets by UUID, generic table action (no caller)                                                                                                                                     |
| ANY    | `?action=read_pri_job_notif`                                                              | php-apis           | Read task notifications by UUID, generic table action (no caller)                                                                                                                              |
| ANY    | `?action=read_pri_job_user`                                                               | php-apis           | Read task followers by UUID, generic table action (no caller)                                                                                                                                  |
| ANY    | `?action=read_queue`                                                                      | php-apis           | Read the queue log (no caller)                                                                                                                                                                 |
| POST   | [`?action=read_room_jobs_new_updates`](#post-actionread_room_jobs_new_updates)            | php-apis           | Count tasks with new activity per room                                                                                                                                                         |
| POST   | [`?action=save_job_status_log`](#post-actionsave_job_status_log)                          | php-apis           | Save task status changes                                                                                                                                                                       |
| POST   | [`?action=save_pri_job`](#post-actionsave_pri_job)                                        | php-apis           | Save tasks                                                                                                                                                                                     |
| POST   | [`?action=save_pri_job_area`](#post-actionsave_pri_job_area)                              | php-apis           | Save task areas                                                                                                                                                                                |
| ANY    | [`?action=save_pri_job_asset`](#any-actionsave_pri_job_asset)                             | php-apis           | Save task assets (no caller)                                                                                                                                                                   |
| POST   | [`?action=save_pri_job_notif`](#post-actionsave_pri_job_notif)                            | php-apis           | Save task notifications                                                                                                                                                                        |
| POST   | [`?action=save_pri_job_room`](#post-actionsave_pri_job_room)                              | php-apis           | Save task rooms                                                                                                                                                                                |
| POST   | [`?action=save_pri_job_timecost`](#post-actionsave_pri_job_timecost)                      | php-apis           | Save task time and cost entries                                                                                                                                                                |
| POST   | [`?action=save_pri_job_user`](#post-actionsave_pri_job_user)                              | php-apis           | Save task followers                                                                                                                                                                            |
| POST   | [`?action=save_pri_job_userassigned`](#post-actionsave_pri_job_userassigned)              | php-apis           | Save task assignees                                                                                                                                                                            |
| POST   | [`?action=save_pri_jobjoblink`](#post-actionsave_pri_jobjoblink)                          | php-apis           | Save task links                                                                                                                                                                                |
| POST   | [`?action=save_pri_log_businessvieweduser`](#post-actionsave_pri_log_businessvieweduser)  | php-apis           | Log that a user viewed a group                                                                                                                                                                 |
| POST   | [`?action=save_pri_log_jobvieweduser`](#post-actionsave_pri_log_jobvieweduser)            | php-apis           | Log that a user viewed a task                                                                                                                                                                  |
| ANY    | `?action=save_queue`                                                                      | php-apis           | Save a batch of queue log entries (no caller)                                                                                                                                                  |
| ANY    | `?action=validate_job_images`                                                             | php-apis           | Disabled: always answers with a fixed error (no caller)                                                                                                                                        |
| ANY    | `?action=webcust_job_pagination_modifiedts_desc`                                          | php-apis           | List tasks by change time, newest first (`webCustReadJob`) (no caller)                                                                                                                         |
| ANY    | `?action=webcust_read_all_job_data`                                                       | php-apis           | Read all task data (no caller)                                                                                                                                                                 |
| ANY    | `?action=taskbulkassign`                                                                  | php-apis web       | Assign tasks in bulk (no caller)                                                                                                                                                               |
| ANY    | `?action=taskbulkcreate`                                                                  | php-apis web       | Not built: always answers 501 (no caller)                                                                                                                                                      |
| ANY    | `?action=taskcount`                                                                       | php-apis web       | Count tasks (no caller)                                                                                                                                                                        |
| ANY    | `?action=taskjobcancel`                                                                   | php-apis web       | Not built: always answers 501 (bulk job cancel) (no caller)                                                                                                                                    |
| ANY    | `?action=taskjobstatus`                                                                   | php-apis web       | Not built: always answers 501 (bulk job status) (no caller)                                                                                                                                    |
| ANY    | `?action=taskperformance`                                                                 | php-apis web       | Aggregate task performance (no caller)                                                                                                                                                         |
| ANY    | `?action=tasksearch`                                                                      | php-apis web       | Search tasks (no caller)                                                                                                                                                                       |
| ANY    | `?action=tasksummary`                                                                     | php-apis web       | Aggregate task summary (no caller)                                                                                                                                                             |
| ANY    | `?action=taskworkload`                                                                    | php-apis web       | Aggregate task workload (no caller)                                                                                                                                                            |
| ANY    | `?action=webcust_copy_job`                                                                | php-apis web       | Copy a task (no caller)                                                                                                                                                                        |
| ANY    | `?action=webcust_create_job`                                                              | php-apis web       | Create a task (no caller)                                                                                                                                                                      |
| ANY    | `?action=webcust_create_job_cost`                                                         | php-apis web       | Add a cost to a task (no caller)                                                                                                                                                               |
| ANY    | `?action=webcust_create_job_time`                                                         | php-apis web       | Add time to a task (no caller)                                                                                                                                                                 |
| ANY    | `?action=webcust_create_jobnotif`                                                         | php-apis web       | Create a task notification (no caller)                                                                                                                                                         |
| ANY    | `?action=webcust_delete_job`                                                              | php-apis web       | Delete a task (`updateJob`) (no caller)                                                                                                                                                        |
| ANY    | `?action=webcust_delete_job_cost`                                                         | php-apis web       | Delete a task cost (no caller)                                                                                                                                                                 |
| ANY    | `?action=webcust_delete_job_time`                                                         | php-apis web       | Delete a task time entry (no caller)                                                                                                                                                           |
| ANY    | `?action=webcust_job_archive`                                                             | php-apis web       | Archive a task (no caller)                                                                                                                                                                     |
| ANY    | `?action=webcust_job_assignuser`                                                          | php-apis web       | Assign a user to a task (no caller)                                                                                                                                                            |
| ANY    | `?action=webcust_job_details`                                                             | php-apis web       | Get a task's details (no caller)                                                                                                                                                               |
| ANY    | `?action=webcust_job_details_v2`                                                          | php-apis web       | Get a task's details (v2) (no caller)                                                                                                                                                          |
| ANY    | `?action=webcust_job_lock`                                                                | php-apis web       | Lock a task (no caller)                                                                                                                                                                        |
| ANY    | `?action=webcust_job_timerange_reset`                                                     | php-apis web       | Reset a task's time range (no caller)                                                                                                                                                          |
| ANY    | `?action=webcust_job_timerange_set`                                                       | php-apis web       | Set a task's time range (no caller)                                                                                                                                                            |
| ANY    | `?action=webcust_job_timerange_update`                                                    | php-apis web       | Change a task's time range (no caller)                                                                                                                                                         |
| ANY    | `?action=webcust_job_unarchive`                                                           | php-apis web       | Unarchive a task (no caller)                                                                                                                                                                   |
| ANY    | `?action=webcust_job_unassignuser`                                                        | php-apis web       | Unassign a user from a task (no caller)                                                                                                                                                        |
| ANY    | `?action=webcust_job_unlock`                                                              | php-apis web       | Unlock a task (no caller)                                                                                                                                                                      |
| ANY    | `?action=webcust_joblink_save`                                                            | php-apis web       | Save a task link (no caller)                                                                                                                                                                   |
| POST   | [`?action=webcust_list_jobs`](#post-actionwebcust_list_jobs)                              | php-apis web       | List a group's tasks as a given user                                                                                                                                                           |
| ANY    | `?action=webcust_mark_alljob_read`                                                        | php-apis web       | Mark all tasks as read (no caller)                                                                                                                                                             |
| ANY    | `?action=webcust_remove_flag`                                                             | php-apis web       | Remove a task's flag (no caller)                                                                                                                                                               |
| ANY    | `?action=webcust_remove_priority`                                                         | php-apis web       | Remove a task's priority (no caller)                                                                                                                                                           |
| POST   | [`?action=webcust_reset_job_signature`](#post-actionwebcust_reset_job_signature)          | php-apis web       | Meant to reset a task's signature; only returns the task's details \[[ASK-17](https://github.com/snapfix/docs/blob/main/ASK.md#ask-17-should-reset-signature-on-the-web-remove-the-signature)] |
| ANY    | `?action=webcust_save_businessviewed`                                                     | php-apis web       | Log that a user viewed a group (no caller)                                                                                                                                                     |
| ANY    | `?action=webcust_save_jobviewed`                                                          | php-apis web       | Log that a user viewed a task (no caller)                                                                                                                                                      |
| ANY    | `?action=webcust_select_user`                                                             | php-apis web       | Add a follower to a task (`selectUser`) (no caller)                                                                                                                                            |
| ANY    | `?action=webcust_set_flag`                                                                | php-apis web       | Flag a task (no caller)                                                                                                                                                                        |
| ANY    | `?action=webcust_set_priority`                                                            | php-apis web       | Set a task's priority (no caller)                                                                                                                                                              |
| ANY    | `?action=webcust_unselect_user`                                                           | php-apis web       | Remove a follower from a task (`unselectUser`) (no caller)                                                                                                                                     |
| ANY    | `?action=webcust_update_job`                                                              | php-apis web       | Change a task (no caller)                                                                                                                                                                      |
| ANY    | `?action=webcust_update_job_cost`                                                         | php-apis web       | Change a task cost (no caller)                                                                                                                                                                 |
| ANY    | `?action=webcust_update_job_description`                                                  | php-apis web       | Change a task's description (no caller)                                                                                                                                                        |
| ANY    | `?action=webcust_update_job_image`                                                        | php-apis web       | Change a task's image (no caller)                                                                                                                                                              |
| ANY    | `?action=webcust_update_job_largetext`                                                    | php-apis web       | Change a task's large text (no caller)                                                                                                                                                         |
| ANY    | `?action=webcust_update_job_location`                                                     | php-apis web       | Change a task's location (no caller)                                                                                                                                                           |
| ANY    | `?action=webcust_update_job_reminder`                                                     | php-apis web       | Change a task's reminder status (no caller)                                                                                                                                                    |
| ANY    | `?action=webcust_update_job_signature`                                                    | php-apis web       | Save a task's signature as a chat message (no caller)                                                                                                                                          |
| ANY    | `?action=webcust_update_job_signature_required`                                           | php-apis web       | Set whether a task needs a signature (no caller)                                                                                                                                               |
| ANY    | `?action=webcust_update_job_status`                                                       | php-apis web       | Change a task's status (no caller)                                                                                                                                                             |
| ANY    | `?action=webcust_update_job_time`                                                         | php-apis web       | Change a task's time (no caller)                                                                                                                                                               |
| ANY    | `?action=webcust_update_job_title`                                                        | php-apis web       | Change a task's title (no caller)                                                                                                                                                              |
| POST   | `/dev/v4/{user_uuid}/jobs`                                                                | apipy              | List a user's tasks, development version (no caller)                                                                                                                                           |
| GET    | [`/g-job/{jobToken}`](#get-g-jobjobtoken)                                                 | apipy              | Get a shared task for the shared task page                                                                                                                                                     |
| GET    | [`/job-reminder/{job_uuid}`](#get-job-reminderjob_uuid)                                   | apipy              | Get a task's reminder settings                                                                                                                                                                 |
| POST   | [`/job-reminder/{job_uuid}`](#post-job-reminderjob_uuid)                                  | apipy              | Save a task's reminder settings                                                                                                                                                                |
| DELETE | [`/job-reminder/{job_uuid}`](#delete-job-reminderjob_uuid)                                | apipy              | Delete a task's reminder settings                                                                                                                                                              |
| POST   | [`/job-reminders`](#post-job-reminders)                                                   | apipy              | Save reminder settings for several tasks, after answering                                                                                                                                      |
| POST   | `/v4/job`                                                                                 | apipy              | Create a task (no caller)                                                                                                                                                                      |
| GET    | [`/v4/{user_uuid}/job/{job_uuid}`](#get-v4user_uuidjobjob_uuid)                           | apipy              | Get a task                                                                                                                                                                                     |
| POST   | `/v4/{user_uuid}/jobs`                                                                    | apipy              | List a user's tasks (v4) (no caller)                                                                                                                                                           |
| POST   | [`/v5/{user_uuid}/jobs`](#post-v5user_uuidjobs)                                           | apipy              | List the tasks of the groups named in the request (v5)                                                                                                                                         |

## POST /v1/app/tasks

Creates a task in a group, with a photo or a large text, and optionally a voice note or a linked asset.

* **Auth:** user token; group admins, or members with the "create task" permission (`perJobCreateNew`) who aren't read-only ([task permissions](#task-permissions)).
* **Used by:** web, Android (housekeeping "create task"), Simon

**Request** (form data; `multipart/form-data` when there is a file)

| Name                                        | In   | Type         | Required             | Rules                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| ------------------------------------------- | ---- | ------------ | -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `businessUuid`                              | body | string       | yes                  | The group                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| `title`                                     | body | string       | yes                  | At most 255 characters                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| `largeTitle`                                | body | string       | without `file`       | Large text shown in place of a photo; ignored when `imageValueAi` is set                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| `file`                                      | body | file         | without `largeTitle` | jpg, jpeg, png or gif, up to `FILE_MAX_SIZE` KB (default 102400)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| `description`                               | body | string       | no                   |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| `jobType`                                   | body | integer      | no                   | A task type from `JobType`, such as 5 normal (default), 45 cleaning, 46 inspection                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| `priorityLevel`                             | body | integer      | no                   | 0, 1, 5, 10, 20 or 30; 1 is stored as 20                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| `assetUuid`                                 | body | string       | no                   | Links this asset and copies its checklist, checklist name and signature setting; ignored when the asset is missing or in another site                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| `chatId`, `messageId`                       | body | string       | together             | The chat message the task is made from; the audit line names it                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| `voiceFileUrl`, `voiceDuration`             | body | URL, `HH:MM` | together             | Makes a voice task (type 41) and posts the voice note in its chat                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| `titleValueAi`                              | body | string       | no                   | AI-made title; replaces `title`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| `imageValueAi`                              | body | string       | no                   | AI-made image URL; becomes the photo. Any string is accepted                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| `transcriptValueAi`                         | body | string       | no                   | Voice note transcript                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| `aiTitle`, `aiBusinessUuid`                 | body | string       | no                   | The title and group the AI suggested, for the AI log                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| `aiTitleSuggestion`, `aiBusinessSuggestion` | body | integer      | no                   | 0 or 1: the title or group came from the AI                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| `cleaningType`                              | body | string       | no                   | stayover, departure, correction or standard; only with `jobType` 45                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| `cleaningSubType`                           | body | string       | no                   | deep\_clean, request\_clean, floor\_deep\_cleaning, touch\_up\_5\_min, touch\_up\_10\_min, deep\_clean\_pet\_room, studio\_tidy, trash\_and\_towel or pre\_arrival\_blitz; only with `jobType` 45 and `cleaningType` standard                                                                                                                                                                                                                                                                                                                                                                     |
| `jobDuration`                               | body | integer      | no                   | Minutes, at least 1; only with `jobType` 45 or 46. Android's `HousekeepingTasksRepository.createTask` would send seconds, but nothing calls it: the create sheet sends seconds as `cleanDuration` to [`POST /v1/app/housekeeping/manual-hk-task/bulk`](https://docs.snapfix.com/engineering-reference/api/housekeeping.md#post-v1apphousekeepingmanual-hk-taskbulk) instead (android @ 86068bfeea, `app/src/main/java/gmail/com/snapfixapp/repository/HousekeepingTasksRepository.kt:458-516`, `app/src/main/java/gmail/com/snapfixapp/bottomSheet/CreateHousekeepingTaskBottomSheet.kt:804-809`) |

The new task is red (To Do), unlocked, unarchived, with no approval status. Its time range length comes from `jobDuration`; without it, a cleaning task gets 5 or 10 minutes for the two touch-up sub types and 30 otherwise, and an inspection 5 minutes. The task's origin comes from the `fOrigin` header.

**Response** `200` (trimmed)

```json
{
  "status": "success",
  "message": "Operation was successful",
  "data": {
    "job": {
      "uuid": "123",
      "title": "Leaking tap",
      "largeTitle": "Leaking tap in Room 101",
      "image": null,
      "enumType": 5,
      "priorityLevel": 20,
      "reference": "38760012",
      "createdTs": 1794387600000,
      "business": { "uuid": "200", "name": "Maintenance", "image": null },
      "status": { "uuid": "201", "name": "red" },
      "subStatus": { "uuid": "202", "name": "New" }
    },
    "jobchat": { "uuid": "400", "text": "<b>Jane Smith</b> created Task", "type": 6 }
  }
}
```

`job` is a [task object](#task-object) with `business`, `status`, `subStatus` and `users`; `jobchat` is the audit line ([chat item object](#chat-item-object)).

**Errors:** [common errors](#common-errors); `403` without the permission; `404` unknown group.

**Side effects:**

* Adds the task to [`tPri_Job`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_job.md), its first status row to [`tPri_Job_StatusLog`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_job_statuslog.md), and the creator as a follower in [`tPri_JobUser`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_jobuser.md).
* Uploads the photo to file storage.
* Adds the "created" audit line, a voice note line for voice tasks, and for `assetUuid` an asset link in [`tPri_JobJobLink`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_jobjoblink.md), an "added" line and a copy of the asset's checklist in [`tPri_JobTodo`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_jobtodo.md).
* Viewed rows, pushes and the Firebase task counter as in [common side effects](#common-side-effects): a silent update and a "created" push to the group, plus a voice note push for voice tasks.
* When the site has AI suggestions on, rows in [`log_ai_job`](https://docs.snapfix.com/engineering-reference/db/tables/log_ai_job.md) for the AI title and group.

## POST /v1/app/tasks/all/archive

Archives or unarchives every task of one status in a group that the caller can see and that matches the filters.

* **Auth:** user token; group admins, or members with the "archive task" permission (`perJobArchive`) who aren't read-only.
* **Used by:** web (task list multi-select, when the selection covers more tasks than are loaded)

**Request**

| Name           | In   | Type   | Required | Rules                                                                |
| -------------- | ---- | ------ | -------- | -------------------------------------------------------------------- |
| `businessUuid` | body | string | yes      | The group                                                            |
| `color`        | body | string | yes      | red, amber or green: the status whose tasks change                   |
| `value`        | body | string | yes      | "1" archives, "0" unarchives                                         |
| filters        | body |        | no       | [Task list filters](#task-list-filters) of `POST /v1/app/tasks/list` |

Tasks already in that state, locked tasks, and tasks outside their time range (housekeeping tasks excepted) are skipped. Archiving a cleaning task also archives its linked inspection task.

**Response** `200`

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

`total` counts the tasks that changed, linked inspection tasks included.

**Errors:** [common errors](#common-errors); `403` "Access denied" without the permission; `403` "Jobs not found" when no task matches; `404` unknown group.

**Side effects:** sets `fArchived`, `fArchivedTs` and `uuid_tUser_ArchivedBy` in [`tPri_Job`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_job.md) task by task, and unarchiving also clears the snooze; an audit line and viewed rows per task; a silent update push to the group \[[ASK-12](https://github.com/snapfix/docs/blob/main/ASK.md#ask-12-which-settings-do-the-production-api-servers-use)].

## POST /v1/app/tasks/all/delete

Deletes every task of one status in a group that the caller can see and that matches the filters.

* **Auth:** user token; group admins, or members with the "delete task" permission (`perJobDelete`) who aren't read-only.
* **Used by:** web (task list multi-select)

**Request**

| Name           | In   | Type   | Required | Rules                                                                |
| -------------- | ---- | ------ | -------- | -------------------------------------------------------------------- |
| `businessUuid` | body | string | yes      | The group                                                            |
| `color`        | body | string | yes      | red, amber or green                                                  |
| `value`        | body | string | yes      | Any value; the web sends "1"                                         |
| filters        | body |        | no       | [Task list filters](#task-list-filters) of `POST /v1/app/tasks/list` |

**Response** `200`: `data` is `{ "total": 12 }`, the tasks deleted, linked inspection tasks of cleaning tasks included.

**Errors:** [common errors](#common-errors); `403` "Access denied" without the permission; `403` "Jobs not found" when no task matches.

**Side effects:** soft-deletes the tasks in [`tPri_Job`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_job.md) one at a time, with no audit line; a silent update push to the group \[[ASK-12](https://github.com/snapfix/docs/blob/main/ASK.md#ask-12-which-settings-do-the-production-api-servers-use)]; the Firebase task counter doesn't change.

## POST /v1/app/tasks/all/lock

Locks or unlocks every task of one status in a group that the caller can see and that matches the filters.

* **Auth:** user token; no group permission is checked. Each task changes only when the caller is a group admin or the task's creator.
* **Used by:** web (task list multi-select)

**Request**

| Name           | In   | Type   | Required | Rules                                                                |
| -------------- | ---- | ------ | -------- | -------------------------------------------------------------------- |
| `businessUuid` | body | string | yes      | The group                                                            |
| `color`        | body | string | yes      | red, amber or green                                                  |
| `value`        | body | string | yes      | "1" locks, "0" unlocks                                               |
| filters        | body |        | no       | [Task list filters](#task-list-filters) of `POST /v1/app/tasks/list` |

Archived tasks and tasks outside their time range are skipped.

**Response** `200`: `data` is `{ "total": 12 }`, the tasks that changed.

**Errors:** [common errors](#common-errors); `403` "Jobs not found" when no task matches.

**Side effects:** sets `fLocked` in [`tPri_Job`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_job.md) task by task, with an audit line and viewed rows each; a silent update push to the group \[[ASK-12](https://github.com/snapfix/docs/blob/main/ASK.md#ask-12-which-settings-do-the-production-api-servers-use)].

## POST /v1/app/tasks/all/move

Queues a move of every task of one status in a group that the caller can see and that matches the filters, to another group of the same site.

* **Auth:** user token; members of both groups; no role or permission is checked.
* **Used by:** web (task list multi-select "Move")

**Request**

| Name                 | In   | Type    | Required | Rules                                                                |
| -------------------- | ---- | ------- | -------- | -------------------------------------------------------------------- |
| `businessUuid`       | body | string  | yes      | The source group                                                     |
| `targetBusinessUuid` | body | string  | yes      | Another group of the same site                                       |
| `color`              | body | string  | yes      | red, amber or green                                                  |
| `copyJobChat`        | body | integer | no       | 0 or 1, default 1: keep the chat                                     |
| `createTags`         | body | integer | no       | 0 or 1, default 0: add the tag folders and tags the target lacks     |
| `createUserBusiness` | body | integer | no       | 0 or 1, default 0: add the users the target lacks                    |
| filters              | body |         | no       | [Task list filters](#task-list-filters) of `POST /v1/app/tasks/list` |

**Response** `200`

```json
{ "status": "success", "message": "Tasks are being moved to the selected group", "data": null }
```

**Errors:** [common errors](#common-errors); `403` "Access denied" when the caller isn't in both groups; `400` "Source and Target businesses belongs to different accounts"; `403` "Jobs not found" when no task matches; `422` when both groups are the same.

**Side effects:** as [`POST /v1/app/tasks/multi/move`](#post-v1apptasksmultimove).

## POST /v1/app/tasks/all/priority

Sets the priority of every task of one status in a group that the caller can see and that matches the filters.

* **Auth:** user token; members of the group, read-only members included; no permission is checked.
* **Used by:** web (task list multi-select)

**Request**

| Name           | In   | Type   | Required | Rules                                                                |
| -------------- | ---- | ------ | -------- | -------------------------------------------------------------------- |
| `businessUuid` | body | string | yes      | The group                                                            |
| `color`        | body | string | yes      | red, amber or green                                                  |
| `value`        | body | string | yes      | 0, 1, 5, 10, 20 or 30                                                |
| filters        | body |        | no       | [Task list filters](#task-list-filters) of `POST /v1/app/tasks/list` |

A non-zero `value` changes only tasks without priority, and 0 only tasks with priority, so tasks that already have a priority keep their level. Archived and locked tasks, and tasks outside their time range, are skipped.

**Response** `200`: `data` is `{ "total": 12 }`, the tasks that changed.

**Errors:** [common errors](#common-errors); `403` "Jobs not found" when no task matches; `422` for another `value`.

**Side effects:** sets `fPriority` and `fPriorityLevel` in [`tPri_Job`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_job.md) task by task, and on the linked inspection task of a cleaning task; a "set priority" or "removed priority" audit line and viewed rows per task; a silent update push to the group \[[ASK-12](https://github.com/snapfix/docs/blob/main/ASK.md#ask-12-which-settings-do-the-production-api-servers-use)].

## POST /v1/app/tasks/all/status

Moves every task of one status in a group that the caller can see and that matches the filters to another status.

* **Auth:** user token; group admins, or members with the permission to move tasks to the new status (`perJobMoveToRed`, `perJobMoveToAmber` or `perJobMoveToGreen`) who aren't read-only.
* **Used by:** web (task list multi-select)

**Request**

| Name           | In   | Type   | Required | Rules                                                                |
| -------------- | ---- | ------ | -------- | -------------------------------------------------------------------- |
| `businessUuid` | body | string | yes      | The group                                                            |
| `color`        | body | string | yes      | red, amber or green: the current status                              |
| `value`        | body | string | yes      | red, amber or green: the new status                                  |
| filters        | body |        | no       | [Task list filters](#task-list-filters) of `POST /v1/app/tasks/list` |

Archived and locked tasks, and tasks outside their time range (housekeeping tasks excepted), are skipped. When the group blocks green until checklists are done (`fBlockGreenWhenChecklistNotComplete`), tasks with unfinished checklists stay. Moving to green a task that needs approval (the task's `fApprovalRequired`, or the group's `fTaskApprovalRequired` when the task says -1) approves it when the caller is a group admin, and otherwise sends it for approval (approval status 2). Moving away from red clears the snooze. Unlike [`PUT /v1/app/tasks/{uuid}`](#put-v1apptasksuuid), it doesn't update room status for housekeeping tasks and doesn't notify admins of approval requests.

**Response** `200`: `data` is `{ "total": 12 }`, the tasks that changed.

**Errors:** [common errors](#common-errors); `403` "Access denied" without the permission; `403` "Jobs not found" when no task matches.

**Side effects:** updates `color`, `uuid_tStatus`, the status time and user, `search_text` and `fApprovalStatus` in [`tPri_Job`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_job.md) task by task; adds rows to [`tPri_Job_StatusLog`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_job_statuslog.md) and audit lines ("changed Status", "approved", "sent for approval") in one batch; viewed rows per task; deletes due date reminders in [`schedule_v3`](https://docs.snapfix.com/engineering-reference/db/tables/schedule_v3.md) for tasks moved to green; a silent update push to the group \[[ASK-12](https://github.com/snapfix/docs/blob/main/ASK.md#ask-12-which-settings-do-the-production-api-servers-use)].

## POST /v1/app/tasks/area-add

Sets a task's area: removes the areas it has and adds the first valid area of the list.

* **Auth:** user token; members of the task's group, any role, read-only members included.
* **Used by:** web, Simon

**Request**

| Name          | In   | Type             | Required | Rules                                                                             |
| ------------- | ---- | ---------------- | -------- | --------------------------------------------------------------------------------- |
| `jobUuid`     | body | string           | yes      | The task; it must be editable ([task permissions](#task-permissions))             |
| `areaUuids`   | body | array of strings | yes      | Only the first area in the task's site is added; areas of other sites are skipped |
| `aiSuggested` | body | integer          | no       | 0 or 1, default 0                                                                 |

The task's current areas go without a "Removed" audit line, also when no area of the list is added, and an unknown area ID fails with `404` after they are gone.

**Response** `200`

```json
{
  "status": "success",
  "message": "Operation was successful",
  "data": {
    "jobAreas": [{ "uuid": "600", "name": "Lobby", "date": "2026-11-11T09:00:00.000000Z" }],
    "jobchats": [{ "uuid": "401", "text": "Added : Lobby", "type": 84 }]
  }
}
```

**Errors:** [common errors](#common-errors); `403` when the caller isn't in the task's group; `400` "The task can not be updated"; `404` unknown task or area.

**Side effects:** replaces the task's rows in [`tPri_JobArea`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_jobarea.md); an "Added" audit line and a push to the task's people; viewed rows and a touch of the task; an AI log row in [`log_ai_job`](https://docs.snapfix.com/engineering-reference/db/tables/log_ai_job.md) when the site has AI suggestions on and the old or new area came from the AI.

## POST /v1/app/tasks/area-remove

Removes one area from a task.

* **Auth:** user token; members of the task's group, any role.
* **Used by:** web, Simon

**Request**

| Name       | In   | Type   | Required | Rules                         |
| ---------- | ---- | ------ | -------- | ----------------------------- |
| `jobUuid`  | body | string | yes      | The task; it must be editable |
| `areaUuid` | body | string | yes      | An area the task has          |

**Response** `200`: `data` is `{ "jobchat": { ... } }`, the "Removed : Lobby" audit line ([chat item object](#chat-item-object)).

**Errors:** [common errors](#common-errors); `404` when the task doesn't have that area; `403` when the caller isn't in the task's group; `400` "The task can not be updated".

**Side effects:** deletes the row in [`tPri_JobArea`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_jobarea.md); an audit line and a push to the task's people; viewed rows; an AI log row when the area came from the AI.

## POST /v1/app/tasks/asset-link

Links assets to a task.

* **Auth:** user token only: no membership or permission check, for the task or the assets.
* **Used by:** web, Simon

**Request**

| Name         | In   | Type             | Required | Rules                                    |
| ------------ | ---- | ---------------- | -------- | ---------------------------------------- |
| `jobUuid`    | body | string           | yes      | The task; it must be editable            |
| `assetUuids` | body | array of strings | yes      | Assets of any group or site are accepted |

**Response** `200` (trimmed)

```json
{
  "status": "success",
  "message": "Operation was successful",
  "data": {
    "assets": [{ "uuid": "700", "title": "Boiler 2", "status": { "uuid": "701", "name": "green" }, "assetRegister": { "uuid": "702", "name": "Plant room", "image": null } }],
    "jobchats": [{ "uuid": "402", "text": "added : Boiler 2", "type": 59, "assetUuid": "700", "assetRegUuid": "702", "taskLinkUuid": "703" }]
  }
}
```

`assets` lists every asset now linked to the task, as [task objects](#task-object) with `status` and `assetRegister`; `jobchats` has a line per new link.

**Errors:** [common errors](#common-errors); `404` unknown task or asset; `400` "The task can not be updated".

**Side effects:** adds rows to [`tPri_JobJobLink`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_jobjoblink.md) (an asset already linked stays as it is); an "added" audit line and a push to the task's people per new link; a silent update push \[[ASK-12](https://github.com/snapfix/docs/blob/main/ASK.md#ask-12-which-settings-do-the-production-api-servers-use)]; viewed rows and a touch of the task.

## POST /v1/app/tasks/asset-unlink

Unlinks assets from a task.

* **Auth:** user token only: no membership or permission check.
* **Used by:** web, Simon

**Request**

| Name         | In   | Type             | Required | Rules                         |
| ------------ | ---- | ---------------- | -------- | ----------------------------- |
| `jobUuid`    | body | string           | yes      | The task; it must be editable |
| `assetUuids` | body | array of strings | yes      | Assets linked to the task     |

**Response** `200`: like [`POST /v1/app/tasks/asset-link`](#post-v1apptasksasset-link), with the assets still linked and a "removed" line per asset.

**Errors:** [common errors](#common-errors); `404` when an asset isn't linked, after the assets before it in the list were already unlinked; `400` "The task can not be updated".

**Side effects:** deletes rows in [`tPri_JobJobLink`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_jobjoblink.md); a "removed" audit line and a push per asset; viewed rows and a touch of the task.

## POST /v1/app/tasks/assign

Assigns one user to a task.

* **Auth:** user token; group admins, or members with the "assign user" permission (`perAssignUser`) who aren't read-only.
* **Used by:** Simon

**Request**

| Name       | In   | Type   | Required | Rules                                                                                                        |
| ---------- | ---- | ------ | -------- | ------------------------------------------------------------------------------------------------------------ |
| `jobUuid`  | body | string | yes      | The task; it must be editable, but inspection tasks can be assigned while locked or outside their time range |
| `userUuid` | body | string | yes      | A member of the task's group who isn't assigned yet                                                          |

**Response** `200` (trimmed)

```json
{
  "status": "success",
  "message": "User assigned successfully",
  "data": {
    "user": { "uuid": "300", "username": "jane@example.com", "name": "Jane Smith", "mobile": "5550100" },
    "jobchat": { "uuid": "403", "text": "<b>Sam Lee</b> assigned <b>Jane Smith</b>", "type": 44 },
    "assignJobUserUuid": "800"
  }
}
```

`user` is a [user object](#user-object).

**Errors:** [common errors](#common-errors); `422` "User has been assigned already"; `400` "User not found in the current group"; `403` without the permission; `400` "The task can not be updated"; `404` unknown task or user.

**Side effects:** adds a row to [`tPri_JobUserAssigned`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_jobuserassigned.md); an "assigned" audit line; a push to the assignee and the task's people and a silent assignment update push; viewed rows and a touch of the task.

## POST /v1/app/tasks/assign/multi

Assigns and unassigns several users on one task.

* **Auth:** user token; group admins, or members with the "assign user" permission who aren't read-only.
* **Used by:** web

**Request**

| Name              | In   | Type             | Required | Rules                                                                                                                                                          |
| ----------------- | ---- | ---------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `jobUuid`         | body | string           | yes      | The task; it must be editable, with the inspection task exception of [`POST /v1/app/tasks/assign`](#post-v1apptasksassign)                                     |
| `addUserUuids`    | body | array of strings | no       | Users to assign; users who aren't active members of the group are left out                                                                                     |
| `removeUserUuids` | body | array of strings | no       | Users to unassign; housekeeping tasks follow their own unassign rules ([Housekeeping API](https://docs.snapfix.com/engineering-reference/api/housekeeping.md)) |
| `aiSuggested`     | body | integer          | no       | 0 or 1, default 0: the added users came from the AI                                                                                                            |

**Response** `200`: `data` is `{ "users": [...], "jobchats": [...] }`: every user now assigned, as [user objects](#user-object), and an audit line per change.

**Errors:** [common errors](#common-errors); `403` without the permission; `400` "The task can not be updated"; `404` unknown task.

**Side effects:** adds, restores or deletes rows in [`tPri_JobUserAssigned`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_jobuserassigned.md); "assigned" and "unassigned" audit lines in one batch; one queued `AssignUserJob` per change sends the push and the silent assignment update, a minute later for AI-suggested assignments and not at all if that assignment was removed meanwhile; viewed rows and a touch of the task; an AI log row when the site has AI suggestions on.

## POST /v1/app/tasks/copy

Copies a task into the same group or another group of the same site, once or on a plan.

* **Auth:** user token; members of the target group. The source task isn't checked: it can be in any group of the site, also one the caller isn't in.
* **Used by:** web

**Request**

| Name                   | In   | Type              | Required        | Rules                                                                    |
| ---------------------- | ---- | ----------------- | --------------- | ------------------------------------------------------------------------ |
| `jobUuid`              | body | string            | yes             | The task to copy                                                         |
| `targetBusinessUuid`   | body | string            | yes             | The task's group or another group of the same site                       |
| `copyJobChat`          | body | integer           | no              | 0 or 1, default 1: copy the chat, reactions and status history           |
| `createTags`           | body | integer           | no              | 0 or 1, default 0: add the tag folders and tags the target lacks         |
| `createUserBusiness`   | body | integer           | no              | 0 or 1, default 0: add the followers and assignees the target lacks      |
| `planType`             | body | string            | no              | single, day, week or month: make one copy, or one per day, week or month |
| `startDate`, `endDate` | body | integer           | with `planType` | `YYYYMMDD`                                                               |
| `chatTypes`            | body | array of integers | no              | Chat item types; accepted and not used                                   |

A copy is titled " Copy" and gets a new reference number and no time range. A copy within the group also loses the due date and gets its checklist unchecked. Without copyJobChat the copy starts red with no approval. Copies keep the checklist and its media (within the group the media aren't copied), the checklist template link, tags (only with `createTags` \[[ASK-21](https://github.com/snapfix/docs/blob/main/ASK.md#ask-21-who-may-copy-or-move-a-task-and-what-should-the-tag-options-do)]), asset links, rooms, compliance systems, areas, schedules, time and cost, followers and assignees. Without `createUserBusiness`, followers and assignees the target group lacks are left out.

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

**Errors:** [common errors](#common-errors); `403` "Access denied" when the caller isn't in the target group; `400` "Source and Target businesses belongs to different accounts"; `404` unknown task, group, or (for a copy within the group) when the caller isn't in it.

**Side effects:** adds the copies to [`tPri_Job`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_job.md) and their copied rows to the task tables ([`tPri_JobChat`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_jobchat.md), [`tPri_JobTodo`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_jobtodo.md), [`tPri_JobTag`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_jobtag.md), [`tPri_JobRoom`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_jobroom.md), [`tPri_JobTimeCost`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_jobtimecost.md) and the others listed above); audit lines on each copy ("Duplicate Task", "Task copied from", "created", and the plan); a silent update push to the target group \[[ASK-12](https://github.com/snapfix/docs/blob/main/ASK.md#ask-12-which-settings-do-the-production-api-servers-use)]; adds the number of copies to the Firebase task counter.

## POST /v1/app/tasks/data

Returns tasks and every related row by task ID, shaped like the database tables, for the mobile apps' local database.

* **Auth:** user token; returns only tasks whose group exists and has the caller as a member now or in the past, without the per-task view rule.
* **Used by:** iOS and Android, to download tasks after they are unfrozen

**Request**

| Name     | In    | Type             | Required | Rules                                                         |
| -------- | ----- | ---------------- | -------- | ------------------------------------------------------------- |
| `uuids`  | body  | array of strings | yes      | Task IDs                                                      |
| `limit`  | query | integer          | no       | Page size, default 25                                         |
| `offset` | query | integer          | no       | Page number from 1, default 1. iOS sends a row offset instead |

**Response** `200` (trimmed)

```json
{
  "status": "success",
  "message": "Operation was successful",
  "data": {
    "jobs": [{ "uuid": "123", "uuid_tBusiness": "200", "color": "red", "fTitle": "Leaking tap", "fDueDateTs": null, "fCreatedTs": 1794387600000 }],
    "jobLink": [],
    "jobTag": [],
    "jobRoom": [{ "uuid": "900", "uuid_tJob": "123", "uuid_tRoom": "500" }],
    "jobUser": [],
    "jobUserAssigned": [],
    "jobChat": [{ "uuid": "400", "uuid_tJob": "123", "uuid_tChatItemType": 6, "fText": "<b>Jane Smith</b> created Task" }],
    "jobChatReaction": [],
    "jobTodo": [],
    "jobTodoMedia": [],
    "jobNotif": [],
    "jobTimeCost": []
  }
}
```

`jobs` has the columns of [`tPri_Job`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_job.md); the other lists hold every row of [`tPri_JobJobLink`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_jobjoblink.md), [`tPri_JobTag`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_jobtag.md), [`tPri_JobRoom`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_jobroom.md), [`tPri_JobUser`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_jobuser.md), [`tPri_JobUserAssigned`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_jobuserassigned.md), [`tPri_JobChat`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_jobchat.md), [`tPri_JobChat_Reaction`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_jobchat_reaction.md), [`tPri_JobTodo`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_jobtodo.md), [`tPri_JobTodoMedia`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_jobtodomedia.md), [`tPri_JobNotif`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_jobnotif.md) and [`tPri_JobTimeCost`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_jobtimecost.md) for those tasks. Times are epoch ms. A page can hold fewer tasks than `limit`, because tasks the caller may not get are dropped after paging.

**Errors:** [common errors](#common-errors).

**Side effects:** none.

## POST /v1/app/tasks/follow/multi

Adds and removes several followers of one task.

* **Auth:** user token; group admins, or members with the "assign user" permission who aren't read-only.
* **Used by:** web

**Request**

| Name              | In   | Type             | Required | Rules                                                            |
| ----------------- | ---- | ---------------- | -------- | ---------------------------------------------------------------- |
| `jobUuid`         | body | string           | yes      | The task; it must be editable                                    |
| `addUserUuids`    | body | array of strings | no       | Users to add; users who aren't members of the group are left out |
| `removeUserUuids` | body | array of strings | no       | Followers to remove                                              |
| `aiSuggested`     | body | integer          | no       | Accepted and not used                                            |

**Response** `200`: `data` is `{ "users": [...], "jobchats": [...] }`: the followers other than the caller, as [user objects](#user-object), and an "added" or "removed" audit line per change.

**Errors:** [common errors](#common-errors); `403` without the permission; `400` "The task can not be updated".

**Side effects:** adds or deletes rows in [`tPri_JobUser`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_jobuser.md); audit lines in one batch; per change, a push to that user and the task's people and a silent assignment update push; viewed rows and a touch of the task.

## POST /v1/app/tasks/generate-url

Creates a read-only share link for a task.

* **Auth:** user token; members of the task's group who are group admins, have "view all tasks", or follow or are assigned to the task. Being the task's creator isn't enough here.
* **Used by:** web (share dialog)

**Request**

| Name       | In   | Type   | Required | Rules                                                                       |
| ---------- | ---- | ------ | -------- | --------------------------------------------------------------------------- |
| `jobUuid`  | body | string | yes      | The task                                                                    |
| `expiryTs` | body | number | yes      | When the link stops working, epoch ms; not checked against the current time |

**Response** `200`

```json
{
  "status": "success",
  "message": "Operation was successful",
  "data": { "shareUrl": "https://tasks.example.com/9b1d0c42-5f6e-4a1b-9c3d-2e8f7a6b5c4d" }
}
```

`shareUrl` is the share page address (server setting `TASK_SHARE_DOMAIN`) followed by the link token. The share page reads the task through apipy `GET /g-job/{jobToken}`.

**Errors:** [common errors](#common-errors); `403` "Access denied"; `404` unknown task, or when the caller isn't in the task's group.

**Side effects:** adds a token row to [`url_job_token`](https://docs.snapfix.com/engineering-reference/db/tables/url_job_token.md) with the task, the expiry, read-only permission and the caller; viewed rows and a touch of the task.

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

Returns, for each listed task, whether the caller has read it and whether someone else changed it since the caller last opened its group or room.

* **Auth:** user token; the task IDs aren't checked against the caller's groups.
* **Used by:** web (task, feed and asset lists refresh with it)

**Request**

| Name       | In   | Type             | Required | Rules                                                                 |
| ---------- | ---- | ---------------- | -------- | --------------------------------------------------------------------- |
| `jobUuids` | body | array of strings | yes      | Task IDs                                                              |
| `roomUuid` | body | string           | no       | On room lists: also compare with the caller's last visit to this room |

**Response** `200`

```json
{
  "status": "success",
  "message": "Operation was successful",
  "data": [{ "jobUuid": "123", "hasRead": 0, "hasUpdate": 1, "modifiedTs": 1794387600000 }]
}
```

`hasUpdate` is 1 when the task's last activity is after the caller's last visit to its group (or room) and someone else made it. Otherwise `hasRead` is 1 when the caller viewed the task after its last activity. Unknown IDs are left out.

**Errors:** [common errors](#common-errors).

**Side effects:** none.

## POST /v1/app/tasks/job-cost

Adds one cost entry to a task.

* **Auth:** user token; members of the task's group, any role.
* **Used by:** Simon

**Request**

| Name           | In   | Type   | Required | Rules                                           |
| -------------- | ---- | ------ | -------- | ----------------------------------------------- |
| `jobUuid`      | body | string | yes      | The task; it must be editable                   |
| `title`        | body | string | yes      |                                                 |
| `cost`         | body | string | no       | Amount, such as "12.50"                         |
| `currencyCode` | body | string | no       | A currency marked supported in `std_currencies` |
| `description`  | body | string | no       |                                                 |
| `ts`           | body | string | no       | The entry's own time (`fOfficialTs`)            |

**Response** `200`: `data` is `{ "timeCost": { ... }, "jobchat": { ... } }`: a [time and cost object](#time-and-cost-object) and the "Added cost" audit line.

**Errors:** [common errors](#common-errors); `400` "The task can not be updated"; `403` when the caller isn't in the task's group; `404` unknown task.

**Side effects:** adds a cost row (type 1, the caller as user) to [`tPri_JobTimeCost`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_jobtimecost.md); an audit line, a push and a silent update push \[[ASK-12](https://github.com/snapfix/docs/blob/main/ASK.md#ask-12-which-settings-do-the-production-api-servers-use)]; viewed rows and a touch of the task.

## POST /v1/app/tasks/job-cost/multi

Adds, changes and deletes a task's cost entries in one call.

* **Auth:** user token; members of the task's group, any role. Any member can change or delete any entry, other users' included.
* **Used by:** web (time and cost dialog)

**Request**

| Name                          | In   | Type             | Required | Rules                                                                                             |
| ----------------------------- | ---- | ---------------- | -------- | ------------------------------------------------------------------------------------------------- |
| `jobUuid`                     | body | string           | yes      | The task; it must be editable                                                                     |
| `timeCostData`                | body | array of objects | yes      | One per entry to add, change or delete                                                            |
| `timeCostData.*.uuid`         | body | string           | no       | Empty for a new entry; an existing entry's ID to change it. The ID isn't checked against the task |
| `timeCostData.*.title`        | body | string           | yes      |                                                                                                   |
| `timeCostData.*.cost`         | body | string           | no       | Amount                                                                                            |
| `timeCostData.*.currencyCode` | body | string           | no       | A supported currency                                                                              |
| `timeCostData.*.description`  | body | string           | no       |                                                                                                   |
| `timeCostData.*.ts`           | body | string           | no       | The entry's own time                                                                              |
| `timeCostData.*.deleted`      | body | integer          | no       | 1 deletes the entry                                                                               |

**Response** `200`: `data` is `{ "timeCosts": [...], "jobchats": [...] }`: every cost entry of the task as [time and cost objects](#time-and-cost-object), and an audit line per change.

**Errors:** [common errors](#common-errors); `400` "The task can not be updated"; `403` when the caller isn't in the task's group.

**Side effects:** adds and updates rows in [`tPri_JobTimeCost`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_jobtimecost.md), one update per entry; "Added", "Edited" or "Removed cost" audit lines in one batch; a push and a silent update push per entry; viewed rows and a touch of the task.

## POST /v1/app/tasks/job-time

Adds one time entry to a task.

* **Auth:** user token; members of the task's group, any role.
* **Used by:** Simon

**Request:** as [`POST /v1/app/tasks/job-cost`](#post-v1apptasksjob-cost), plus:

| Name   | In   | Type   | Required | Rules                        |
| ------ | ---- | ------ | -------- | ---------------------------- |
| `time` | body | number | no       | Milliseconds, at least 60000 |

**Response** `200`: as `POST /v1/app/tasks/job-cost`, with an "Added time" audit line.

**Errors:** as `POST /v1/app/tasks/job-cost`.

**Side effects:** adds a time row (type 0) to [`tPri_JobTimeCost`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_jobtimecost.md); otherwise as `POST /v1/app/tasks/job-cost`.

## POST /v1/app/tasks/job-time/multi

Adds, changes and deletes a task's time entries in one call.

* **Auth:** as [`POST /v1/app/tasks/job-cost/multi`](#post-v1apptasksjob-costmulti).
* **Used by:** web (time and cost dialog)

**Request:** as `POST /v1/app/tasks/job-cost/multi`, plus `timeCostData.*.time` (milliseconds, at least 0).

**Response** `200`: as `POST /v1/app/tasks/job-cost/multi`, with the task's time entries.

**Errors:** as `POST /v1/app/tasks/job-cost/multi`.

**Side effects:** as `POST /v1/app/tasks/job-cost/multi`, on time rows (type 0), with "Added", "Edited" or "Removed time" audit lines.

## POST /v1/app/tasks/list

Lists the tasks of one status in a group, a room or an area, with counts per status.

* **Auth:** user token; returns the tasks the caller can see there ([task permissions](#task-permissions)), or all of them for multi-site users of the site.
* **Used by:** web (group, room and area task lists), Simon

**Request**

| Name                                   | In            | Type    | Required    | Rules                                                                                                            |
| -------------------------------------- | ------------- | ------- | ----------- | ---------------------------------------------------------------------------------------------------------------- |
| `businessUuid`, `roomUuid`, `areaUuid` | query         | string  | exactly one | The group, room or area; the clients send it in the query string                                                 |
| `limit`                                | query         | integer | no          | Page size; without it the list has no limit                                                                      |
| `offset`                               | query         | integer | no          | Page number from 1, default 1                                                                                    |
| `sortBy`                               | query         | string  | no          | created, lastActivity, title, priorityLevel or dueDate; default the last change. Read from the query string only |
| `orderBy`                              | query or body | string  | no          | asc or desc, default desc; priorityLevel always sorts desc                                                       |
| `color`                                | body          | string  | no          | red, amber or green, default red; amber includes old yellow tasks                                                |
| filters                                | body          |         | no          | [Task list filters](#task-list-filters) for group, room and area lists                                           |

**Response** `200` (trimmed)

```json
{
  "status": "success",
  "message": "Operation was successful",
  "data": {
    "jobs": [{ "uuid": "123", "title": "Leaking tap", "status": { "uuid": "201", "name": "red" }, "checklistPercent": 50, "rooms": [{ "uuid": "500", "name": "Room 101" }] }],
    "totalCount": { "red": 12, "amber": 3, "green": 40 },
    "filterCount": { "red": 2, "amber": 0, "green": 5 },
    "pagination": { "total": 12, "perPage": 25, "currentPage": 1, "lastPage": 1, "from": 1, "to": 12 }
  }
}
```

`jobs` are [task objects](#task-object) with `status`, `checklistCount`, `checklistPercent`, `users` and `tags`, plus `rooms` and `areas` on group lists, `business` and `areas` on room lists, and `business` and `rooms` on area lists. `totalCount` counts the tasks per status without filters, archived tasks left out unless `archivedTasks` is sent; `filterCount` counts them with the filters. `pagination` comes only with `limit`.

**Errors:** [common errors](#common-errors); `422` when not exactly one of the three IDs is given; `404` unknown group, room or area; `500` for the unread filter on room and area lists.

**Side effects:** none.

## POST /v1/app/tasks/list-by-multiSite

Lists the tasks of a multi-site's sites, newest activity first.

* **Auth:** user token; returns the tasks the caller can see in their own groups of those sites. Membership of the multi-site isn't checked, but other groups' tasks never show.
* **Used by:** web (task feed while a multi-site is selected)

**Request**

| Name              | In    | Type             | Required | Rules                                                  |
| ----------------- | ----- | ---------------- | -------- | ------------------------------------------------------ |
| `multiSiteUuid`   | body  | string           | yes      | The multi-site                                         |
| `parents`         | body  | array of strings | no       | Only these sites                                       |
| `limit`, `offset` | query | integer          | no       | Page size (no limit without it) and page number from 1 |
| filters           | body  |                  | no       | [Task list filters](#task-list-filters) for site lists |

**Response** `200`: `data` has `jobs` ([task objects](#task-object) with `users` holding only `modifiedBy`, `businessInfo`, `rooms`, `areas` and `status`), `totalCount` (an integer: the caller's tasks in those sites, archived ones left out unless `archivedTasks` is sent) and, with `limit`, `pagination`.

**Errors:** [common errors](#common-errors); `404` unknown multi-site.

**Side effects:** none.

## POST /v1/app/tasks/list-by-parent

Lists a site's tasks across the caller's groups: the task feed.

* **Auth:** user token; returns the tasks the caller can see in their own groups of the site.
* **Used by:** web (task feed), Simon

**Request**

| Name              | In            | Type    | Required | Rules                                                                                                                                                                                                                                       |
| ----------------- | ------------- | ------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `parentUuid`      | query or body | string  | yes      | The site                                                                                                                                                                                                                                    |
| `limit`, `offset` | query         | integer | no       | Page size (no limit without it) and page number from 1                                                                                                                                                                                      |
| `sortBy`          | query or body | string  | no       | lastActivity, startDate, roomNumber or jobTitle. startDate puts today's tasks first, ordered by time range start; every other value sorts by last activity                                                                                  |
| `orderBy`         | query or body | string  | no       | asc or desc, default desc                                                                                                                                                                                                                   |
| `updateFilter`    | body          | boolean | no       | Also saves the filters as the caller's feed filter in `tPri_UserPreference` (added by a migration dated 2026-09-01, so missing from the staging copy behind [the database reference](https://docs.snapfix.com/engineering-reference/db.md)) |
| filters           | body          |         | no       | [Task list filters](#task-list-filters) for site lists, housekeeping filters included                                                                                                                                                       |

**Response** `200`: `data` has `jobs` ([task objects](#task-object) with `users` holding only `modifiedBy`, `businessInfo`, `rooms` with their status and guests, `areas`, `status`, `checklistInfo` and `reservation`), `totalCount` (an integer for the whole site, archived tasks left out unless `archivedTasks` is sent; only on page 1 or without `limit`) and, with `limit`, `pagination`.

**Errors:** [common errors](#common-errors).

**Side effects:** with `updateFilter`, saves the filter preference.

## POST /v1/app/tasks/list-for-checklist

Lists a site's tasks without checklist items, with or without a given checklist template, so a checklist can be added to them.

* **Auth:** user token; returns the tasks the caller can see in their own groups of the site.
* **Used by:** web (Site Console checklist tasks, and the add-checklist list of tasks)

**Request**

| Name              | In    | Type    | Required | Rules                                                                                         |
| ----------------- | ----- | ------- | -------- | --------------------------------------------------------------------------------------------- |
| `parentUuid`      | body  | string  | yes      | The site                                                                                      |
| `templateUuid`    | body  | string  | yes      | A site or multi-site checklist template                                                       |
| `withTemplate`    | body  | integer | yes      | 1: tasks that have this template; 0: tasks that don't                                         |
| `limit`, `offset` | query | integer | no       | Page size and page number from 1                                                              |
| filters           | body  |         | no       | [Task list filters](#task-list-filters) for site lists, without tags and housekeeping filters |

Groups where the template is hidden are left out, and the list is empty when the template is hidden for the whole site.

**Response** `200`: `data` has `jobs` ([task objects](#task-object) with `users` holding only `modifiedBy`, and `status`), `totalCount` (an integer) and, with `limit`, `pagination`.

**Errors:** [common errors](#common-errors); `404` unknown template.

**Side effects:** none.

## POST /v1/app/tasks/list-for-checklist/uuids

Returns the IDs of all tasks that [`POST /v1/app/tasks/list-for-checklist`](#post-v1apptaskslist-for-checklist) would list, for "Select all".

* **Auth:** as `POST /v1/app/tasks/list-for-checklist`.
* **Used by:** web (checklist task selection)

**Request:** as `POST /v1/app/tasks/list-for-checklist`, without `limit` and `offset`.

**Response** `200`

```json
{
  "status": "success",
  "message": "Operation was successful",
  "data": { "uuids": ["123", "124"], "truncated": false, "limit": 5000 }
}
```

At most `limit` IDs come back (server setting `CHECKLIST_SELECT_ALL_LIMIT`, default 5000); `truncated` says there were more.

**Errors:** as `POST /v1/app/tasks/list-for-checklist`.

**Side effects:** none.

## GET /v1/app/tasks/mark-as-read/{type}/{itemUuid}

Marks every task of a group or a room that the caller can see as read.

* **Auth:** user token; any signed-in user, but only tasks the caller can see are marked.
* **Used by:** web ("Mark all as read" on group and room task lists; on area lists it fails)

**Request**

| Name       | In   | Type   | Required | Rules             |
| ---------- | ---- | ------ | -------- | ----------------- |
| `type`     | path | string | yes      | business or room  |
| `itemUuid` | path | string | yes      | The group or room |

**Response** `200`

```json
{ "status": "success", "message": "Tasks marked as read", "data": null }
```

**Errors:** [common errors](#common-errors); `422` for another `type`, such as area; `404` unknown group or room.

**Side effects:** a viewed row in [`tPri_Log_JobViewedUser`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_log_jobvieweduser.md) per task, archived ones included, one insert at a time; a visit row for the group in [`tPri_Log_BusinessViewedUser`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_log_businessvieweduser.md) or the room in [`tPri_Log_RoomViewedUser`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_log_roomvieweduser.md).

## POST /v1/app/tasks/move

Moves one task to another group of the same site.

* **Auth:** as [`POST /v1/app/tasks/copy`](#post-v1apptaskscopy): members of the target group, with no check on the source task's group or on the caller's role.
* **Used by:** web

**Request:** as `POST /v1/app/tasks/copy`.

A task without `planType` moves at once, with its linked housekeeping tasks, as described for [`POST /v1/app/tasks/multi/move`](#post-v1apptasksmultimove): the target group gets a new task with a new ID and the original is deleted. With `planType`, for assets, or with the task's own group as target, it runs the copy steps instead and deletes the original after each copy.

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

**Errors:** as `POST /v1/app/tasks/copy`; `400` "Jobs not found" or "The task can not be updated" when a linked task can't move; `403` when the caller isn't in a linked task's group.

**Side effects:** as `POST /v1/app/tasks/multi/move` for each task; a silent update push to the target group; adds the moved tasks to the Firebase task counter, although the site has no more tasks than before.

## POST /v1/app/tasks/multi/archive

Archives or unarchives the listed tasks.

* **Auth:** user token; group admins, or members with the "archive task" permission in `businessUuid` who aren't read-only. The tasks in `uuids` aren't checked against that group: any task in Snapfix can be archived by ID.
* **Used by:** web (task list multi-select), Simon

**Request**

| Name           | In   | Type             | Required | Rules                                  |
| -------------- | ---- | ---------------- | -------- | -------------------------------------- |
| `businessUuid` | body | string           | yes      | The group the permission is checked in |
| `value`        | body | string           | yes      | "1" archives, "0" unarchives           |
| `uuids`        | body | array of strings | yes      | Task IDs                               |

The web also sends the list filters, which are ignored. Skips tasks as [`POST /v1/app/tasks/all/archive`](#post-v1apptasksallarchive) does.

**Response** `200`: `data` is `{ "total": 3 }`, the tasks that changed, linked inspection tasks included.

**Errors:** [common errors](#common-errors); `403` "Access denied" without the permission, or `messages.access_denied` when the caller isn't in `businessUuid`; `404` unknown group.

**Side effects:** as `POST /v1/app/tasks/all/archive`; the silent update push goes to `businessUuid`'s group \[[ASK-12](https://github.com/snapfix/docs/blob/main/ASK.md#ask-12-which-settings-do-the-production-api-servers-use)].

## POST /v1/app/tasks/multi/delete

Deletes the listed tasks.

* **Auth:** user token; group admins, or members with the "delete task" permission in `businessUuid` who aren't read-only. The tasks in `uuids` aren't checked against that group: any task in Snapfix can be deleted by ID.
* **Used by:** web (task list multi-select), Simon

**Request**

| Name           | In   | Type             | Required | Rules                                  |
| -------------- | ---- | ---------------- | -------- | -------------------------------------- |
| `businessUuid` | body | string           | yes      | The group the permission is checked in |
| `value`        | body | string           | yes      | Any value; the clients send "1"        |
| `uuids`        | body | array of strings | yes      | Task IDs                               |

**Response** `200`: `data` is `{ "total": 3 }`, the tasks deleted, linked inspection tasks of cleaning tasks included.

**Errors:** [common errors](#common-errors); `403` "Access denied" without the permission, or `messages.access_denied` when the caller isn't in `businessUuid`; `404` unknown group.

**Side effects:** soft-deletes the tasks in [`tPri_Job`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_job.md) one at a time, with no audit line; a silent update push to `businessUuid`'s group \[[ASK-12](https://github.com/snapfix/docs/blob/main/ASK.md#ask-12-which-settings-do-the-production-api-servers-use)]; the Firebase task counter doesn't change.

## POST /v1/app/tasks/multi/lock

Locks or unlocks the listed tasks.

* **Auth:** user token; no group permission is checked. Each task changes only when the caller is an admin of the task's group or its creator; a task in a group the caller isn't in stops the request with `403`, after the tasks before it have changed.
* **Used by:** web (task list multi-select), Simon

**Request**

| Name           | In   | Type             | Required | Rules                    |
| -------------- | ---- | ---------------- | -------- | ------------------------ |
| `businessUuid` | body | string           | yes      | A group the caller is in |
| `value`        | body | string           | yes      | "1" locks, "0" unlocks   |
| `uuids`        | body | array of strings | yes      | Task IDs                 |

Archived tasks and tasks outside their time range are skipped.

**Response** `200`: `data` is `{ "total": 3 }`, the tasks that changed.

**Errors:** [common errors](#common-errors); `404` when the caller isn't in `businessUuid`; `403` as above.

**Side effects:** as [`POST /v1/app/tasks/all/lock`](#post-v1apptasksalllock); the silent update push goes to `businessUuid`'s group \[[ASK-12](https://github.com/snapfix/docs/blob/main/ASK.md#ask-12-which-settings-do-the-production-api-servers-use)].

## POST /v1/app/tasks/multi/move

Queues a move of the listed tasks from one group to another group of the same site.

* **Auth:** user token; members of both groups. No role or permission is checked; the web offers Move only to group admins with the "create task" permission.
* **Used by:** web (task list multi-select), Simon

**Request**

| Name                 | In   | Type             | Required | Rules                                                               |
| -------------------- | ---- | ---------------- | -------- | ------------------------------------------------------------------- |
| `sourceBusinessUuid` | body | string           | yes      | The tasks' group                                                    |
| `targetBusinessUuid` | body | string           | yes      | Another group of the same site                                      |
| `uuids`              | body | array of strings | yes      | At least one task ID                                                |
| `copyJobChat`        | body | integer          | no       | 0 or 1, default 1: keep the chat, reactions and status history      |
| `createTags`         | body | integer          | no       | 0 or 1, default 0: add the tag folders and tags the target lacks    |
| `createUserBusiness` | body | integer          | no       | 0 or 1, default 0: add the followers and assignees the target lacks |

**Response** `200`

```json
{ "status": "success", "message": "Tasks are being moved to the selected group", "data": null }
```

The move runs later in `BulkMoveTasksToGroupJob` on the `long-running` queue (one try, 620 seconds), so failures are only logged. Tasks not in the source group fail, and linked housekeeping tasks move along when the caller is in their group. Each task, in its own transaction, is recreated in the target group with a new ID and reference number, with its chat (or a "created" line), checklist items and media, checklist template link, tags (only with `createTags` \[[ASK-21](https://github.com/snapfix/docs/blob/main/ASK.md#ask-21-who-may-copy-or-move-a-task-and-what-should-the-tag-options-do)]), asset links, rooms, compliance systems, areas, schedules, time and cost, followers and assignees, and a "moved from" audit line; then the original is deleted. Links between moved cleaning and inspection tasks point to the new tasks.

**Errors:** [common errors](#common-errors); `403` "Access denied" when the caller isn't in both groups; `400` "Source and Target businesses belongs to different accounts"; `422` when both groups are the same or `uuids` is empty.

**Side effects:** adds the new tasks to [`tPri_Job`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_job.md) and their rows to the task tables, soft-deletes the originals, and updates [`tPri_JobLink`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_joblink.md); with `createTags` or `createUserBusiness`, adds tags, tag folders or group members to the target group; no push and no change to the Firebase task counter.

## POST /v1/app/tasks/multi/priority

Sets the priority of the listed tasks.

* **Auth:** user token; members of `businessUuid`, read-only members included. No permission is checked, and the tasks in `uuids` aren't checked against that group: any task in Snapfix can be changed by ID.
* **Used by:** web (task list multi-select), Simon

**Request**

| Name           | In   | Type             | Required | Rules                    |
| -------------- | ---- | ---------------- | -------- | ------------------------ |
| `businessUuid` | body | string           | yes      | A group the caller is in |
| `value`        | body | string           | yes      | 0, 1, 5, 10, 20 or 30    |
| `uuids`        | body | array of strings | yes      | Task IDs                 |

Archived and locked tasks, and tasks outside their time range, are skipped.

**Response** `200`: `data` is `{ "total": 3 }`, the tasks that changed.

**Errors:** [common errors](#common-errors); `404` when the caller isn't in `businessUuid`; `422` for another `value`.

**Side effects:** as [`POST /v1/app/tasks/all/priority`](#post-v1apptasksallpriority); the silent update push goes to `businessUuid`'s group \[[ASK-12](https://github.com/snapfix/docs/blob/main/ASK.md#ask-12-which-settings-do-the-production-api-servers-use)].

## POST /v1/app/tasks/multi/status

Moves the listed tasks of a group to another status.

* **Auth:** user token; group admins, or members with the permission to move tasks to the new status who aren't read-only. Only tasks of `businessUuid` change.
* **Used by:** web (task list multi-select), Simon

**Request**

| Name           | In   | Type             | Required | Rules                                               |
| -------------- | ---- | ---------------- | -------- | --------------------------------------------------- |
| `businessUuid` | body | string           | yes      | The tasks' group                                    |
| `value`        | body | string           | yes      | red, amber or green: the new status                 |
| `uuids`        | body | array of strings | yes      | Task IDs; tasks already in that status are left out |

Works as [`POST /v1/app/tasks/all/status`](#post-v1apptasksallstatus) on the listed tasks.

**Response** `200`: `data` is `{ "total": 3 }`, the tasks that changed.

**Errors:** [common errors](#common-errors); `403` "Access denied" without the permission; `422` for another `value`.

**Side effects:** as `POST /v1/app/tasks/all/status`.

## POST /v1/app/tasks/notify-contractor

Emails a contractor who is assigned to a task a read-only link to it.

* **Auth:** user token; group admins, or members with the "assign user" permission who aren't read-only.
* **Used by:** web, iOS, Android (after a contractor is assigned)

**Request**

| Name       | In   | Type   | Required | Rules                                                                         |
| ---------- | ---- | ------ | -------- | ----------------------------------------------------------------------------- |
| `jobUuid`  | body | string | yes      | The task                                                                      |
| `userUuid` | body | string | yes      | A contractor of the site who is assigned to the task and has an email address |

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

**Errors:** [common errors](#common-errors); `400` "User is not a contractor for this workspace", "User is not assigned to this task" or "Contractor has no email address"; `403` without the permission; `404` unknown task or user.

**Side effects:** adds a share token valid for one year to [`url_job_token`](https://docs.snapfix.com/engineering-reference/db/tables/url_job_token.md); queues an email (`ContractorTaskAssignmentEmail`) to the contractor with their name, the task title, the site name and the share link; viewed rows and a touch of the task.

## POST /v1/app/tasks/room-add

Sets a task's room: removes the rooms it has and adds the first room of the list that is in the task's site.

* **Auth:** user token; members of the task's group, any role, read-only members included.
* **Used by:** web, Android (housekeeping "create task"), Simon. iOS has the address in its endpoint list but doesn't call it.

**Request**

| Name          | In   | Type             | Required | Rules                                           |
| ------------- | ---- | ---------------- | -------- | ----------------------------------------------- |
| `jobUuid`     | body | string           | yes      | The task; it must be editable                   |
| `roomUuids`   | body | array of strings | yes      | Only the first room in the task's site is added |
| `aiSuggested` | body | integer          | no       | 0 or 1, default 0                               |

The task's current rooms go without a "Removed" audit line, also when no room of the list is in the site. Adding a room also marks the task pending (`fBacklog` = 1) \[[ASK-16](https://github.com/snapfix/docs/blob/main/ASK.md#ask-16-should-adding-a-room-to-a-task-always-mark-it-pending)]. For cleaning and inspection tasks it applies the room's status rule and guest status, and for cleaning tasks it can create the linked inspection task ([Housekeeping API](https://docs.snapfix.com/engineering-reference/api/housekeeping.md)).

**Response** `200`

```json
{
  "status": "success",
  "message": "Operation was successful",
  "data": {
    "jobRooms": [{ "uuid": "500", "name": "Room 101", "aiSuggested": 0, "date": "2026-11-11T09:00:00.000000Z" }],
    "jobchats": [{ "uuid": "404", "text": "Added : Room 101", "type": 74 }]
  }
}
```

**Errors:** [common errors](#common-errors); `403` when the caller isn't in the task's group; `400` "The task can not be updated"; `404` unknown task.

**Side effects:** replaces the task's rows in [`tPri_JobRoom`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_jobroom.md); sets `fBacklog`, `fBacklogTs` and `uuid_tUser_BacklogChangedBy` in [`tPri_Job`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_job.md); an "Added" audit line and a push to the task's people, and a silent update push \[[ASK-12](https://github.com/snapfix/docs/blob/main/ASK.md#ask-12-which-settings-do-the-production-api-servers-use)]; viewed rows; an AI log row in [`log_ai_job`](https://docs.snapfix.com/engineering-reference/db/tables/log_ai_job.md) when the site has AI suggestions on and the old or new room came from the AI.

## POST /v1/app/tasks/room-remove

Removes one room from a task.

* **Auth:** user token; members of the task's group, any role.
* **Used by:** web, Simon

**Request**

| Name       | In   | Type   | Required | Rules                         |
| ---------- | ---- | ------ | -------- | ----------------------------- |
| `jobUuid`  | body | string | yes      | The task; it must be editable |
| `roomUuid` | body | string | yes      | A room the task has           |

**Response** `200`: `data` is `{ "jobchat": { ... } }`, the "Removed : Room 101" audit line.

**Errors:** [common errors](#common-errors); `404` when the task doesn't have that room; `403` when the caller isn't in the task's group; `400` "The task can not be updated".

**Side effects:** deletes the row in [`tPri_JobRoom`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_jobroom.md); an audit line, a push to the task's people and a silent update push; viewed rows and a touch of the task; an AI log row when the room came from the AI.

## POST /v1/app/tasks/soft-freeze

Freezes or unfreezes tasks. Frozen tasks drop out of the mobile apps' data loads.

* **Auth:** user token; tasks the caller can't change, or whose group the caller isn't in, are skipped without an error.
* **Used by:** web (unfreezes a frozen task when it is opened) \[[ASK-7](https://github.com/snapfix/docs/blob/main/ASK.md#ask-7-should-soft-freeze-still-run)]

**Request**

| Name         | In   | Type             | Required | Rules                                                       |
| ------------ | ---- | ---------------- | -------- | ----------------------------------------------------------- |
| `uuids`      | body | array of strings | yes      | Task IDs; deleted tasks count too, missing ones are skipped |
| `softFreeze` | body | integer          | yes      | 1 freezes, 0 unfreezes                                      |

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

**Errors:** [common errors](#common-errors).

**Side effects:** sets `fSoftFreeze` and `fSoftFreezeTs` in [`tPri_Job`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_job.md), and `fSoftFreeze` on the tasks' rows in [`tPri_JobChat`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_jobchat.md), [`tPri_JobNotif`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_jobnotif.md), [`tPri_JobJobLink`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_jobjoblink.md), [`tPri_JobUserAssigned`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_jobuserassigned.md), [`tPri_JobTodo`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_jobtodo.md), [`tPri_JobTodoMedia`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_jobtodomedia.md), [`tPri_JobTag`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_jobtag.md), [`tPri_JobUser`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_jobuser.md), [`tPri_JobTimeCost`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_jobtimecost.md), [`tPri_JobReminder`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_jobreminder.md) and [`tPri_JobAttribute`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_jobattribute.md); no audit line, no push, and nothing in [`tPri_Log_Job_SoftFreeze`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_log_job_softfreeze.md).

## POST /v1/app/tasks/statuses

Lists the approval activity (sent for approval, approved, rejected) of a group's tasks in one status, newest first.

* **Auth:** user token; covers the tasks the caller can see, or all of them for multi-site users of the site; other users get an empty list.
* **Used by:** web (approval activity of a group)

**Request**

| Name              | In            | Type    | Required | Rules                                                   |
| ----------------- | ------------- | ------- | -------- | ------------------------------------------------------- |
| `businessUuid`    | query or body | string  | yes      | The group                                               |
| `color`           | body          | string  | no       | red, amber or green, default red                        |
| `limit`, `offset` | query         | integer | no       | Page size and page number from 1                        |
| filters           | body          |         | no       | [Task list filters](#task-list-filters) for group lists |

**Response** `200` (trimmed)

```json
{
  "status": "success",
  "message": "Operation was successful",
  "data": {
    "statuses": [{
      "uuid": "405",
      "chatItemType": 86,
      "approvalStatus": 2,
      "taskStatusTs": "2026-11-11T09:00:00.000000Z",
      "createdTs": "2026-11-11T09:00:00.000000Z",
      "job": { "uuid": "123", "title": "Leaking tap" },
      "user": { "uuid": "300", "name": "Jane Smith", "firstname": "Jane", "lastname": "Smith", "image": null }
    }],
    "pagination": { "total": 1, "perPage": 25, "currentPage": 1, "lastPage": 1, "from": 1, "to": 1 }
  }
}
```

`chatItemType` is 86 (sent for approval), 87 (approved) or 88 (rejected), and `approvalStatus` the matching 2, 1 or 0. Times are UTC.

**Errors:** [common errors](#common-errors); `404` unknown group.

**Side effects:** none.

## POST /v1/app/tasks/statuses-by-parent

Lists the approval activity of a site's tasks, newest first.

* **Auth:** user token; covers the tasks the caller can see in their own groups of the site.
* **Used by:** web (approval activity of the task feed)

**Request**

| Name              | In            | Type    | Required | Rules                                                  |
| ----------------- | ------------- | ------- | -------- | ------------------------------------------------------ |
| `parentUuid`      | query or body | string  | yes      | The site                                               |
| `limit`, `offset` | query         | integer | no       | Page size and page number from 1                       |
| filters           | body          |         | no       | [Task list filters](#task-list-filters) for site lists |

**Response** `200`: as [`POST /v1/app/tasks/statuses`](#post-v1apptasksstatuses).

**Errors:** [common errors](#common-errors).

**Side effects:** none.

## POST /v1/app/tasks/tag/multi

Adds and removes a task's tags in one call.

* **Auth:** user token; members of the task's group, any role.
* **Used by:** web, Simon

**Request**

| Name             | In   | Type             | Required | Rules                                                                            |
| ---------------- | ---- | ---------------- | -------- | -------------------------------------------------------------------------------- |
| `jobUuid`        | body | string           | yes      | The task; it must be editable                                                    |
| `addTagUuids`    | body | array of strings | no       | Tags to add; removed ones come back. Tags of other groups and sites are accepted |
| `removeTagUuids` | body | array of strings | no       | Tags to remove. An AI-created tag that no task uses any more is deleted          |
| `aiSuggested`    | body | integer          | no       | 0 or 1, default 0: the added tags came from the AI                               |

**Response** `200` (trimmed)

```json
{
  "status": "success",
  "message": "Operation was successful",
  "data": {
    "jobTagsWithHeader": [{ "uuid": "1000", "name": "Trade", "description": null, "mandatory": 0, "tags": [{ "jobTagUuid": "1002", "uuid": "1001", "name": "Plumbing", "aiNewTag": 0 }] }],
    "jobchats": [{ "uuid": "406", "text": "1000,,<b>Jane Smith</b> added: Plumbing", "type": 14 }]
  }
}
```

`jobTagsWithHeader` lists the group's tag folders with the task's tags in each ([task object](#task-object) `tags`); tags outside the group's folders don't show there.

**Errors:** [common errors](#common-errors); `403` when the caller isn't in the task's group; `400` "The task can not be updated".

**Side effects:** adds, restores or deletes rows in [`tPri_JobTag`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_jobtag.md) and deletes unused AI tags in [`tPri_Tag`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_tag.md); "added" and "removed" audit lines in one batch and a push per change; viewed rows and a touch of the task; an AI log row when the site has AI suggestions on.

## POST /v1/app/tasks/unassign

Unassigns one user from a task.

* **Auth:** user token; group admins, or members with the "assign user" permission who aren't read-only.
* **Used by:** Simon. The web defines this call but never makes it; it unassigns through [`POST /v1/app/tasks/assign/multi`](#post-v1apptasksassignmulti).

**Request**

| Name       | In   | Type   | Required | Rules                                                                                                                                               |
| ---------- | ---- | ------ | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
| `jobUuid`  | body | string | yes      | The task; it must be editable, with the inspection task exception of `POST /v1/app/tasks/assign`                                                    |
| `userUuid` | body | string | yes      | A user assigned to the task; housekeeping tasks can refuse ([Housekeeping API](https://docs.snapfix.com/engineering-reference/api/housekeeping.md)) |

**Response** `200`: as [`POST /v1/app/tasks/assign`](#post-v1apptasksassign), with the message "User unassigned successfully" and an "unassigned" audit line.

**Errors:** [common errors](#common-errors); `400` "Job user relation does not exist"; `403` without the permission; `400` "The task can not be updated"; `404` unknown task or user.

**Side effects:** deletes the row in [`tPri_JobUserAssigned`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_jobuserassigned.md) and applies the housekeeping follow-up rules; an "unassigned" audit line; a silent assignment update push and an "unassigned" push; viewed rows and a touch of the task.

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

Returns one task with everything the task detail shows.

* **Auth:** user token; members of the task's group who can see the task ([task permissions](#task-permissions)). Multi-site users of the site skip the check.
* **Used by:** web (task detail), Simon

**Request**

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

**Response** `200` (trimmed)

```json
{
  "status": "success",
  "message": "Operation was successful",
  "data": {
    "job": {
      "uuid": "123",
      "title": "Leaking tap",
      "dueDateTs": 1794474000000,
      "status": { "uuid": "201", "name": "amber" },
      "business": { "uuid": "200", "name": "Maintenance", "image": null },
      "users": {
        "lastViewed": [{ "uuid": "300", "name": "Jane Smith", "image": null, "lastViewedTs": 1794387600000, "lastViewedDt": "2026-11-11 09:00:00" }],
        "assigned": [{ "uuid": "301", "isSystem": false, "name": "Sam Lee", "image": null, "date": "2026-11-11T09:05:00.000Z" }]
      },
      "rooms": [{ "uuid": "500", "name": "Room 101", "image": null, "aiSuggested": 0 }],
      "time": [],
      "cost": [{ "uuid": "1100", "title": "Washer", "description": null, "currencyCode": "EUR", "cost": "2.50", "user": { "uuid": "300", "name": "Jane Smith" } }],
      "parentJob": null
    }
  }
}
```

`job` is a [task object](#task-object) with `business`, `status`, `subStatus`, `users` (with `lastViewed` and `following`), `assets`, `signature`, `tags`, `rooms`, `systems`, `areas`, `time`, `cost` (each entry with its full [user object](#user-object)) and `parentJob`, plus `checklistInfo`, `reservation` and the resolved `approvalRequired`.

**Errors:** [common errors](#common-errors); `404` unknown task, or when the caller isn't in the task's group; `403` "Access denied" when the caller can't see the task.

**Side effects:** viewed rows for the task and its group ([common side effects](#common-side-effects)).

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

Changes one field of a task, chosen by `action`.

* **Auth:** user token; members of the task's group (multi-site users who aren't members get `404`), with the permission the action needs (table below).
* **Used by:** web, Simon (title and description)

**Request** (form data or JSON; the web sends file uploads as `POST` with the query `_method=PUT`)

| Name            | In   | Type    | Required                                 | Rules                                                                        |
| --------------- | ---- | ------- | ---------------------------------------- | ---------------------------------------------------------------------------- |
| `uuid`          | path | string  | yes                                      | The task                                                                     |
| `action`        | body | string  | yes                                      | One of the actions below                                                     |
| `value`         | body |         | per action                               | See below                                                                    |
| `autoColor`     | body | integer | with `color`                             | 1 when the app changes the status itself (the checklist started or finished) |
| `file`          | body | file    | with `image`; optional with `largeTitle` | At most 51200 KB; the type isn't checked                                     |
| `snoozedNotes`  | body | string  | no                                       | With `snooze`                                                                |
| `rejectionNote` | body | string  | when rejecting                           | With `approvalStatus` 0                                                      |

| `action`           | `value`                        | Who may                                                                                                                                                                                                   | What changes                                                                    |
| ------------------ | ------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------- |
| `title`            | string, at most 255 characters | can change the task                                                                                                                                                                                       | `fTitle`; clears `title_aiSuggested`                                            |
| `description`      | string or empty                | can change the task                                                                                                                                                                                       | `fDescription`, also on the linked inspection task of a cleaning task           |
| `largeTitle`       | string                         | can change the task                                                                                                                                                                                       | `fLargeTextTitle`; the photo becomes `file`, or none without it                 |
| `image`            | none                           | can change the task                                                                                                                                                                                       | The photo becomes `file`; clears the large text                                 |
| `color`            | red, amber or green            | group admin or the "move to" permission for that status, and not read-only (the permission is skipped for `autoColor` 1 when the group's automatic amber or green setting is on); or assigned to the task | Status, as in [`POST /v1/app/tasks/all/status`](#post-v1apptasksallstatus)      |
| `priority`         | 0, 1, 5, 10, 20 or 30          | can change the task                                                                                                                                                                                       | `fPriority`, `fPriorityLevel`, also on a cleaning task's linked inspection task |
| `reminder`         | boolean                        | can change the task                                                                                                                                                                                       | `fEnableTaskReminder`                                                           |
| `lock`             | boolean                        | can change the task, and group admin or the task's creator                                                                                                                                                | `fLocked`                                                                       |
| `archive`          | boolean                        | can change the task, and admin or the "archive task" permission                                                                                                                                           | `fArchived`; also archives a cleaning task's linked inspection task             |
| `snooze`           | DND, DNS, Delay or Other       | can change the task                                                                                                                                                                                       | `fSnoozed`, the reason and `snoozedNotes`                                       |
| `approvalRequired` | 0 or 1                         | can change the task, and admin, an assignee, or an assignee of the linked inspection task                                                                                                                 | `fApprovalRequired`; turning it off approves a pending green task               |
| `approvalStatus`   | -1, 0, 1 or 2                  | as `approvalRequired`                                                                                                                                                                                     | `fApprovalStatus`, `fApprovedTs`; 0 with `rejectionNote` adds a rejection note  |

The task must be editable for the action ([task permissions](#task-permissions)): `lock` and `archive` work on archived tasks, and housekeeping tasks can change status or archive outside their time range.

**Response** `200` (trimmed)

```json
{
  "status": "success",
  "message": "Operation was successful",
  "data": {
    "job": { "uuid": "123", "title": "Leaking tap", "status": { "uuid": "203", "name": "green" }, "approvalStatus": 2 },
    "jobchat": { "uuid": "407", "text": "203,,<b>Jane Smith</b> changed Status to Green", "type": 19 },
    "approveRequestJobChat": { "uuid": "408", "text": "Sent for Approval", "type": 86 }
  }
}
```

`job` is a [task object](#task-object) with `business`, `users`, `status`, `subStatus` and `parentJob`; `jobchat` is the audit line, or `null` for `approvalRequired`; `rejectJobChat`, `approveRequestJobChat` and `approveJobChat` come when the change made them.

**Errors:** [common errors](#common-errors); `403` "Access denied" without the permission; `404` unknown task, or when the caller isn't in the task's group; `400` "The task can not be updated"; `400` "Approve is not required" for `approvalStatus` on a task that doesn't need approval; `422` for a bad `action` or `value`.

**Side effects:**

* Updates [`tPri_Job`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_job.md) as in the table, and adds the audit line, plus approval lines when the change makes them.
* `color` adds rows to [`tPri_Job_StatusLog`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_job_statuslog.md), deletes due date reminders in [`schedule_v3`](https://docs.snapfix.com/engineering-reference/db/tables/schedule_v3.md) when green, and for cleaning and inspection tasks updates the room's status when the task starts or is completed ([Housekeeping API](https://docs.snapfix.com/engineering-reference/api/housekeeping.md)).
* `image` and `largeTitle` upload the file to file storage and delete the old photo.
* A push to the task's assignees and followers and a silent update push; an approval request also pushes to the group's admins.
* Viewed rows; an AI log row in [`log_ai_job`](https://docs.snapfix.com/engineering-reference/db/tables/log_ai_job.md) when an AI-suggested title changes and the site has AI suggestions on.

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

Deletes a task.

* **Auth:** user token; group admins, or members with the "delete task" permission who aren't read-only.
* **Used by:** web

**Request**

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

**Response** `200`

```json
{ "status": "success", "message": "Task deleted successfully", "data": null }
```

**Errors:** [common errors](#common-errors); `403` "Access denied" without the permission, or `messages.access_denied` when the caller isn't in the task's group; `404` unknown task.

**Side effects:** soft-deletes the task in [`tPri_Job`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_job.md), and the linked inspection task of a cleaning task; a silent "task deleted" push to the group; subtracts 1 from the Firebase task counter, and 1 for the inspection task; a viewed row for the group.

## POST /v1/app/tasks/{uuid}/due-date

Sets a task's due date, with an optional daily reminder.

* **Auth:** user token; members of the task's group who can see the task, read-only members included.
* **Used by:** web, iOS, Android, Simon (when the task has no due date)

**Request** (form data or JSON)

| Name                   | In   | Type    | Required | Rules                                          |
| ---------------------- | ---- | ------- | -------- | ---------------------------------------------- |
| `uuid`                 | path | string  | yes      | The task; it must be editable                  |
| `dueDateTs`            | body | integer | yes      | Due date, epoch ms                             |
| `dueDateDailyReminder` | body | integer | no       | 0 or 1, default 0: remind every day until then |

**Response** `200` (trimmed)

```json
{
  "status": "success",
  "message": "Due Date Updated",
  "data": {
    "job": { "uuid": "123", "dueDateTs": 1794474000000, "dueDateDailyReminder": 1, "status": { "uuid": "201", "name": "red" } },
    "jobchat": { "uuid": "409", "text": "1794474000000,,Due Date Set", "type": 77 }
  }
}
```

`job` is a [task object](#task-object) with `status` and `business`.

**Errors:** [common errors](#common-errors); `403` "Access denied" when the caller can't see the task; `404` unknown task, or when the caller isn't in the task's group; `400` "The task can not be updated".

**Side effects:** sets `fDueDateTs`, `fDueDateDailyReminder` and `uuid_tUser_DueDate` in [`tPri_Job`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_job.md); replaces the task's due date reminders in [`schedule_v3`](https://docs.snapfix.com/engineering-reference/db/tables/schedule_v3.md) (a daily reminder adds them); a "Due Date Set" audit line (type 77) whose text starts with the due date; a push to the task's people and a silent update push \[[ASK-12](https://github.com/snapfix/docs/blob/main/ASK.md#ask-12-which-settings-do-the-production-api-servers-use)]; viewed rows.

## PUT /v1/app/tasks/{uuid}/due-date

Changes a task's due date. It works as [`POST /v1/app/tasks/{uuid}/due-date`](#post-v1apptasksuuiddue-date); only the audit line differs ("Due Date Updated", type 78).

* **Auth:** as `POST /v1/app/tasks/{uuid}/due-date`.
* **Used by:** web, iOS, Android, Simon (when the task has a due date)

**Request:** as `POST /v1/app/tasks/{uuid}/due-date`; iOS and Android send it form-encoded.

**Response** `200`: as `POST /v1/app/tasks/{uuid}/due-date`.

**Errors:** as `POST /v1/app/tasks/{uuid}/due-date`.

**Side effects:** as `POST /v1/app/tasks/{uuid}/due-date`, with audit line type 78.

## DELETE /v1/app/tasks/{uuid}/due-date

Removes a task's due date and its daily reminder.

* **Auth:** as [`POST /v1/app/tasks/{uuid}/due-date`](#post-v1apptasksuuiddue-date).
* **Used by:** web, iOS, Android, Simon

**Request**

| Name   | In   | Type   | Required | Rules                         |
| ------ | ---- | ------ | -------- | ----------------------------- |
| `uuid` | path | string | yes      | The task; it must be editable |

**Response** `200`: as `POST /v1/app/tasks/{uuid}/due-date`, with the message "Due Date UnSet" and `dueDateTs` null.

**Errors:** as `POST /v1/app/tasks/{uuid}/due-date`.

**Side effects:** clears the due date fields in [`tPri_Job`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_job.md) and deletes the task's due date reminders in [`schedule_v3`](https://docs.snapfix.com/engineering-reference/db/tables/schedule_v3.md); a "Due Date UnSet" audit line (type 79); pushes and viewed rows as for `POST`.

## POST /v1/app/tasks/{uuid}/signature

Signs off a task's checklist with a signature image.

* **Auth:** user token only: no membership or permission check.
* **Used by:** web (checklist sign-off)

**Request** (`multipart/form-data`)

| Name   | In   | Type   | Required | Rules                                                         |
| ------ | ---- | ------ | -------- | ------------------------------------------------------------- |
| `uuid` | path | string | yes      | A task whose checklist needs a signature; it must be editable |
| `file` | body | file   | yes      | jpg, jpeg, png or gif, at most 51200 KB                       |

**Response** `200` (trimmed)

```json
{
  "status": "success",
  "message": "Signature added successfully",
  "data": {
    "job": { "uuid": "123", "signature": { "name": "Jane Smith", "fileUrl": "https://files.example.com/img/sign.png" } },
    "jobchat": { "uuid": "410", "text": "<b>Jane Smith</b> checklist signed off: 100 %", "type": 42, "fileUrl": "https://files.example.com/img/sign.png" }
  }
}
```

**Errors:** [common errors](#common-errors); `422` "Signature is disabled for this job" or "The todo list contains mandatory items to be checked"; `400` "This checklist has mandatory items"; `400` "The task can not be updated"; `404` unknown task.

**Side effects:** uploads the image to file storage; a signature audit line (type 42) with the image and the percentage of checklist items done in [`tPri_JobChat`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_jobchat.md); a push to the task's people and a silent update push; viewed rows.

## PUT /v1/app/tasks/{uuid}/signature

Sets whether a task's checklist needs a signature.

* **Auth:** user token only: no membership or permission check.
* **Used by:** web (checklist settings)

**Request**

| Name                    | In   | Type    | Required | Rules                                    |
| ----------------------- | ---- | ------- | -------- | ---------------------------------------- |
| `uuid`                  | path | string  | yes      | The task; it must be editable            |
| `todoSignatureRequired` | body | integer | yes      | 0 or 1, different from the current value |

**Response** `200`: `data` is `{ "job": { ... } }`, a [task object](#task-object) without the optional blocks, with the message "Signature enabled" or "Signature disabled".

**Errors:** [common errors](#common-errors); `422` "Signature is already enabled" or "Signature is already disabled"; `400` "The task can not be updated"; `404` unknown task.

**Side effects:** sets `fTodoSignatureRequired` in [`tPri_Job`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_job.md); viewed rows; no audit line and no push.

## POST /v1/app/tasks/{uuid}/time-range

Sets a task's time range: when it starts and how long it lasts. While a task has one, it can be changed only during that time ([task permissions](#task-permissions)).

* **Auth:** user token; group admins.
* **Used by:** web

**Request**

| Name                  | In   | Type    | Required | Rules                                                                                                                |
| --------------------- | ---- | ------- | -------- | -------------------------------------------------------------------------------------------------------------------- |
| `uuid`                | path | string  | yes      | The task; it must be unlocked and unarchived                                                                         |
| `timerangeStartMs`    | body | integer | yes      | Start, epoch ms, at least 0. The column is named "after midnight", but the web and the server store a full timestamp |
| `timerangeDurationMs` | body | integer | yes      | Length in ms, from 60000 to 604800000 (7 days)                                                                       |

**Response** `200`: `data` is `{ "job": { ... }, "jobchat": { ... } }`, a [task object](#task-object) and the "Time Range Set" audit line (type 66, its text starting with the start and length), with the message "Time Range Updated".

**Errors:** [common errors](#common-errors); `403` "Access denied" for non-admins, or `messages.access_denied` when the caller isn't in the task's group; `400` "The task can not be updated"; `422` "Max duration is 168 hours (7 days)." and the other rules; `404` unknown task.

**Side effects:** sets `timerange_startAfterMidnightMs` and `timerange_durationMs` in [`tPri_Job`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_job.md); an audit line; a push to the task's people and a silent update push \[[ASK-12](https://github.com/snapfix/docs/blob/main/ASK.md#ask-12-which-settings-do-the-production-api-servers-use)]; viewed rows.

## DELETE /v1/app/tasks/{uuid}/time-range

Removes a task's time range.

* **Auth:** as [`POST /v1/app/tasks/{uuid}/time-range`](#post-v1apptasksuuidtime-range).
* **Used by:** web

**Request**

| Name   | In   | Type   | Required | Rules                                        |
| ------ | ---- | ------ | -------- | -------------------------------------------- |
| `uuid` | path | string | yes      | The task; it must be unlocked and unarchived |

**Response** `200`: as `POST /v1/app/tasks/{uuid}/time-range`, with the "Time Range UnSet" audit line (type 68) and the same message.

**Errors:** as `POST /v1/app/tasks/{uuid}/time-range`.

**Side effects:** clears both time range fields in [`tPri_Job`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_job.md); otherwise as `POST /v1/app/tasks/{uuid}/time-range`.

## PUT /v1/app/tasks/{uuid}/todo-name

Changes the name of a task's checklist.

* **Auth:** user token only: no membership or permission check.
* **Used by:** web (checklist editor)

**Request**

| Name   | In   | Type   | Required | Rules                                    |
| ------ | ---- | ------ | -------- | ---------------------------------------- |
| `uuid` | path | string | yes      | The task; it must be editable            |
| `name` | body | string | no       | The new name; empty or missing clears it |

**Response** `200`: `data` is `{ "job": { ... }, "jobchat": { ... } }`, a [task object](#task-object) and the audit line (type 76), with the message "Todo name updated successfully".

**Errors:** [common errors](#common-errors); `400` "The task can not be updated"; `404` unknown task.

**Side effects:** sets `fTodoName` in [`tPri_Job`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_job.md); an audit line in [`tPri_JobChat`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_jobchat.md); no push and no viewed rows.

## POST ?action=copy\_job\_v2

Copies one task, with its checklist, tags (only with `create_tags` \[[ASK-21](https://github.com/snapfix/docs/blob/main/ASK.md#ask-21-who-may-copy-or-move-a-task-and-what-should-the-tag-options-do)]), followers, assignees, links, rooms, areas and attributes, within its group or to another group of the same site; can also create the copy on planned dates.

* **Auth:** user token, if `JWT_AUTH_ENABLED` is on \[[ASK-12](https://github.com/snapfix/docs/blob/main/ASK.md#ask-12-which-settings-do-the-production-api-servers-use)]; any signed-in user. Nothing checks that the caller belongs to either group.
* **Used by:** iOS, Android (copy a task to a group; Android also copies a task to a chosen date)

**Request:** clients send POST with a JSON body.

| Name                          | In   | Type                                | Required         | Rules                                                                                                                                                                                                                                                                 |
| ----------------------------- | ---- | ----------------------------------- | ---------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `business_uuid_source`        | body | string                              | yes              | The task's group; not compared with the task's real group                                                                                                                                                                                                             |
| `business_uuid_target`        | body | string                              | yes              | Must be in the same site as the source group                                                                                                                                                                                                                          |
| `job_uuid`                    | body | string                              | yes              | A task that isn't deleted                                                                                                                                                                                                                                             |
| `create_tags`                 | body | 0 or 1                              | no, default 1    | 1: a tag folder the task uses that the target group lacks becomes a site-wide folder, added to both groups; 0: no tags are copied \[[ASK-21](https://github.com/snapfix/docs/blob/main/ASK.md#ask-21-who-may-copy-or-move-a-task-and-what-should-the-tag-options-do)] |
| `create_user_business`        | body | 0 or 1                              | no, default 1    | 1: people on the task who aren't in the target group are added to it, with their role and permissions from the source group                                                                                                                                           |
| `copy_job_chat`               | body | 0 or 1                              | no, default 1    | 1: also copies time and cost entries, chat messages and their reactions; within a group, signatures aren't copied. 0: copies only the "task created" message (type 6)                                                                                                 |
| `uuid_tChatItemTypes_to_copy` | body | array of numbers                    | no               | With `copy_job_chat` 1, copies only chat messages of these types                                                                                                                                                                                                      |
| `dest_color`                  | body | `red`, `amber`, `yellow` or `green` | no               | The copy's colour. Between groups it must equal the task's colour                                                                                                                                                                                                     |
| `dest_color_audit_message`    | body | 0 or 1                              | no               | 1: adds the chat message `<b>Snapfix</b> changed color to <colour>` when the copy's colour differs                                                                                                                                                                    |
| `plan_type`                   | body | `single`, `day`, `week` or `month`  | no               | Creates one copy per day, week or month from `start_date` to `end_date`, with no upper limit                                                                                                                                                                          |
| `start_date`, `end_date`      | body | string, `YYYYMMDD`                  | with `plan_type` | Android sends `single` with both set to the chosen date                                                                                                                                                                                                               |

**Response** `200`: the new task as a [Task bundle object](#task-bundle-object-php-apis-apipy), plus the memberships and tags the copy created. With `plan_type`, it describes the last copy.

```json
{
  "result": true,
  "message": "success",
  "data": {
    "tPri_Job": { "uuid": "task-124", "uuid_tBusiness": "group-2", "fTitle": "Leaking tap in Room 101 Copy", "color": "red", "fJobReference": "48213307", "business_name": "Maintenance" },
    "tPri_JobChat": [ { "uuid": "chat-9", "uuid_tChatItemType": 69, "fText": "Task copied from 'Housekeeping'. Nov 11 2026 09:30" } ],
    "tPri_JobUserAssigned": [],
    "tPri_UserBusiness": [],
    "tPri_Tag": []
  },
  "serverTs": 1794400000000
}
```

**Errors:** HTTP 200 with `result: false` and the message: `Data cannot be blank!` (empty body); `invalid params` (a required field missing); `invalid source group`, `invalid target group`, `invalid job`; `Source(<site>.<group>) and Target(<site>.<group>) group belongs to different businesses`; `Moving job between different colors is temporarily not available`; `invalid target business status` (the target group has no status of that colour); `Error while creating job <database error>`. Token and IP-block errors: [API conventions](https://docs.snapfix.com/engineering-reference/api.md).

**Side effects:**

* Inserts the copy into [`tPri_Job`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_job.md): new `uuid` and `fJobReference`, " Copy" added to the title, the target group's status for the colour, reminder and time range cleared, approval switched on when only the source group requires it. Without `plan_type`, the copy keeps the source's creation and task times.
* Copies the child rows (within a group, checklist items lose their answers) into [`tPri_JobTodo`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_jobtodo.md), [`tPri_JobTodoMedia`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_jobtodomedia.md), [`tPri_Job_CL_Template`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_job_cl_template.md) and its checklist permissions, [`tPri_JobComplySystem`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_jobcomplysystem.md), [`tPri_JobTag`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_jobtag.md), [`tPri_JobNotif`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_jobnotif.md), [`tPri_JobUser`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_jobuser.md), [`tPri_JobUserAssigned`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_jobuserassigned.md), [`tPri_JobJobLink`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_jobjoblink.md), [`tPri_JobRoom`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_jobroom.md), [`tPri_JobArea`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_jobarea.md), [`tPri_JobAttribute`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_jobattribute.md), and with `copy_job_chat` also [`tPri_JobTimeCost`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_jobtimecost.md), [`tPri_JobChat`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_jobchat.md) and [`tPri_JobChat_Reaction`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_jobchat_reaction.md).
* Between groups: may insert [`tPri_UserBusiness`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_userbusiness.md) rows (`create_user_business`), change [`tPri_TagHeader`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_tagheader.md) and insert [`tPri_BusinessTagHeaderRule`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_businesstagheaderrule.md) rows (`create_tags`), and adds the chat message "Task copied from ''. " (type 69). Within a group it adds "Duplicate task - all messages" or "Duplicate task - no messages" as the caller. With `plan_type` it adds a "Planned Date", "Planned Daily", "Planned Weekly" or "Planned Monthly" chat message whose name part is empty.
* Adds 1 to the site's task count in Firebase Realtime Database.
* When `WEB_QUEUE_SUPPORT` or `LEGACY_QUEUE_SUPPORT` is on \[[ASK-12](https://github.com/snapfix/docs/blob/main/ASK.md#ask-12-which-settings-do-the-production-api-servers-use)], also writes each change to [`tPri_Queue`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_queue.md) and asks apipy's `/req-to-notify-user-for-api-trigger` to tell both groups' members to refresh, which does nothing.

## POST ?action=copy\_job\_v2\_multiselect

Checks a copy of several tasks to a group, answers, then copies them one by one after the response is sent.

* **Auth:** as [`copy_job_v2`](#post-actioncopy_job_v2).
* **Used by:** Android and iOS (copying tasks chosen in a list; iOS builds the action name by adding `_multiselect` to `copy_job_v2`)

**Request:** clients send POST with a JSON body: the fields of [`copy_job_v2`](#post-actioncopy_job_v2), with `job_uuids` instead of `job_uuid`.

| Name                                                                                                        | In   | Type             | Required | Rules                                          |
| ----------------------------------------------------------------------------------------------------------- | ---- | ---------------- | -------- | ---------------------------------------------- |
| `business_uuid_source`                                                                                      | body | string           | yes      |                                                |
| `business_uuid_target`                                                                                      | body | string           | yes      | Same site as the source group                  |
| `job_uuids`                                                                                                 | body | array of strings | yes      | At least one task that isn't deleted           |
| `create_tags`, `create_user_business`, `copy_job_chat`, `dest_color`, `plan_type`, `start_date`, `end_date` | body |                  | no       | As in [`copy_job_v2`](#post-actioncopy_job_v2) |

**Response** `200`: an acceptance only; the client can't learn whether the copies succeeded.

```json
{
  "result": true,
  "message": "Request to copy tasks is accepted and will be processed shortly",
  "serverTs": 1794400000000
}
```

**Errors:** HTTP 200 with `result: false`: `Data cannot be blank!`; `invalid params`; `invalid source group`, `invalid target group`, `invalid jobs`; `Source(<site>.<group>) and Target(<site>.<group>) group belongs to different businesses`. Errors while copying, after the response, are dropped.

**Side effects:** after the response, the same writes as [`copy_job_v2`](#post-actioncopy_job_v2) for each task.

## POST ?action=generate\_task\_url

Creates a read-only share link for a task, valid until the given time.

* **Auth:** user token, if `JWT_AUTH_ENABLED` is on \[[ASK-12](https://github.com/snapfix/docs/blob/main/ASK.md#ask-12-which-settings-do-the-production-api-servers-use)]; any signed-in user. The link is recorded as created by the `user_uuid` in the body, not the token's user, and nothing checks that this user may see the task.
* **Used by:** iOS, Android (share a task as a link)

**Request:** clients send POST with a JSON body.

| Name        | In   | Type   | Required | Rules                                                                           |
| ----------- | ---- | ------ | -------- | ------------------------------------------------------------------------------- |
| `job_uuid`  | body | string | yes      | A task that isn't deleted                                                       |
| `user_uuid` | body | string | yes      | A user who isn't deleted                                                        |
| `expiry_ts` | body | number | yes      | Expiry, in ms since 1970; must be above 0. Not checked against the current time |

**Response** `200`:

```json
{
  "result": true,
  "message": "success",
  "data": { "share_url": "https://task.snapfix.com/0b1c2d3e-0000-4000-8000-000000000123" },
  "serverTs": 1794400000000
}
```

Outside production (`MODE` not `LIVE`) the link points at the test task page.

**Errors:** HTTP 200 with `result: false`: `Data cannot be blank!`; `invalid job uuid`, `invalid user uuid`, `invalid expiry_ts`; `invalid user`, `invalid job`; `url_job_token Creation Error : <database error>`.

**Side effects:** inserts a [`url_job_token`](https://docs.snapfix.com/engineering-reference/db/tables/url_job_token.md) row: the link token as `uuid`, `expiryTs`, `permission_json` `{"read-only": true}`, and the whole request in `user_request_json`.

## POST ?action=guest\_job\_data

Returns everything the shared task page shows for a share link that hasn't expired.

* **Auth:** app basic (HTTP Basic with the server's `AUTH_USERNAME` login; the action is on the no-login list) \[[ASK-12](https://github.com/snapfix/docs/blob/main/ASK.md#ask-12-which-settings-do-the-production-api-servers-use)]. Meant for apipy only.
* **Used by:** apipy [`GET /g-job/{jobToken}`](#get-g-jobjobtoken), which web\_tasks calls

**Request:** apipy sends POST with a JSON body.

| Name        | In   | Type   | Required | Rules                                                                                                                                             |
| ----------- | ---- | ------ | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
| `url_token` | body | string | yes      | A [`url_job_token`](https://docs.snapfix.com/engineering-reference/db/tables/url_job_token.md) `uuid` that is active, not deleted and not expired |

**Response** `200`: a [Shared task object](#shared-task-object-php-apis) in `data`.

```json
{
  "result": true,
  "message": "Success",
  "data": {
    "expiry_ts": 1794999999000,
    "parent_name": "Seaview Hotel",
    "business_name": "Maintenance",
    "job": { "fTitle": "Leaking tap in Room 101", "color": "amber", "type": "task" },
    "tags": [ { "tag_name": "Plumbing", "tag_header_name": "Category" } ],
    "chat": []
  },
  "serverTs": 1794400000000
}
```

**Errors:** HTTP 200 with `result: false`: `You are not authorised to access this API.` (wrong basic login); `Data cannot be blank!`; `invalid token` (empty token); `invalid job token` (unknown, inactive or expired token; the message ends with a space); `Job not found!`; `invalid asset register!` (asset task whose register is deleted).

**Side effects:** none.

## POST ?action=move\_job\_v2

Moves one task to another group of the same site: copies it there as [`copy_job_v2`](#post-actioncopy_job_v2) does, then deletes the original.

* **Auth:** as [`copy_job_v2`](#post-actioncopy_job_v2); anyone signed in can delete any task this way.
* **Used by:** iOS, Android (move a task to another group)

**Request:** as [`copy_job_v2`](#post-actioncopy_job_v2). The apps send `business_uuid_source`, `business_uuid_target`, `job_uuid`, `create_tags` and `create_user_business`.

**Response** `200`: as [`copy_job_v2`](#post-actioncopy_job_v2); the moved task keeps its title, and gets the chat message "Task moved from ''. " (type 70) instead of the "copied" one.

**Errors:** as [`copy_job_v2`](#post-actioncopy_job_v2).

**Side effects:** as [`copy_job_v2`](#post-actioncopy_job_v2), then sets `fDeleted` 1 on the original [`tPri_Job`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_job.md) row, with `uuid_tUser_ModifiedBy` `admin`. The original's child rows stay as they are.

## POST ?action=move\_job\_v2\_multiselect

Checks a move of several tasks to another group, answers, then moves them one by one after the response is sent.

* **Auth:** as [`copy_job_v2`](#post-actioncopy_job_v2).
* **Used by:** Android and iOS (moving tasks chosen in a list; iOS builds the action name by adding `_multiselect` to `move_job_v2`)

**Request:** as [`copy_job_v2_multiselect`](#post-actioncopy_job_v2_multiselect).

**Response** `200`: `{"result": true, "message": "Request to move tasks is accepted and will be processed shortly"}`, plus `serverTs`.

**Errors:** as [`copy_job_v2_multiselect`](#post-actioncopy_job_v2_multiselect).

**Side effects:** after the response, the writes of [`move_job_v2`](#post-actionmove_job_v2) for each task.

## POST ?action=read\_area\_jobs\_new\_updates

Counts, per area, the tasks with activity since the user last opened the area.

* **Auth:** user token, if `JWT_AUTH_ENABLED` is on \[[ASK-12](https://github.com/snapfix/docs/blob/main/ASK.md#ask-12-which-settings-do-the-production-api-servers-use)]; any signed-in user. Counts for the `user_uuid` in the body, not the token's user.
* **Used by:** iOS, Android (area list)

**Request:** clients send POST with a JSON body.

| Name         | In   | Type             | Required | Rules                                                                    |
| ------------ | ---- | ---------------- | -------- | ------------------------------------------------------------------------ |
| `user_uuid`  | body | string           | yes      | Not checked                                                              |
| `area_uuids` | body | array of strings | yes      | Must not be empty; an empty list fails with the database's error message |

**Response** `200`: one entry per area asked for. A task counts when it is linked to the area, isn't deleted or archived, and its last chat activity (`fJobChatModifiedTs`) is after the user's last visit; the user's own task permissions aren't applied.

```json
{
  "result": true,
  "message": "success",
  "data": [ { "uuid_tArea": "area-5", "new_job_update": 3 } ],
  "serverTs": 1794400000000
}
```

**Errors:** HTTP 200 with `result: false`: `Data cannot be blank!`; `invalid user_uuid`; `invalid area uuids`.

**Side effects:** for each area the user has never opened, inserts a [`tPri_Log_AreaViewedUser`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_log_areavieweduser.md) row dated now, so its count starts from now. Runs one count query per area.

## POST ?action=read\_business\_jobs\_new\_updates

Meant to count, per group, the tasks with activity since the user last opened the group; returns 0 for every group, because the handler fills one pair of variables and reads another, so its count query never runs.

* **Auth:** user token, if `JWT_AUTH_ENABLED` is on \[[ASK-12](https://github.com/snapfix/docs/blob/main/ASK.md#ask-12-which-settings-do-the-production-api-servers-use)]; any signed-in user. Works on the `user_uuid` in the body.
* **Used by:** iOS, Android (group list)

**Request:** clients send POST with a JSON body.

| Name             | In   | Type             | Required | Rules             |
| ---------------- | ---- | ---------------- | -------- | ----------------- |
| `user_uuid`      | body | string           | yes      | Not checked       |
| `business_uuids` | body | array of strings | yes      | Must not be empty |

**Response** `200`:

```json
{
  "result": true,
  "message": "success",
  "data": [ { "uuid_tBusiness": "group-2", "new_job_update": 0 } ],
  "serverTs": 1794400000000
}
```

**Errors:** HTTP 200: `{"success": "0", "message": "Data cannot be blank!"}` for an empty body; `result: false` with `invalid user_uuid` or `invalid business uuids`.

**Side effects:** for each group the user has never opened, inserts a [`tPri_Log_BusinessViewedUser`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_log_businessvieweduser.md) row dated now.

## POST ?action=read\_businessjob\_data

Returns every task of a group, deleted ones included, with all child rows, in one response.

* **Auth:** user token, if `JWT_AUTH_ENABLED` is on \[[ASK-12](https://github.com/snapfix/docs/blob/main/ASK.md#ask-12-which-settings-do-the-production-api-servers-use)]; any signed-in user, for any group.
* **Used by:** iOS (downloads every group of a site after switching sites)

**Request:** iOS sends POST with a JSON body.

| Name            | In   | Type   | Required | Rules                      |
| --------------- | ---- | ------ | -------- | -------------------------- |
| `business_uuid` | body | string | yes      | A group that isn't deleted |

**Response** `200`: a [Table data object](#table-data-object-php-apis) with `tPri_Job`, `tPri_JobTag`, `tPri_JobUser`, `tPri_JobChat`, `tPri_JobTodo`, `tPri_JobTodo_Notes`, `tPri_JobTodo_WithSection`, `tPri_JobTodoMedia`, `tPri_JobNotif`, `tPri_JobUserAssigned`, `tPri_JobTimeCost`, `tPri_JobAsset` and `tPri_JobChat_Reaction`. There is no paging: a group's whole history comes in one answer. The response is gzip-compressed when the client accepts it.

```json
{
  "result": true,
  "message": "Values Found",
  "data": {
    "tPri_Job": [ { "uuid": "task-123", "uuid_tBusiness": "group-2", "fTitle": "Leaking tap in Room 101", "color": "red" } ],
    "tPri_JobChat": [ { "uuid": "chat-1", "uuid_tJob": "task-123", "fText": "Plumber booked" } ]
  },
  "serverTs": 1794400000000
}
```

**Errors:** HTTP 200 with `result: false`: `Data cannot be blank!`; `invalid request parameters!`; `invalid business!`; `No Data found!`.

**Side effects:** none.

## POST ?action=read\_businessjob\_data\_v2

Returns one page of a group's tasks, newest first, with their child rows and colour counts.

* **Auth:** user token, if `JWT_AUTH_ENABLED` is on \[[ASK-12](https://github.com/snapfix/docs/blob/main/ASK.md#ask-12-which-settings-do-the-production-api-servers-use)]; any signed-in user, for any group, and every task of the group whatever the user may see.
* **Used by:** Android (group task download), iOS (when the apipy download fails)

**Request:** clients send POST with a JSON body.

| Name               | In   | Type   | Required        | Rules                                                                                           |
| ------------------ | ---- | ------ | --------------- | ----------------------------------------------------------------------------------------------- |
| `business_uuid`    | body | string | yes             | A group that isn't deleted                                                                      |
| `offset`           | body | number | no, default 0   | Put into the SQL as sent                                                                        |
| `limit`            | body | number | no, default 100 | Put into the SQL as sent                                                                        |
| `include_archived` | body | 0 or 1 | no              | 0 leaves out archived tasks; otherwise they're included                                         |
| `app_version`      | body | string | no              | Overrides the app version header; from 6.10.38 frozen tasks are left out and counted separately |

**Response** `200`: `data` is a [Table data object](#table-data-object-php-apis) with the page's `tPri_Job` rows and, for those tasks, `tPri_JobTag`, `tPri_JobUser`, `tPri_JobChat`, `tPri_JobTodo`, `tPri_JobTodo_WithSection`, `tPri_JobTodoMedia`, `tPri_JobNotif`, `tPri_JobUserAssigned`, `tPri_JobTimeCost`, `tPri_JobAsset`, `tPri_JobChat_Reaction`, `tPri_JobAttribute`, `tPri_JobJobLink`, `tPri_JobLink` and `tPri_JobTodo_Notes` (each key present, possibly empty). `total` is a [Task count object](#task-count-object-php-apis-apipy), filled only when `offset` is 0. Gzip-compressed when the client accepts it.

```json
{
  "result": true,
  "message": "Values Found",
  "data": {
    "tPri_Job": [ { "uuid": "task-123", "fTitle": "Leaking tap in Room 101", "color": "red", "fArchived": 0 } ],
    "tPri_JobUserAssigned": [ { "uuid": "assign-7", "uuid_tJob": "task-123", "uuid_tUser": "user-9", "fUnassigned": 0 } ]
  },
  "total": { "jobs": { "red": 12, "amber": 3, "green": 140, "red_archived": 1, "amber_archived": 0, "green_archived": 98, "red_frozen": 0, "amber_frozen": 0, "green_frozen": 20, "red_frozen_archived": 0, "amber_frozen_archived": 0, "green_frozen_archived": 15, "unknown": 0, "unknown_archived": 0, "unknown_frozen": 0 } },
  "serverTs": 1794400000000
}
```

**Errors:** HTTP 200 with `result: false`: `Data cannot be blank!`; `invalid request parameters!`; `invalid business!`; `No Data found!` (no task on this page).

**Side effects:** none.

## POST ?action=read\_businessjob\_data\_v2\_proxy

The same as [`read_businessjob_data_v2`](#post-actionread_businessjob_data_v2), behind the shared basic login, for apipy's [`/v5/{user_uuid}/jobs`](#post-v5user_uuidjobs).

* **Auth:** app basic (`AUTH_USERNAME`; the action is on the no-login list) \[[ASK-12](https://github.com/snapfix/docs/blob/main/ASK.md#ask-12-which-settings-do-the-production-api-servers-use)]. Through apipy, anyone with a user token reaches it for any group.
* **Used by:** apipy `/v5/{user_uuid}/jobs` when the request names exactly one group, which is how iOS calls it

**Request:** apipy sends POST with a JSON body: `business_uuid`, `offset` and `limit` from its own query string (passed on as sent), `include_archived`, and `app_version` from the `Device-App-Version` header. Rules as in [`read_businessjob_data_v2`](#post-actionread_businessjob_data_v2).

**Response** `200`: as [`read_businessjob_data_v2`](#post-actionread_businessjob_data_v2).

**Errors:** as [`read_businessjob_data_v2`](#post-actionread_businessjob_data_v2), plus `You are not authorised to access this API.` for a wrong basic login.

**Side effects:** none.

## POST ?action=read\_data

Returns the rows of the tables the app asks for, from every group the user belongs to, changed since the time given per table.

* **Auth:** user token, if `JWT_AUTH_ENABLED` is on \[[ASK-12](https://github.com/snapfix/docs/blob/main/ASK.md#ask-12-which-settings-do-the-production-api-servers-use)]; any signed-in user. Reads the data of the `uuid_tUser` in the body, not the token's user.
* **Used by:** iOS (after sign-in and on refresh)

**Request:** iOS sends POST with a JSON body.

| Name                           | In   | Type                                    | Required      | Rules                                                                                                                                                                                                  |
| ------------------------------ | ---- | --------------------------------------- | ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `uuid_tUser`                   | body | string                                  | yes           | A user who isn't deleted                                                                                                                                                                               |
| `table_data`                   | body | array of `{"table", "last_updated_ts"}` | yes           | Table names as in the database. Names containing `tPub` are put into the SQL as sent; any other name not handled specially is read with a group filter only if the table has a `uuid_tBusiness` column |
| `table_data[].last_updated_ts` | body | number                                  | no, default 0 | ms; rows with `fServerTs` from 5 seconds before it. 0 also leaves out deleted rows of most tables                                                                                                      |
| `uuid_device`                  | body | string                                  | no            | Groups this device hasn't loaded before are sent in full                                                                                                                                               |
| `parent_uuids`                 | body | array                                   | no            | Sent by iOS; ignored                                                                                                                                                                                   |

**Response** `200`: a [Table data object](#table-data-object-php-apis). The user's groups include those they left or that were deleted. `tPri_User` holds every member of those groups; `tPri_Parent` their sites. There is no paging.

```json
{
  "result": true,
  "message": "Values Found",
  "data": {
    "tPri_Business": [ { "uuid": "group-2", "fName": "Maintenance" } ],
    "tPri_Job": [ { "uuid": "task-123", "uuid_tBusiness": "group-2", "fTitle": "Leaking tap in Room 101" } ]
  },
  "serverTs": 1794400000000
}
```

**Errors:** HTTP 200 with `result: false`: `Invalid Request Params` (no `uuid_tUser`); `Invalid User`; `Invalid User Business` (in no group); `No Values Found`.

**Side effects:** with `uuid_device`, inserts a [`tUserAddedToBusiness_DeviceUuid`](https://docs.snapfix.com/engineering-reference/db/tables/tuseraddedtobusiness_deviceuuid.md) row for each membership the device hasn't loaded.

## POST ?action=read\_data\_v2

Returns the rows of the tables the app asks for, from the user's groups in the given sites, changed since the time given per table.

* **Auth:** user token, if `JWT_AUTH_ENABLED` is on \[[ASK-12](https://github.com/snapfix/docs/blob/main/ASK.md#ask-12-which-settings-do-the-production-api-servers-use)]; any signed-in user. Reads the data of the `uuid_tUser` in the body.
* **Used by:** Android (main sync, also as a stream)

**Request:** Android sends POST with a JSON body.

| Name                           | In   | Type                                    | Required | Rules                                                                                                                                                                              |
| ------------------------------ | ---- | --------------------------------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `uuid_tUser`                   | body | string                                  | yes      | A user who isn't deleted                                                                                                                                                           |
| `parent_uuids`                 | body | array of strings                        | yes      | Sites; all must exist                                                                                                                                                              |
| `table_data`                   | body | array of `{"table", "last_updated_ts"}` | yes      | As in [`read_data`](#post-actionread_data): names containing `tPub` go into the SQL as sent, and unknown names are read with a group filter only if the table has `uuid_tBusiness` |
| `table_data[].last_updated_ts` | body | number                                  | no       | ms; rows with `fServerTs` after it minus 5 seconds. Only when it's left out are deleted rows left out; 0 counts as minus 5 seconds, so a first load with 0 includes deleted rows   |
| `uuid_device`                  | body | string                                  | no       | As in [`read_data`](#post-actionread_data)                                                                                                                                         |

App versions are read as numbers with the dots removed (6.10.38 is 61038), from the `device-app-version` or `snapfix-version` header. Above 6105 the groups include every asset register of the sites; up to 6105, only task groups the user belongs to.

**Response** `200`: a [Table data object](#table-data-object-php-apis); only tables with rows are included. The first load (`last_updated_ts` 0) sends every task of the user's groups in one answer. Gzip-compressed when the client accepts it.

```json
{
  "result": true,
  "message": "Values Found",
  "data": {
    "tPri_Job": [ { "uuid": "task-123", "fTitle": "Leaking tap in Room 101", "fServerTs": 1794399990000 } ],
    "frozen_job_uuids": [],
    "unfrozen_job_uuids": [ "task-77" ]
  },
  "serverTs": 1794400000000
}
```

**Errors:** HTTP 200 with `result: false`: `Data cannot be blank!`; `invalid params`; `invalid parent uuids`; `invalid user`; `invalid parent!`; `invalid parent count!` (a site doesn't exist); `user is not part of any business!`; `No Values Found` (nothing changed).

**Side effects:** as [`read_data`](#post-actionread_data).

## POST ?action=read\_data\_v3

As [`read_data_v2`](#post-actionread_data_v2), with a row limit, column choice and filters per table, used to migrate an app's local database.

* **Auth:** as [`read_data_v2`](#post-actionread_data_v2).
* **Used by:** iOS and Android (local database migration), Android (frozen tasks)

**Request:** clients send POST with a JSON body: the fields of [`read_data_v2`](#post-actionread_data_v2), plus per table:

| Name                           | In   | Type                                       | Required      | Rules                                                                                                                                          |
| ------------------------------ | ---- | ------------------------------------------ | ------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
| `table_data[].last_updated_ts` | body | number                                     | no, default 0 | ms; rows with `fModifiedTs` after it, oldest change first                                                                                      |
| `table_data[].limit`           | body | number                                     | no            | Rows per table                                                                                                                                 |
| `table_data[].selection`       | body | array of strings                           | no            | Columns to return; put into the SQL as sent                                                                                                    |
| `table_data[].filter`          | body | array of `{"key", "comparision", "value"}` | no            | Combined with OR, as `key comparision 'value'`; `IS NOT` with an empty value means `IS NOT NULL`. All three parts are put into the SQL as sent |

**Response** `200`: as [`read_data_v2`](#post-actionread_data_v2); `tPri_Job` is included even when empty.

**Errors:** as [`read_data_v2`](#post-actionread_data_v2).

**Side effects:** as [`read_data`](#post-actionread_data).

## POST ?action=read\_jobs\_last\_viewed

Lists the people who viewed a task, with their last view time, newest first.

* **Auth:** user token, if `JWT_AUTH_ENABLED` is on \[[ASK-12](https://github.com/snapfix/docs/blob/main/ASK.md#ask-12-which-settings-do-the-production-api-servers-use)]; any signed-in user, for any task; the answer includes viewers' email addresses and phone numbers.
* **Used by:** iOS, Android (task details: who has seen the task)

**Request:** clients send POST with a JSON body.

| Name        | In   | Type   | Required | Rules       |
| ----------- | ---- | ------ | -------- | ----------- |
| `uuid_tJob` | body | string | yes      | Not checked |

**Response** `200`: one [User summary object](#user-summary-object-php-apis) per viewer, with `user_uuid`, `last_viewed_ts` (ms) and `last_viewed_dt` (`YYYY-MM-DD HH:MM:SS`, in the database's time zone).

```json
{
  "result": true,
  "message": "success",
  "data": [ { "user_uuid": "user-9", "user_name": "Jane Doe", "fUsername": "jane@example.com", "last_viewed_ts": 1794399000000, "last_viewed_dt": "2026-11-11 09:10:00" } ],
  "serverTs": 1794400000000
}
```

**Errors:** HTTP 200 with `result: false`: `Data cannot be blank!`; `invalid job uuid`.

**Side effects:** none.

## POST ?action=read\_jobs\_read\_status

Tells, per task, whether the user has read its latest activity.

* **Auth:** user token, if `JWT_AUTH_ENABLED` is on \[[ASK-12](https://github.com/snapfix/docs/blob/main/ASK.md#ask-12-which-settings-do-the-production-api-servers-use)]; any signed-in user. Works on the `user_uuid` in the body.
* **Used by:** iOS, Android (task lists and feed)

**Request:** clients send POST with a JSON body.

| Name        | In   | Type             | Required | Rules             |
| ----------- | ---- | ---------------- | -------- | ----------------- |
| `user_uuid` | body | string           | yes      | Not checked       |
| `job_uuids` | body | array of strings | yes      | Must not be empty |

**Response** `200`: one entry per task asked for. `has_new_update` 1 means activity (`fJobChatModifiedTs`) after the user last opened both the task and its group; `has_read` 0 with `has_new_update` 0 means activity after the user last opened the task but before they last opened the group; otherwise `has_read` is 1. Unknown tasks get 0 and 0.

```json
{
  "result": true,
  "message": "success",
  "data": [ { "uuid_tJob": "task-123", "has_read": 0, "has_new_update": 1 } ],
  "serverTs": 1794400000000
}
```

**Errors:** HTTP 200: `{"success": "0", "message": "Data cannot be blank!"}` for an empty body; `result: false` with `invalid user_uuid` or `invalid job uuids`.

**Side effects:** none.

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

Returns the user's sites with their settings, asset registers and the user's consent settings; used at sign-in and when switching sites.

* **Auth:** user token, if `JWT_AUTH_ENABLED` is on \[[ASK-12](https://github.com/snapfix/docs/blob/main/ASK.md#ask-12-which-settings-do-the-production-api-servers-use)]; any signed-in user. Reads the sites of the `user_uuid` in the body.
* **Used by:** iOS (sign-in, site switcher), Android (sign-in, site list)

**Request:** clients send POST with a JSON body.

| Name                       | In     | Type   | Required | Rules                                       |
| -------------------------- | ------ | ------ | -------- | ------------------------------------------- |
| `user_uuid`                | body   | string | yes      | A user who isn't deleted                    |
| `device-id` or `device_id` | header | string | no       | Sites that blocked this device are left out |

The sites are those of the user's groups, minus sites that blocked the user or the device. Groups and memberships that are deleted still count for sites the user administers, directly or through a multi-site. The multi-site part finds no sites: it looks up the multi-sites' sites in `tPri_MultiSiteParent` by the row's own `uuid` instead of `uuid_tMultiSite` (php-apis @ aee9175122, `htmlphp/api/snapfix/class/class.functions.php:29619-29622`).

**Response** `200`: `data` holds `tPub_Onboard`, `tPub_UserType`, `tPri_Parent` (each site with `parent_admin`, `basic_address`, `region`, `php_base_url` and `py_base_url`), `tPri_NotificationGlobal` and `tPri_NotificationBusiness` (always empty), `tPri_SettingsParent`, `assetReg`, `assetMain`, and `tPri_Log_UserGdpr` (the user's latest consent row, or a default row with `uuid` `unknown`). Gzip is not used.

```json
{
  "result": true,
  "message": "Values Found",
  "data": {
    "tPri_Parent": [ { "uuid": "site-1", "fName": "Seaview Hotel", "parent_admin": 1, "region": "eu-west-1", "basic_address": null } ],
    "tPri_SettingsParent": [],
    "tPri_Log_UserGdpr": [ { "uuid": "unknown", "uuid_tUser": "user-9", "fReceiveAccountUpdates": 0 } ]
  },
  "serverTs": 1794400000000
}
```

**Errors:** HTTP 200 with `result: false`: `Data cannot be blank!`; `invalid request parameters!`; `invalid user!`; `user is not part of any business!`; `no busienss found!` (every site is blocked or deleted; misspelled in the code); `No Data found!`.

**Side effects:** none.

## POST ?action=read\_parent\_jobs\_new\_updates

Counts, per site, the tasks with activity since the user last opened each group, summed over the site's groups.

* **Auth:** user token, if `JWT_AUTH_ENABLED` is on \[[ASK-12](https://github.com/snapfix/docs/blob/main/ASK.md#ask-12-which-settings-do-the-production-api-servers-use)]; any signed-in user. Counts for the `user_uuid` in the body.
* **Used by:** iOS, Android (site switcher)

**Request:** clients send POST with a JSON body.

| Name           | In   | Type             | Required | Rules                                    |
| -------------- | ---- | ---------------- | -------- | ---------------------------------------- |
| `user_uuid`    | body | string           | yes      | Not checked                              |
| `parent_uuids` | body | array of strings | yes      | Sites; all must exist and not be deleted |

**Response** `200`: one entry per site. A task counts when it isn't deleted or archived and its last chat activity is after the user's last visit to its group; members who may see only their own tasks (not admin, `perJobViewAll` 0) count only tasks they created, follow or are assigned to.

```json
{
  "result": true,
  "message": "success",
  "data": [ { "uuid_tParent": "site-1", "new_job_update": 4 } ],
  "serverTs": 1794400000000
}
```

**Errors:** HTTP 200 with `result: false`: `Data cannot be blank!`; `invalid user_uuid`; `invalid parent uuids`; `invalid parents!`; `invalid groups!` (the sites have no groups).

**Side effects:** for each group of the sites the user has never opened, inserts a [`tPri_Log_BusinessViewedUser`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_log_businessvieweduser.md) row dated now, also for groups the user isn't in. The insert goes through the read-only connection (`DB_HOST_RO`); if that host is a read replica, the call fails for such users \[[ASK-12](https://github.com/snapfix/docs/blob/main/ASK.md#ask-12-which-settings-do-the-production-api-servers-use)]. Runs several queries per group.

## POST ?action=read\_room\_jobs\_new\_updates

Counts, per room, the tasks with activity since the user last opened the room.

* **Auth:** user token, if `JWT_AUTH_ENABLED` is on \[[ASK-12](https://github.com/snapfix/docs/blob/main/ASK.md#ask-12-which-settings-do-the-production-api-servers-use)]; any signed-in user. Counts for the `user_uuid` in the body.
* **Used by:** iOS, Android (room list)

**Request:** clients send POST with a JSON body.

| Name         | In   | Type             | Required | Rules                                                                    |
| ------------ | ---- | ---------------- | -------- | ------------------------------------------------------------------------ |
| `user_uuid`  | body | string           | yes      | Not checked                                                              |
| `room_uuids` | body | array of strings | yes      | Must not be empty; an empty list fails with the database's error message |

**Response** `200`: one entry per room, counted as in [`read_area_jobs_new_updates`](#post-actionread_area_jobs_new_updates), through [`tPri_JobRoom`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_jobroom.md).

```json
{
  "result": true,
  "message": "success",
  "data": [ { "uuid_tRoom": "room-101", "new_job_update": 1 } ],
  "serverTs": 1794400000000
}
```

**Errors:** HTTP 200 with `result: false`: `Data cannot be blank!`; `invalid user_uuid`; `invalid room uuids`.

**Side effects:** for each room the user has never opened, inserts a [`tPri_Log_RoomViewedUser`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_log_roomvieweduser.md) row dated now.

## POST ?action=save\_job\_status\_log

Saves the apps' log of task colour and approval changes; every row is a new entry.

* **Auth:** user token, if `JWT_AUTH_ENABLED` is on \[[ASK-12](https://github.com/snapfix/docs/blob/main/ASK.md#ask-12-which-settings-do-the-production-api-servers-use)]; any signed-in user, for any task.
* **Used by:** iOS, Android (sync)

**Request:** clients send POST with a JSON body.

| Name          | In   | Type                                                                                                                 | Required | Rules                                                                                                                                 |
| ------------- | ---- | -------------------------------------------------------------------------------------------------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------- |
| `insert_data` | body | array of [`tPri_Job_StatusLog`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_job_statuslog.md) rows | yes      | `uuid_tJob`, `color`, `fApprovalStatus`, `fNotes`, `fTaskStatusTs`, `fCreatedTs`, `uuid_tUser_CreatedBy`. The `uuid` sent is replaced |

**Response** `200`: a [Save result object](#save-result-object-php-apis).

**Errors:** as for every save action: see [Save result object](#save-result-object-php-apis).

**Side effects:**

* Inserts each row into [`tPri_Job_StatusLog`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_job_statuslog.md) with a new `uuid`.
* For a row created today (server time) with colour green, amber or yellow, on a housekeeping task (`enum_JobType` 45, 46 or 0, with a room status rule or room guest status), calls api\_php\_live\_v2's `POST /v1/internal/task-completed/{uuid}` with the colour, approval status, user and `source=mobile`, using the scripts basic login. It waits one second before the call and writes the call and the answer to a log file on the server.

## POST ?action=save\_pri\_job

Creates or changes tasks; the apps' sync sends each changed task row.

* **Auth:** user token, if `JWT_AUTH_ENABLED` is on \[[ASK-12](https://github.com/snapfix/docs/blob/main/ASK.md#ask-12-which-settings-do-the-production-api-servers-use)]; any signed-in user, for any task or group, any column.
* **Used by:** iOS, Android (sync)

**Request:** clients send POST with a JSON body.

| Name                                      | In     | Type                                                                                             | Required | Rules                                                                                                     |
| ----------------------------------------- | ------ | ------------------------------------------------------------------------------------------------ | -------- | --------------------------------------------------------------------------------------------------------- |
| `insert_data`                             | body   | array of [`tPri_Job`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_job.md) rows | yes      | See [Save result object](#save-result-object-php-apis) for how rows are handled                           |
| `device-type`, `device_type` or `forigin` | header | string                                                                                           | no       | Sets `enum_Origin` on new tasks: `android` 1, `ios` or `apple` 2, `web` 3, `web-admin` 4, anything else 0 |

Before writing a task, the server fills in what's missing: the group's first sub-status when `uuid_tStatusSub` is empty, `fJobTs` from `fCreatedTs`, `color` from the status's name, and `search_text` from colour, reference, title and description. It drops `uuid_schedule_origin` and `uuid_schedule_planned`, and `enum_Origin` on updates. `fImage` may hold base64 image data, which is stored as a file.

**Response** `200`: a [Save result object](#save-result-object-php-apis).

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

**Errors:** see [Save result object](#save-result-object-php-apis).

**Side effects:** writes [`tPri_Job`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_job.md); for each new task, adds 1 to the site's task count in Firebase Realtime Database. No notifications: the apps send those separately.

## POST ?action=save\_pri\_job\_area

Creates or changes links between tasks and areas.

* **Auth:** as [`save_pri_job`](#post-actionsave_pri_job).
* **Used by:** iOS, Android (sync)

**Request:** clients send POST with a JSON body.

| Name          | In   | Type                                                                                                     | Required | Rules                                                                      |
| ------------- | ---- | -------------------------------------------------------------------------------------------------------- | -------- | -------------------------------------------------------------------------- |
| `insert_data` | body | array of [`tPri_JobArea`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_jobarea.md) rows | yes      | `uuid`, `uuid_tJob`, `uuid_tArea`, `fDeleted`. Foreign keys aren't checked |

**Response** `200`: a [Save result object](#save-result-object-php-apis).

**Errors:** see [Save result object](#save-result-object-php-apis).

**Side effects:** writes [`tPri_JobArea`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_jobarea.md).

## ANY ?action=save\_pri\_job\_asset

Creates or changes links between tasks and assets.

* **Auth:** as [`save_pri_job`](#post-actionsave_pri_job).
* **Used by:** no live caller. Both apps save a task's asset links as task links, with [`save_pri_jobjoblink`](#post-actionsave_pri_jobjoblink). Android's sync sends only pending `tPri_JobAsset` rows and makes none (android @ 86068bfeea, `app/src/main/java/gmail/com/snapfixapp/room/dao/JobAssetDao.kt:30`, `viewModels/AssetSelectionViewModel.kt:116-132`); iOS skips the table in its sync (ios @ aa31967ac8, `Managers/TaskManager.swift:2244-2247`).

**Request:** a JSON body.

| Name          | In   | Type                                                                                                       | Required | Rules                                                               |
| ------------- | ---- | ---------------------------------------------------------------------------------------------------------- | -------- | ------------------------------------------------------------------- |
| `insert_data` | body | array of [`tPri_JobAsset`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_jobasset.md) rows | yes      | `uuid`, `uuid_tJob`, `uuid_assetMain`, `uuid_tBusiness`, `fDeleted` |

**Response** `200`: a [Save result object](#save-result-object-php-apis).

**Errors:** see [Save result object](#save-result-object-php-apis).

**Side effects:** writes [`tPri_JobAsset`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_jobasset.md).

## POST ?action=save\_pri\_job\_notif

Creates or changes task notification times.

* **Auth:** as [`save_pri_job`](#post-actionsave_pri_job).
* **Used by:** Android (sync)

**Request:** Android sends POST with a JSON body.

| Name          | In   | Type                                                                                                       | Required | Rules                                                                                                                        |
| ------------- | ---- | ---------------------------------------------------------------------------------------------------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------- |
| `insert_data` | body | array of [`tPri_JobNotif`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_jobnotif.md) rows | yes      | `uuid`, `uuid_tJob`, `uuid_tBusiness`, `uuid_tNotifRepeatType`, `fTitle`, `fDate`, `fTime`, `fNotifTs` and the other columns |

**Response** `200`: a [Save result object](#save-result-object-php-apis).

**Errors:** see [Save result object](#save-result-object-php-apis).

**Side effects:** writes [`tPri_JobNotif`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_jobnotif.md).

## POST ?action=save\_pri\_job\_room

Creates or changes links between tasks and rooms.

* **Auth:** as [`save_pri_job`](#post-actionsave_pri_job).
* **Used by:** iOS, Android (sync)

**Request:** clients send POST with a JSON body.

| Name          | In   | Type                                                                                                     | Required | Rules                                                                      |
| ------------- | ---- | -------------------------------------------------------------------------------------------------------- | -------- | -------------------------------------------------------------------------- |
| `insert_data` | body | array of [`tPri_JobRoom`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_jobroom.md) rows | yes      | `uuid`, `uuid_tJob`, `uuid_tRoom`, `fDeleted`. Foreign keys aren't checked |

**Response** `200`: a [Save result object](#save-result-object-php-apis).

**Errors:** see [Save result object](#save-result-object-php-apis).

**Side effects:** writes [`tPri_JobRoom`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_jobroom.md).

## POST ?action=save\_pri\_job\_timecost

Creates or changes time and cost entries on tasks.

* **Auth:** as [`save_pri_job`](#post-actionsave_pri_job).
* **Used by:** iOS, Android (sync)

**Request:** clients send POST with a JSON body.

| Name          | In   | Type                                                                                                             | Required | Rules                                                                                                                                      |
| ------------- | ---- | ---------------------------------------------------------------------------------------------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
| `insert_data` | body | array of [`tPri_JobTimeCost`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_jobtimecost.md) rows | yes      | `uuid`, `uuid_tJob`, `uuid_tBusiness`, `uuid_tUser`, `fTitle`, `fType`, `fTime_ms`, `fCost_std_currency_code`, `fCost_decimal`, `fDeleted` |

**Response** `200`: a [Save result object](#save-result-object-php-apis).

**Errors:** see [Save result object](#save-result-object-php-apis).

**Side effects:** writes [`tPri_JobTimeCost`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_jobtimecost.md).

## POST ?action=save\_pri\_job\_user

Creates or changes task followers.

* **Auth:** as [`save_pri_job`](#post-actionsave_pri_job).
* **Used by:** iOS, Android (sync)

**Request:** clients send POST with a JSON body.

| Name          | In   | Type                                                                                                     | Required | Rules                                                                                                               |
| ------------- | ---- | -------------------------------------------------------------------------------------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------- |
| `insert_data` | body | array of [`tPri_JobUser`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_jobuser.md) rows | yes      | `uuid`, `uuid_tJob`, `uuid_tUserBusiness`, `uuid_tBusiness`, `fLastSeenTs`, `fDeleted`. Foreign keys aren't checked |

**Response** `200`: a [Save result object](#save-result-object-php-apis).

**Errors:** see [Save result object](#save-result-object-php-apis).

**Side effects:** writes [`tPri_JobUser`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_jobuser.md).

## POST ?action=save\_pri\_job\_userassigned

Creates or changes task assignees; the apps unassign someone by saving the row with `fUnassigned` or `fDeleted` set to 1.

* **Auth:** as [`save_pri_job`](#post-actionsave_pri_job).
* **Used by:** iOS, Android (sync)

**Request:** clients send POST with a JSON body.

| Name          | In   | Type                                                                                                                     | Required | Rules                                                                                                       |
| ------------- | ---- | ------------------------------------------------------------------------------------------------------------------------ | -------- | ----------------------------------------------------------------------------------------------------------- |
| `insert_data` | body | array of [`tPri_JobUserAssigned`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_jobuserassigned.md) rows | yes      | `uuid`, `uuid_tJob`, `uuid_tUser`, `uuid_tBusiness`, `fUnassigned`, `fDeleted`. Foreign keys aren't checked |

**Response** `200`: a [Save result object](#save-result-object-php-apis).

**Errors:** see [Save result object](#save-result-object-php-apis).

**Side effects:** writes [`tPri_JobUserAssigned`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_jobuserassigned.md). No notifications: after a successful save the apps notify the assignee themselves.

## POST ?action=save\_pri\_jobjoblink

Creates or changes links between two tasks. The apps also save a task's asset links this way, with the task in `uuid_tJob_a` and the asset in `uuid_tJob_b` (android @ 86068bfeea, `app/src/main/java/gmail/com/snapfixapp/viewModels/AssetSelectionViewModel.kt:116-132`; ios @ aa31967ac8, `SnapFix/Asset/AssetList/AssetListVC+SelectAll.swift:585-593`).

* **Auth:** as [`save_pri_job`](#post-actionsave_pri_job).
* **Used by:** iOS, Android (sync; Android's endpoint list lacks this action, so the URL comes from the build's base URL)

**Request:** clients send POST with a JSON body.

| Name          | In   | Type                                                                                                           | Required | Rules                                                                                    |
| ------------- | ---- | -------------------------------------------------------------------------------------------------------------- | -------- | ---------------------------------------------------------------------------------------- |
| `insert_data` | body | array of [`tPri_JobJobLink`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_jobjoblink.md) rows | yes      | `uuid`, `uuid_tJob_a`, `uuid_tJob_b`, `uuid_tBusiness_a`, `uuid_tBusiness_b`, `fDeleted` |

**Response** `200`: a [Save result object](#save-result-object-php-apis).

**Errors:** see [Save result object](#save-result-object-php-apis).

**Side effects:** writes [`tPri_JobJobLink`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_jobjoblink.md).

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

Logs that a user opened a group; the time is used to count new activity.

* **Auth:** as [`save_pri_job`](#post-actionsave_pri_job); rows can name any user and group.
* **Used by:** iOS, Android (opening a group or asset register)

**Request:** clients send POST with a JSON body.

| Name          | In   | Type                                                                                                                                   | Required | Rules                                                                    |
| ------------- | ---- | -------------------------------------------------------------------------------------------------------------------------------------- | -------- | ------------------------------------------------------------------------ |
| `insert_data` | body | array of [`tPri_Log_BusinessViewedUser`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_log_businessvieweduser.md) rows | yes      | `uuid_tUser`, `uuid_tBusiness`, `fViewedTs`. The `uuid` sent is replaced |

**Response** `200`: a [Save result object](#save-result-object-php-apis).

**Errors:** see [Save result object](#save-result-object-php-apis).

**Side effects:** inserts every row into [`tPri_Log_BusinessViewedUser`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_log_businessvieweduser.md); nothing is ever updated or removed.

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

Logs that a user opened a task; used for read status and the list of viewers.

* **Auth:** as [`save_pri_job`](#post-actionsave_pri_job); rows can name any user and task.
* **Used by:** iOS, Android (opening a task, selecting tasks in a list)

**Request:** clients send POST with a JSON body.

| Name          | In   | Type                                                                                                                         | Required | Rules                                                                                 |
| ------------- | ---- | ---------------------------------------------------------------------------------------------------------------------------- | -------- | ------------------------------------------------------------------------------------- |
| `insert_data` | body | array of [`tPri_Log_JobViewedUser`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_log_jobvieweduser.md) rows | yes      | `uuid_tUser`, `uuid_tBusiness`, `uuid_tJob`, `fViewedTs`. The `uuid` sent is replaced |

**Response** `200`: a [Save result object](#save-result-object-php-apis).

**Errors:** see [Save result object](#save-result-object-php-apis).

**Side effects:** inserts every row into [`tPri_Log_JobViewedUser`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_log_jobvieweduser.md); nothing is ever updated or removed.

## POST ?action=webcust\_list\_jobs

Lists a group's tasks as a given user sees them, with filters, sorting, paging and colour counts; the admin app uses it to pick tasks to move.

* **Auth:** user token, if `JWT_AUTH_ENABLED` is on \[[ASK-12](https://github.com/snapfix/docs/blob/main/ASK.md#ask-12-which-settings-do-the-production-api-servers-use)]; any signed-in user. Lists as the `user_uuid` in the body; the admin app sends the user chosen on its Task Move page.
* **Used by:** webadmin\_angular (Task Move page)

**Request:** the admin app sends POST to `/api/snapfix/web/index.php` with a JSON body.

| Name                                                                                                           | In   | Type                                        | Required           | Rules                                                                                       |
| -------------------------------------------------------------------------------------------------------------- | ---- | ------------------------------------------- | ------------------ | ------------------------------------------------------------------------------------------- |
| `user_uuid`                                                                                                    | body | string                                      | yes                | Must be a member of the group                                                               |
| `business_uuid`                                                                                                | body | string                                      | yes                |                                                                                             |
| `volume_of_records`                                                                                            | body | number                                      | yes                | Page size; 0 or less means 10                                                               |
| `color`                                                                                                        | body | string                                      | no                 | `amber` and `yellow` match both                                                             |
| `sort_by_field`                                                                                                | body | `fCreatedTs`, `fLastActivityTs` or `fTitle` | no                 | Default: last activity. With one of these, `offset` pages; without, `last_fModifiedTs` does |
| `sort_by_order`                                                                                                | body | `ASC` or `DESC`                             | no, default `DESC` |                                                                                             |
| `offset`                                                                                                       | body | number                                      | no                 | With `unread_only` it's put into the SQL as sent                                            |
| `last_fModifiedTs`                                                                                             | body | number                                      | no                 | Returns tasks last active before this time                                                  |
| `search_text`                                                                                                  | body | string                                      | no                 | Matches title, description, reference and chat text                                         |
| `start_date`, `end_date`; `created_start_date`, `created_end_date`; `activity_start_date`, `activity_end_date` | body | date strings                                | no                 | Created or active in the range; created in the range; active in the range                   |
| `uuids_tag1`, `uuids_tag2`, `uuids_tag3`                                                                       | body | arrays of strings                           | no                 | Tag filters                                                                                 |
| `user_uuids_assigned_to`, `user_uuids_following_by`, `user_uuids_created_by`                                   | body | arrays of strings                           | no                 | People filters                                                                              |
| `asset_uuids`, `asset_attribute_value`                                                                         | body | array, string                               | no                 | Asset filters                                                                               |
| `my_tasks`                                                                                                     | body | 1                                           | no                 | Only tasks the user created, follows or is assigned to                                      |
| `with_cost`, `fPriority`, `unread_only`                                                                        | body | 1                                           | no                 | Tasks with time or cost entries; priority tasks; tasks the user hasn't read                 |
| `fArchived`, or `normal_tasks` and `archived_tasks`                                                            | body | 0 or 1                                      | no                 | Default: archived tasks left out                                                            |

Members who may see only their own tasks (not admin, `perJobViewAll` 0) get only tasks they created, follow or are assigned to.

**Response** `200`: `data.jobs` (task fields, the creator and last editor as flat fields and as `created_by` and `modified_by` [User summary objects](#user-summary-object-php-apis), `assignees`, `tags`, `checklist_count`, `checklist_percent`), `offset` (for the next page), `last_fModifiedTs`, and counts by colour in `total`, `planned`, `archived` and `locked`. The answer also has `request_serial`, echoed from the request.

```json
{
  "result": true,
  "message": "Jobs found!",
  "data": {
    "jobs": [ { "job_uuid": "task-123", "fTitle": "Leaking tap in Room 101", "color": "red", "fArchived": 0, "created_by": { "user_uuid": "user-9", "user_name": "Jane Doe" }, "assignees": [], "tags": [ { "uuid_tTag": "tag-3", "fName": "Plumbing" } ], "checklist_count": 4, "checklist_percent": 50 } ],
    "offset": 20,
    "last_fModifiedTs": 1794399000000,
    "total": { "red_job_count": 12, "amber_job_count": 3, "green_job_count": 140, "unknown_job_count": 0 },
    "planned": { "red_job_count": 0, "amber_job_count": 0, "green_job_count": 0, "unknown_job_count": 0 },
    "archived": { "red_job_count": 1, "amber_job_count": 0, "green_job_count": 98, "unknown_job_count": 0 },
    "locked": { "red_job_count": 0, "amber_job_count": 0, "green_job_count": 2, "unknown_job_count": 0 }
  },
  "serverTs": 1794400000000,
  "request_serial": ""
}
```

**Errors:** HTTP 200 with `result: false`: `Data cannot be blank!`; `user_uuid, business_uuid, volume_of_records must be mentioned in the request!` (naming the missing ones); `invalid user`; `invalid user role` (not a member); `Invalid date filters`. Filters that match nothing give an empty list, not an error.

**Side effects:** none.

## POST ?action=webcust\_reset\_job\_signature

Meant to clear a task's signature after its signed checklist is changed. It doesn't: the update is commented out, and the action only returns the task's details \[[ASK-17](https://github.com/snapfix/docs/blob/main/ASK.md#ask-17-should-reset-signature-on-the-web-remove-the-signature)].

* **Auth:** user token, if `JWT_AUTH_ENABLED` is on \[[ASK-12](https://github.com/snapfix/docs/blob/main/ASK.md#ask-12-which-settings-do-the-production-api-servers-use)]. The token's user must be a site admin or a member of the task's group; members who may see only their own tasks must have created, follow or be assigned to it. Adding `debug=1` to the URL skips this check.
* **Used by:** web\_app\_v2 (changing a signed checklist, after the user confirms resetting the signature)

**Request:** the web app sends POST to `/api/snapfix/web/index.php` as multipart form fields.

| Name            | In   | Type   | Required | Rules                              |
| --------------- | ---- | ------ | -------- | ---------------------------------- |
| `user_uuid`     | form | string | yes      | Not used beyond the presence check |
| `business_uuid` | form | string | yes      | Not used beyond the presence check |
| `job_uuid`      | form | string | yes      | A task that isn't deleted          |

**Response** `200`: the task's details: `job` (task fields with `createdby` and `modifiedby` contact details), `assets`, `tags`, `users`, `todos`, `todos_with_section`, `assignees`, `signatures`, `recent_signature`, `times`, `costs`, `last_viewed`, `job_links`, and `job_attributes` for asset tasks. The web app ignores it.

```json
{
  "result": true,
  "message": "Success",
  "data": {
    "job": { "job_uuid": "task-123", "fTitle": "Room 101 inspection", "fTodoSignatureRequired": 1 },
    "recent_signature": { "user_name": "Jane Doe", "signature_url": "https://example.com/signature-123.png" }
  },
  "serverTs": 1794400000000,
  "request_serial": ""
}
```

**Errors:** HTTP 200 with `result: false`: `Data cannot be blank!` (no form fields); `user_uuid, business_uuid, job_uuid must be mentioned in the request!` (naming the missing ones); `invalid job`; `invalid business`; `invalid access!`; `Job not found!`.

**Side effects:** if the task's colour differs from the colour named in its latest status chat message (type 19, text such as `changed color to red`), sets the task's `color` and `uuid_tStatus` in [`tPri_Job`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_job.md) to match that message.

## GET /g-job/{jobToken}

Returns a shared task for the shared task page, by forwarding the token to php-apis.

* **Auth:** app basic (`Authorization: Basic` with apipy's shared login, which the web front ends carry). No user.
* **Used by:** web\_tasks (shared task page)

**Request**

| Name       | In   | Type   | Required | Rules                                                                             |
| ---------- | ---- | ------ | -------- | --------------------------------------------------------------------------------- |
| `jobToken` | path | string | yes      | The share link's token, from [`generate_task_url`](#post-actiongenerate_task_url) |

**Response** `200`: php-apis [`guest_job_data`](#post-actionguest_job_data)'s answer, unchanged: a [Shared task object](#shared-task-object-php-apis) in `data`. apipy calls php-apis with its own basic login.

**Errors:** HTTP 200 `{"result": false, "message": "invalid authentication"}` for a wrong basic login; otherwise php-apis's errors, also with HTTP 200. IP-block errors: [API conventions](https://docs.snapfix.com/engineering-reference/api.md).

**Side effects:** none.

## GET /job-reminder/{job\_uuid}

Returns a task's reminder.

* **Auth:** user token; any signed-in user, for any task.
* **Used by:** web\_app\_v2, iOS, Android, snapfix\_ai\_agent (Simon)

**Request**

| Name       | In   | Type   | Required | Rules                                 |
| ---------- | ---- | ------ | -------- | ------------------------------------- |
| `job_uuid` | path | string | yes      | A task that isn't deleted or archived |

**Response** `200`: a [Reminder object](#reminder-object-apipy). When the task has reminders switched on but no schedule, the answer is a default: daily at 09:05 site time, next at the coming 09:05.

```json
{
  "result": true,
  "message": "success",
  "data": { "type": "daily", "time": "09:00", "timezone": "Europe/Dublin", "nextReminderTimestamp": 1794474000000 },
  "serverTs": 1794400000000
}
```

**Errors:** HTTP 200 with `result: false`: `invalid task`; `task reminder not found!` (reminders off, or the schedule has no next time). Token errors: `401` `{"result": false, "message": "Access token expired"}`, or Flask-JWT-Extended's `{"msg": "..."}` with `401` or `422`.

**Side effects:** none.

## POST /job-reminder/{job\_uuid}

Sets or replaces a task's reminder, as the caller.

* **Auth:** user token; any signed-in user, for any task. When the caller isn't in the task's group, the audit message is written as the group's first admin.
* **Used by:** web\_app\_v2, iOS, Android, snapfix\_ai\_agent (Simon)

**Request:** JSON body.

| Name                 | In   | Type                 | Required | Rules                                                                                                                                                                                                                                                     |
| -------------------- | ---- | -------------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `job_uuid`           | path | string               | yes      | A task that isn't deleted or archived                                                                                                                                                                                                                     |
| `type`               | body | `single` or `daily`  | yes      |                                                                                                                                                                                                                                                           |
| `start_date`         | body | string, `YYYY-MM-DD` | yes      |                                                                                                                                                                                                                                                           |
| `reminder_time`      | body | string, `HH:MM`      | yes      | Site time                                                                                                                                                                                                                                                 |
| `timezone`, `locale` | body | string               | no       | Sent by the web (`src/app/pages/task/task-quick-actions/task-reminder-dialog/task-reminder-dialog.component.ts:200-212`), iOS (`SnapFix/ReminderManager.swift:38`, `:115`) and Simon; stored with the schedule but not used. The site's time zone is used |

**Response** `200`: a [Reminder object](#reminder-object-apipy) with `job_chat`, the audit message added.

```json
{
  "result": true,
  "message": "Reminder information saved successfully",
  "data": {
    "type": "single",
    "time": "14:30",
    "timezone": "Europe/Dublin",
    "nextReminderTimestamp": 1794493800000,
    "job_chat": { "uuid": "chat-12", "uuid_tChatItemType": 56, "fText": "Task reminder set to occur once at 14:30, on 11/11/2026." }
  },
  "serverTs": 1794400000000
}
```

**Errors:** HTTP 200 with `result: false`: `invalid reminder repetitive type`; `invalid reminder start date`; `invalid reminder time`; `invalid user`; `invalid task`; `invalid reminder preferences as we couldnt find any valid date to schedule the task reminder`; `invalid user business` (the caller isn't in the group and the group has no admin). Token errors as for [`GET`](#get-job-reminderjob_uuid).

**Side effects:**

* Inserts a [`schedule_v3`](https://docs.snapfix.com/engineering-reference/db/tables/schedule_v3.md) row (category `tasknotif`, the request in `schedule_json`, the first time in UTC) and marks the task's older `tasknotif` schedules deleted. py\_scheduler sends the reminders.
* Sets `fEnableTaskReminder` 1 and `uuid_tUserEnableTaskReminder` on the task in [`tPri_Job`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_job.md).
* Adds a chat message of type 56 in [`tPri_JobChat`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_jobchat.md), such as "Task reminder set to repeat daily at 09:00, starting from 11/11/2026."

## DELETE /job-reminder/{job\_uuid}

Cancels a task's reminder.

* **Auth:** user token; any signed-in user, for any task.
* **Used by:** web\_app\_v2, iOS, Android, snapfix\_ai\_agent (Simon)

**Request**

| Name       | In   | Type   | Required | Rules                                                     |
| ---------- | ---- | ------ | -------- | --------------------------------------------------------- |
| `job_uuid` | path | string | yes      | A task that isn't deleted or archived, and has a reminder |

**Response** `200`: the audit message added.

```json
{
  "result": true,
  "message": "Reminder cancelled successfully",
  "data": { "job_chat": { "uuid": "chat-13", "uuid_tChatItemType": 57, "fText": "Task reminder cancelled" } },
  "serverTs": 1794400000000
}
```

**Errors:** HTTP 200 with `result: false`: `invalid task`, `task reminder not found!`; `invalid user business`. Token errors as for [`GET`](#get-job-reminderjob_uuid).

**Side effects:** marks the task's `tasknotif` rows in [`schedule_v3`](https://docs.snapfix.com/engineering-reference/db/tables/schedule_v3.md) deleted, sets `fEnableTaskReminder` 0 in [`tPri_Job`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_job.md), and adds a chat message of type 57 "Task reminder cancelled" in [`tPri_JobChat`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_jobchat.md), as the caller or the group's first admin.

## POST /job-reminders

Sets the same reminder on several tasks, in the background after answering.

* **Auth:** user token; any signed-in user, for any task.
* **Used by:** iOS, Android (reminder for tasks chosen in a list)

**Request:** JSON body: `type`, `start_date` and `reminder_time` as in [`POST /job-reminder/{job_uuid}`](#post-job-reminderjob_uuid), plus:

| Name        | In   | Type             | Required | Rules                                                             |
| ----------- | ---- | ---------------- | -------- | ----------------------------------------------------------------- |
| `job_uuids` | body | array of strings | yes      | Must not be empty; tasks that are deleted or archived are skipped |

**Response** `200`: an acceptance only.

```json
{
  "result": true,
  "message": "Request to set reminder for tasks is accepted and will be processed shortly",
  "serverTs": 1794400000000
}
```

**Errors:** HTTP 200 with `result: false`: `invalid reminder repetitive type`; `invalid reminder start date`; `invalid reminder time`; `invalid tasks`. Errors in the background job are only written to the Celery error log.

**Side effects:** a Celery worker does, for each task, the writes of [`POST /job-reminder/{job_uuid}`](#post-job-reminderjob_uuid). It also assigns the caller to each task that has no assignee, in [`tPri_JobUserAssigned`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_jobuserassigned.md), with an "Assigned" chat message (type 44); setting a reminder on one task doesn't do this \[[ASK-18](https://github.com/snapfix/docs/blob/main/ASK.md#ask-18-should-setting-a-reminder-on-several-tasks-assign-the-caller)].

## GET /v4/{user\_uuid}/job/{job\_uuid}

Returns one task with all its child rows.

* **Auth:** user token; any signed-in user. `user_uuid` is only logged, and any task is returned, also a deleted one.
* **Used by:** iOS (`getJobData`), Android (opening a task from a push notification or chat)

**Request**

| Name        | In   | Type   | Required | Rules    |
| ----------- | ---- | ------ | -------- | -------- |
| `user_uuid` | path | string | yes      | Not used |
| `job_uuid`  | path | string | yes      |          |

**Response** `200`: a [Task bundle object](#task-bundle-object-php-apis-apipy) in `data`.

```json
{
  "result": true,
  "message": "success",
  "data": {
    "tPri_Job": { "uuid": "task-123", "fTitle": "Leaking tap in Room 101", "color": "red", "business_name": "Maintenance", "business_image": "" },
    "tPri_JobChat": [],
    "tPri_JobTodo": []
  },
  "serverTs": 1794400000000
}
```

**Errors:** HTTP 200 with `result: false`: `no job found!`. Token errors as for [`GET /job-reminder/{job_uuid}`](#get-job-reminderjob_uuid).

**Side effects:** none.

## POST /v5/{user\_uuid}/jobs

Lists the tasks of the groups named in the body, newest first, with their child rows and colour counts. With exactly one group, it forwards to php-apis.

* **Auth:** user token; any signed-in user. The user in the path isn't compared with the token's user, and the groups in the body aren't checked against the user's memberships. Every task of the groups is returned, also to members who may see only their own tasks.
* **Used by:** iOS (group task download; always one group)

**Request:** JSON body; paging in the query string.

| Name                                                       | In     | Type                             | Required      | Rules                                                                                                                                                                                                    |
| ---------------------------------------------------------- | ------ | -------------------------------- | ------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `user_uuid`                                                | path   | string                           | yes           | Must exist, except on the one-group path                                                                                                                                                                 |
| `offset`                                                   | query  | number                           | no, default 0 |                                                                                                                                                                                                          |
| `limit`                                                    | query  | number                           | no            | Default 200, or 100 on the one-group path                                                                                                                                                                |
| `business_uuids`                                           | body   | array of strings                 | no            | Exactly one: forwarded to php-apis [`read_businessjob_data_v2_proxy`](#post-actionread_businessjob_data_v2_proxy) with `offset`, `limit` and `is_include_archived` only. Left out: the user's own groups |
| `is_include_archived`, `is_include_deleted`, `is_priority` | body   | 0 or 1                           | no            |                                                                                                                                                                                                          |
| `colors`                                                   | body   | array of `red`, `amber`, `green` | no            |                                                                                                                                                                                                          |
| `search_text`                                              | body   | string                           | no            | Matches the task's search text                                                                                                                                                                           |
| `from_date`, `to_date`                                     | body   | number                           | no            | Creation time range, ms                                                                                                                                                                                  |
| `is_my_task`                                               | body   | `"1"`                            | no            | Tasks the user follows                                                                                                                                                                                   |
| `followed_by`, `created_by`, `assigned_to`, `tags`         | body   | arrays of strings                | no            |                                                                                                                                                                                                          |
| `Device-App-Version`                                       | header | string                           | no            | Passed to php-apis on the one-group path                                                                                                                                                                 |

**Response** `200`: `data` is a [Task bundle object](#task-bundle-object-php-apis-apipy) with lists, and `total` a [Task count object](#task-count-object-php-apis-apipy), filled when `offset` is 0. On the one-group path, php-apis's answer is returned unchanged, with `No Data found!` renamed `no job found!`.

```json
{
  "result": true,
  "message": "success",
  "data": {
    "tPri_Job": [ { "uuid": "task-123", "fTitle": "Leaking tap in Room 101", "color": "red", "business_name": "Maintenance" } ],
    "tPri_JobChat": []
  },
  "total": { "jobs": { "red": 12, "amber": 3, "green": 140, "red_archived": 0, "amber_archived": 0, "green_archived": 0, "unknown": 0, "unknown_archived": 0 } },
  "serverTs": 1794400000000
}
```

**Errors:** HTTP 200 with `result: false`: `invalid user`; `user is not associated with any business yet!`; `no jobs found` (`assigned_to` matches nothing); `no job found!`; on the one-group path, php-apis's errors. Token errors as for [`GET /job-reminder/{job_uuid}`](#get-job-reminderjob_uuid).

**Side effects:** none.

## Task object

A task (`AssetJobResource`), as `job` or in `jobs`. The fields marked "when included" come only from the endpoints whose section names them. Times are epoch ms unless noted.

| Field                                        | Type            | Meaning                                                                                                                                                                                                                                              |
| -------------------------------------------- | --------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `uuid`                                       | string          | Task ID                                                                                                                                                                                                                                              |
| `title`                                      | string          | Title (`fTitle`)                                                                                                                                                                                                                                     |
| `shortTitle`                                 | string or null  | `fShortTitle`                                                                                                                                                                                                                                        |
| `largeTitle`                                 | string or null  | Large text shown in place of a photo (`fLargeTextTitle`)                                                                                                                                                                                             |
| `description`                                | string or null  | Notes (`fDescription`)                                                                                                                                                                                                                               |
| `image`                                      | string or null  | Photo URL                                                                                                                                                                                                                                            |
| `enumType`                                   | integer         | Task type (`enum_JobType`): 5 normal, 41 voice, 45 cleaning, 46 inspection, 210 checklist task, and the others in `JobType`                                                                                                                          |
| `assignmentType`                             | integer         | Housekeeping assignment: 0 default, 1 by the AI, 2 by hand                                                                                                                                                                                           |
| `cleaningType`, `cleaningSubType`            | string or null  | Housekeeping clean type and sub type                                                                                                                                                                                                                 |
| `reservation`                                | object or null  | The guest reservation of the task's first room, on task detail and site lists                                                                                                                                                                        |
| `isPriority`                                 | integer         | 1 when the task has a priority (`fPriority`)                                                                                                                                                                                                         |
| `priorityLevel`                              | integer         | 0 none, 5 low, 10 medium, 20 high, 30 emergency; 20 for old tasks with only `fPriority` set                                                                                                                                                          |
| `isFrozen`                                   | integer         | 1 when soft-frozen (`fSoftFreeze`) \[[ASK-7](https://github.com/snapfix/docs/blob/main/ASK.md#ask-7-should-soft-freeze-still-run)]                                                                                                                   |
| `aiTitleSuggested`, `aiBusinessSuggested`    | integer         | 1 when the title or the group came from the AI                                                                                                                                                                                                       |
| `approvalRequired`                           | integer         | -1 follows the group, 0 no, 1 yes; most endpoints replace -1 with the group's setting                                                                                                                                                                |
| `approvalStatus`                             | integer         | -1 none, 0 rejected, 1 approved, 2 pending                                                                                                                                                                                                           |
| `approvedTs`                                 | integer or null | When it was approved                                                                                                                                                                                                                                 |
| `isLocked`, `isArchived`                     | integer         | 1 when locked or archived                                                                                                                                                                                                                            |
| `isPending`                                  | integer         | 1 when pending (`fBacklog`)                                                                                                                                                                                                                          |
| `isSnoozed`, `snoozedReason`, `snoozedNotes` |                 | Snoozed, with reason DND, DNS, Delay or Other                                                                                                                                                                                                        |
| `todoSignatureRequired`                      | integer         | 1 when the checklist needs a signature                                                                                                                                                                                                               |
| `dueDateTs`, `dueDateDailyReminder`          |                 | Due date, and 1 for a daily reminder                                                                                                                                                                                                                 |
| `timerangeStartMs`, `timerangeDurationMs`    | integer or null | Time range start (a full timestamp) and length in ms                                                                                                                                                                                                 |
| `createdTs`                                  | integer         | Created                                                                                                                                                                                                                                              |
| `modifiedTs`                                 | integer         | Last activity (`fJobChatModifiedTs`)                                                                                                                                                                                                                 |
| `greenTs`, `greenByUserUuid`                 |                 | When and by whom it last turned green                                                                                                                                                                                                                |
| `jobAccess`                                  | integer         | Only on linked assets: 1 when the caller can open it                                                                                                                                                                                                 |
| `reference`                                  | string          | Reference number shown to users                                                                                                                                                                                                                      |
| `reminderEnabled`                            | integer         | 1 when the task reminder is on                                                                                                                                                                                                                       |
| `checklistInfo`                              | object          | The checklist template applied: `checklistUuid`, `checklistName`, `checklistDescription`, `checklistNote`, `scope` (site or multiSite), `signatureRequired`, `modifiedTs`; and `todoStarted`, 1 when the task has checklist items                    |
| `todoName`                                   | string or null  | Checklist name                                                                                                                                                                                                                                       |
| `userBusinessName`                           | string or null  | `fUserBusinessName` as stored                                                                                                                                                                                                                        |
| `location`                                   | object          | `lat`, `lng`                                                                                                                                                                                                                                         |
| `attributes`                                 | array           | Asset attributes; empty for tasks                                                                                                                                                                                                                    |
| `business`                                   | object          | When included: the group's `uuid`, `name`, `image`                                                                                                                                                                                                   |
| `businessInfo`                               | object          | When included: `businessUuid`, `businessName`, `businessImage`, `parentName`, `parentImage` (group and site)                                                                                                                                         |
| `assetRegister`                              | object          | When included, on assets: the asset register's `uuid`, `name`, `image`                                                                                                                                                                               |
| `status`                                     | object          | When included: the group status `uuid` and `name`: red (To Do), amber (In Progress) or green (Complete); old tasks may say yellow, which means amber                                                                                                 |
| `subStatus`                                  | object          | When included: `uuid` and `name` (New, In Progress or Closed)                                                                                                                                                                                        |
| `checklistCount`, `checklistPercent`         | integer         | When included: checklist items, and the percentage done                                                                                                                                                                                              |
| `users`                                      | object          | When included: `assigned` and `following` (lists), `createdBy`, `modifiedBy`, `approvedBy`, `backloggedBy`, `snoozedBy` ([task user objects](#task-user-object)), and `lastViewed`: `uuid`, `name`, `image`, `lastViewedTs`, `lastViewedDt` per user |
| `tags`                                       | array           | When included: the group's tag folders, each with `uuid`, `name`, `description`, `mandatory` and the task's `tags` in it (`jobTagUuid`, `uuid`, `name`, `aiNewTag`, `aiSuggested`)                                                                   |
| `rooms`                                      | array           | When included: `uuid`, `name`, `image`, `aiSuggested`, and where loaded `status`, `statusSecondary` and, for occupied rooms, `guestsInfo`: each guest's name, email, phone, address, date of birth, nationality, language and VIP flag               |
| `areas`                                      | array           | When included: `uuid`, `name`, `image`, `aiSuggested`                                                                                                                                                                                                |
| `systems`                                    | array           | When included: linked compliance systems ([Compliance API](https://docs.snapfix.com/engineering-reference/api/compliance.md))                                                                                                                        |
| `time`, `cost`                               | array           | When included: [time and cost objects](#time-and-cost-object) with `user`                                                                                                                                                                            |
| `signature`                                  | object or null  | When included: the latest signature's signer `name` and `fileUrl`                                                                                                                                                                                    |
| `assets`                                     | array           | When included: linked assets                                                                                                                                                                                                                         |
| `parentJob`                                  | object or null  | When included: the linked task (such as the cleaning task of an inspection), as a task object with `tags`, `status`, `rooms`, `users` and `business`                                                                                                 |
| `jobCounts`                                  | object          | Only on assets: linked tasks per status                                                                                                                                                                                                              |

## Task user object

A person on a task (`JobUserResource`), in a task's `users`.

| Field         | Type           | Meaning                                                                  |
| ------------- | -------------- | ------------------------------------------------------------------------ |
| `uuid`        | string         | User ID                                                                  |
| `isSystem`    | boolean        | True for Snapfix's built-in system user                                  |
| `name`        | string         | Name                                                                     |
| `aiSuggested` | integer        | Assignees only: 1 when the AI suggested them                             |
| `image`       | string or null | Photo URL                                                                |
| `date`        | string or null | When they were assigned, started following, or made the change, ISO 8601 |

## Chat item object

A chat line of a task (`ChatItemResource`), as `jobchat` or in `jobchats`. Most task changes return their audit line this way.

| Field                                       | Type           | Meaning                                                                                                                                                        |
| ------------------------------------------- | -------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `uuid`                                      | string         | Chat item ID                                                                                                                                                   |
| `text`                                      | string         | The text. Audit lines are HTML from a template, with names, titles and tag names put in as they are; some start with IDs or values and `,,` that the apps read |
| `type`                                      | integer        | Chat item type (`uuid_tChatItemType`), such as 1 message, 6 task created, 14 tag added, 19 status changed, 44 user assigned, 74 room added, 77 due date set    |
| `fileUrl`, `thumbnailUrl`                   | string or null | Attached file                                                                                                                                                  |
| `titleValueAI`, `transcriptValueAI`         | string or null | Voice notes: AI title and transcript                                                                                                                           |
| `active`                                    |                | `fActive`                                                                                                                                                      |
| `replyUuid`                                 | string or null | The chat item this one replies to                                                                                                                              |
| `jobChatTs`, `createdTs`, `modifiedTs`      | integer        | Epoch ms                                                                                                                                                       |
| `createdAt`, `updatedAt`                    | string         | ISO 8601                                                                                                                                                       |
| `assetUuid`, `assetRegUuid`, `taskLinkUuid` | string         | Asset link lines only                                                                                                                                          |
| `user`                                      | object or null | Author: `uuid`, `name`, `image`, `username` (email or user name), `businessName`                                                                               |
| `reactions`                                 | array          | Where loaded                                                                                                                                                   |

## User object

A user's profile (`UserResource`), in assign and follow responses and as the `user` of time and cost entries. It carries more personal data than those screens show.

| Field                             | Type           | Meaning                         |
| --------------------------------- | -------------- | ------------------------------- |
| `uuid`                            | string         | User ID                         |
| `username`                        | string         | Email or user name              |
| `name`, `firstname`, `lastname`   | string         | Names                           |
| `countryCode`, `mobile`           | string or null | Phone                           |
| `image`                           | string or null | Photo URL                       |
| `address`                         | string or null | Address                         |
| `language`                        | string or null | Language                        |
| `emailVerified`, `mobileVerified` | integer        | 1 when verified                 |
| `notes`                           | string or null | `fNotes`                        |
| `showAiAgentTooltip`              | integer        | Simon tooltip flag              |
| `userType`                        | string         | Admin or User                   |
| `userParentDeleted`               |                | `user_parent_deleted` as loaded |

## Time and cost object

A time or cost entry of a task (`TimeCostResource`).

| Field          | Type           | Meaning                                                         |
| -------------- | -------------- | --------------------------------------------------------------- |
| `uuid`         | string         | Entry ID                                                        |
| `title`        | string         | Title                                                           |
| `time`         | integer        | Milliseconds; left out when 0 or empty                          |
| `description`  | string or null |                                                                 |
| `currencyCode` | string or null | Currency                                                        |
| `cost`         | string or null | Amount                                                          |
| `user`         | object         | Where included: who logged it, as a [user object](#user-object) |

## Save result object (php-apis)

The answer of the generic save actions (`save_pri_job`, `save_job_status_log` and the other `save_*` rows above). They all take `insert_data`, a list of rows of one table, and handle each row the same way:

* A row whose `uuid` exists in the table is updated with every field sent; any other row is inserted. Rows of the status log and the viewed logs always get a new `uuid` and are inserted.
* Field names are column names. The server sets `fServerTs`, and sets `fModifiedTs`, and `fCreatedTs` on inserts, when they're missing or 0.
* Nothing checks who sends a row or which group it belongs to. Field names, and field values that are JSON objects, reach the SQL as sent.
* An `fImage` value that isn't a URL is taken as base64 image data, written to a file on the API server, and replaced with its URL.
* When the server setting `LEGACY_QUEUE_SUPPORT` is on, rows go to [`tPri_Queue`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_queue.md) and are written after the response, and the counts report every row as inserted. The staging copy suggests it's off: the newest `tPri_Queue` row is from 2026-09-07, while the task tables have rows up to 2026-09-24 \[[ASK-12](https://github.com/snapfix/docs/blob/main/ASK.md#ask-12-which-settings-do-the-production-api-servers-use)].
* An empty body answers `{"result": false, "message": "Data cannot be blank!"}` for `save_job_status_log`, `save_pri_job_area`, `save_pri_job_asset`, `save_pri_job_room`, `save_pri_jobjoblink`, `save_pri_businessjobattributerule` and `save_pri_jobattribute` (php-apis @ 238ca4414e, `html/api/snapfix/index.php:1150-1157`, `:1226-1233`), and `{"success": "0", "message": "Data cannot be blank!"}` for the others. A body without `insert_data` fails with HTTP 500.

| Field                        | Type    | Meaning                                                                                              |
| ---------------------------- | ------- | ---------------------------------------------------------------------------------------------------- |
| `result`                     | boolean | `false` when any row failed                                                                          |
| `message`                    | string  | Always "Please find the processed record count"                                                      |
| `total_record_count`         | number  | Rows sent                                                                                            |
| `inserted_record_count`      | number  | Rows inserted                                                                                        |
| `updated_record_count`       | number  | Rows updated                                                                                         |
| `insert_failed_record_count` | number  | Rows that failed to insert, including rows that raised a database error                              |
| `update_failed_record_count` | number  | Rows that failed to update                                                                           |
| `trigger_auto_archive`       | array   | Group settings that switched auto-archive on; always empty for task tables, absent with the queue on |
| `serverTs`                   | number  | Server time in ms, minus 5 seconds                                                                   |

## Table data object (php-apis)

The `data` of the sync loads: one key per table, each a list of rows with every column as stored.

| Field                                    | Type             | Meaning                                                                                                                                 |
| ---------------------------------------- | ---------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
| `<table name>`                           | array            | Rows of that table, such as `tPri_Job` or `tPri_JobChat`                                                                                |
| `tPri_JobTodo_WithSection`               | array            | Checklist items including section headers; `tPri_JobTodo` holds the items without sections                                              |
| `frozen_job_uuids`, `unfrozen_job_uuids` | array of strings | `read_data_v2` and `read_data_v3`, app 6.10.38 or later, when `tPri_Job` is asked for: tasks frozen or unfrozen since `last_updated_ts` |

## Task bundle object (php-apis, apipy)

One task, or a list of tasks, with their child rows; every row has all its columns as stored.

| Field                           | Type                      | Meaning                                                   |
| ------------------------------- | ------------------------- | --------------------------------------------------------- |
| `tPri_Job`                      | object, or array in lists | The task row, plus `business_name` and `business_image`   |
| `tPri_JobChat`                  | array                     | Chat messages that aren't deleted                         |
| `tPri_JobNotif`                 | array                     | Notification times                                        |
| `tPri_JobTag`                   | array                     | Tags                                                      |
| `tPri_JobTimeCost`              | array                     | Time and cost entries                                     |
| `tPri_JobTodo`                  | array                     | Checklist items                                           |
| `tPri_JobTodoMedia`             | array                     | Checklist photos and files                                |
| `tPri_JobAsset`                 | array                     | Linked assets                                             |
| `tPri_JobChat_Reaction`         | array                     | Reactions to chat messages                                |
| `tPri_JobUser`                  | array                     | Followers                                                 |
| `tPri_JobUserAssigned`          | array                     | Assignees, including unassigned ones (`fUnassigned` 1)    |
| `tPri_JobAttribute`             | array                     | Asset attributes                                          |
| `tPri_JobJobLink`               | array                     | Links from this task to other tasks                       |
| `tPri_UserBusiness`, `tPri_Tag` | array                     | Copy and move only: memberships and tags the copy created |

## Task count object (php-apis, apipy)

`total.jobs`: a group's tasks by colour. php-apis counts every task that isn't deleted; apipy counts the tasks that match the request's filters.

| Field                                                                                                                 | Type   | Meaning                                           |
| --------------------------------------------------------------------------------------------------------------------- | ------ | ------------------------------------------------- |
| `red`, `amber`, `green`                                                                                               | number | Tasks of that colour, archived ones included      |
| `red_archived`, `amber_archived`, `green_archived`                                                                    | number | Archived tasks of that colour                     |
| `red_frozen`, `amber_frozen`, `green_frozen`, `red_frozen_archived`, `amber_frozen_archived`, `green_frozen_archived` | number | php-apis only, app 6.10.38 or later: frozen tasks |
| `unknown`, `unknown_archived`, `unknown_frozen`                                                                       | number | Tasks with any other colour                       |

## Shared task object (php-apis)

The `data` of [`guest_job_data`](#post-actionguest_job_data), shown on the shared task page. It names everyone involved in the task with their email address and phone number, and includes deleted chat messages.

| Field                                            | Type          | Meaning                                                                                                                                                                                                                                                                                             |
| ------------------------------------------------ | ------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `expiry_ts`                                      | number        | When the link expires, ms                                                                                                                                                                                                                                                                           |
| `parent_name`, `business_name`, `business_image` | string        | Site and group                                                                                                                                                                                                                                                                                      |
| `job`                                            | object        | Title, large text title, description, image, colour, status and sub-status names, planned flag, job type, location, priority, lock and archive flags, reference, chat count and times; `createdby` and `modifiedby` with name, email and phone; `type` (`task`, or `asset` for job types 43 and 44) |
| `asset_attributes`                               | array         | Asset tasks only: attribute name, category, key, value, order, value type and whether it's mandatory                                                                                                                                                                                                |
| `tags`                                           | array         | `tag_name`, `tag_header_name`                                                                                                                                                                                                                                                                       |
| `users`                                          | array         | Followers, as [User summary objects](#user-summary-object-php-apis)                                                                                                                                                                                                                                 |
| `todos`                                          | array         | Checklist items with their answers, NFC and notes fields, and `media` (`fType`, `media_url`, `thumb_url`)                                                                                                                                                                                           |
| `assignees`                                      | array         | [User summary objects](#user-summary-object-php-apis)                                                                                                                                                                                                                                               |
| `signatures`, `recent_signature`                 | array, object | Signers as [User summary objects](#user-summary-object-php-apis) with `signature_url`, newest first; `recent_signature` is the first or `null`                                                                                                                                                      |
| `times`                                          | array         | Time entries: the user, `time_in_ms`, `time_title`, `time_description`, `time_created_ms`, and cost fields                                                                                                                                                                                          |
| `costs`                                          | array         | Cost entries: `cost_uuid`, the user with `user_uuid`, `currency_code`, `cost`, `cost_title`, `cost_description`, `cost_created_ms`                                                                                                                                                                  |
| `last_viewed`                                    | array         | Viewers with `last_viewed_ts` and `last_viewed_dt`                                                                                                                                                                                                                                                  |
| `chat`                                           | array         | Every chat message, oldest change first: type, text, file URLs, times, the author's business name, `createdby` and `modifiedby` (name, email, phone, photo), and `chat_uuid_proxy` and `reply_chat_uuid_proxy`, new IDs made for each response so that replies can be matched                       |

## User summary object (php-apis)

The person fields several php-apis task answers include.

| Field                     | Type   | Meaning                                              |
| ------------------------- | ------ | ---------------------------------------------------- |
| `user_name`               | string | First and last name                                  |
| `fImage`                  | string | Photo URL                                            |
| `fFirstName`, `fLastName` | string |                                                      |
| `staff_username`          | string | Username of staff who sign in without email or phone |
| `fUsername`               | string | Email address                                        |
| `fCountryCode`, `fMobile` | number | Mobile phone number                                  |

## Reminder object (apipy)

A task's reminder, from apipy's `/job-reminder` routes.

| Field                   | Type   | Meaning                                                                                                                                        |
| ----------------------- | ------ | ---------------------------------------------------------------------------------------------------------------------------------------------- |
| `type`                  | string | `single` or `daily`                                                                                                                            |
| `time`                  | string | Time of day as saved, `HH:MM` in site time                                                                                                     |
| `timezone`              | string | The site's time zone, such as `Europe/Dublin`                                                                                                  |
| `nextReminderTimestamp` | number | Next reminder, ms since 1970                                                                                                                   |
| `job_chat`              | object | `POST` only: the audit chat message added, as a [`tPri_JobChat`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_jobchat.md) row |

## Task list filters

Body fields that narrow the task lists, and the bulk actions that reuse them. Each list accepts the set named in its section: "group lists" are `POST /v1/app/tasks/list`, `POST /v1/app/tasks/statuses` and the `all/*` actions; "site lists" are `list-by-parent`, `list-by-multiSite`, `list-for-checklist` and `statuses-by-parent`. Booleans take 1 or 0 (form data) or true or false (JSON). Dates are `Y-m-d` days in the time zone of the `device-tz-offset` header (such as `GMT+0100`), UTC without it.

| Name                                                                                                                                                                                 | Type              | Lists                   | Rules                                                                                                                                                                      |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------------- | ----------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `searchText`                                                                                                                                                                         | string            | all                     | Group lists match the status, reference, title and description, chat messages and asset attribute values; site lists match the title, large text, group name and reference |
| `colors`                                                                                                                                                                             | array of strings  | site                    | red, amber, green                                                                                                                                                          |
| `normalTasks`, `archivedTasks`                                                                                                                                                       | boolean           | all                     | Only `archivedTasks`: archived tasks only; both: archived and current; neither: current only                                                                               |
| `unreadTasks`                                                                                                                                                                        | boolean           | all                     | Only tasks with activity since the caller last viewed them                                                                                                                 |
| `priority`                                                                                                                                                                           | boolean           | all                     | Only tasks with priority (or only without, for false)                                                                                                                      |
| `priorityLevel`                                                                                                                                                                      | array of integers | all                     | 0, 1, 5, 10, 20, 30; 20 also matches old tasks with only `fPriority`                                                                                                       |
| `withCost`                                                                                                                                                                           | boolean           | group                   | Only tasks with time or cost entries                                                                                                                                       |
| `tags`                                                                                                                                                                               | array of strings  | group, site             | Tag IDs; a task needs one of the listed tags from each folder named                                                                                                        |
| `rooms`, `areas`                                                                                                                                                                     | array of strings  | all                     | Room or area IDs                                                                                                                                                           |
| `assets`                                                                                                                                                                             | array of strings  | group                   | Linked asset IDs                                                                                                                                                           |
| `assetAttributeValue`                                                                                                                                                                | string            | group                   | Linked assets with an attribute value containing this                                                                                                                      |
| `createdStartDate`, `createdEndDate`                                                                                                                                                 | date              | all                     | Creation day range; both or neither, after 1970-01-01, end on or after start                                                                                               |
| `updatedStartDate`, `updatedEndDate`                                                                                                                                                 | date              | all                     | Last activity day range, same rules                                                                                                                                        |
| `dueStartDate`, `dueEndDate`                                                                                                                                                         | date              | all                     | Due day range, same rules                                                                                                                                                  |
| `dueToday`, `overDue`                                                                                                                                                                | boolean           | all                     | Due today; overdue (due date passed and not turned green before it). With each other and with the due range, they combine with OR                                          |
| `createdBy`, `assignedTo`                                                                                                                                                            | array of strings  | all                     | User IDs                                                                                                                                                                   |
| `updatedBy`                                                                                                                                                                          | array of strings  | site                    | Users who wrote in the task's chat                                                                                                                                         |
| `plannedTasks`                                                                                                                                                                       | boolean           | group                   | Only planned tasks (true) or no planned tasks (false)                                                                                                                      |
| `approvalTasks`                                                                                                                                                                      | array of integers | group, `list-by-parent` | Tasks needing approval with these approval statuses (0, 1, 2)                                                                                                              |
| `housekeepingTasks`, `inspectionTasks`                                                                                                                                               | boolean           | site                    | Only cleaning or inspection tasks                                                                                                                                          |
| `parents`                                                                                                                                                                            | array of strings  | `list-by-multiSite`     | Site IDs                                                                                                                                                                   |
| `queued`, `roomStatus`, `stayoverClean`, `departureClean`, `correctionClean`, `touchupClean`, `studioTidy`, `trashAndTowel`, `preArrivalBlitz`, `inspections`, `occupied`, `arrival` |                   | `list-by-parent`        | Housekeeping filters ([Housekeeping API](https://docs.snapfix.com/engineering-reference/api/housekeeping.md))                                                              |

**Paging:** `limit` (page size) and `offset` (page number, from 1) go in the query string. With `limit`, lists return `pagination`: `total`, `perPage`, `currentPage`, `lastPage`, `from`, `to`. Without it, most lists return every match.

## Task permissions

The checks the endpoints above name. They use the caller's relation to the task's group, with its role and permissions, in [`tPri_UserBusiness`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_userbusiness.md).

* **Member:** has a current relation to the group. Multi-site users also pass the permission checks below in every group of their sites, with default permissions and the role User, but not the endpoints that require membership.
* **Read-only:** a member whose onboarding in the group is inactive.
* **Can see the task:** group admin, the "view all tasks" permission (`perJobViewAll`), the task's creator, a follower or an assignee. Group, room and area lists show only these tasks, except to multi-site users of the site, who see them all; site lists show only these tasks, and only in groups the caller is a member of.
* **Can change the task:** can see it and isn't read-only.
* **Named permissions:** "create task" `perJobCreateNew`, "delete task" `perJobDelete`, "archive task" `perJobArchive`, "assign user" `perAssignUser`, and "move to" `perJobMoveToRed`, `perJobMoveToAmber` and `perJobMoveToGreen`; group admins pass them all, read-only members none. When the caller isn't a member at all, these checks answer `403` with the text `messages.access_denied`.
* **Editable:** many changes need a task that isn't locked, isn't archived, and has no time range or is inside it now; otherwise they answer `400` "The task can not be updated". Exceptions: `lock` and `archive` work on archived tasks; time range changes and deletes ignore the time range; inspection tasks can be assigned while locked or outside it; housekeeping tasks can change status or be archived outside it; tasks assigned by the AI or by hand (`assignmentType` 1 or 2) ignore it.

## Common side effects

What the endpoints above mean by these words.

* **Audit line:** a row in [`tPri_JobChat`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_jobchat.md) that shows the change in the task's chat, written with the caller's name. Its text is HTML with the names put in as they are.
* **Viewed rows:** a new row for the caller in [`tPri_Log_JobViewedUser`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_log_jobvieweduser.md) (the task) and [`tPri_Log_BusinessViewedUser`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_log_businessvieweduser.md) (its group). Every call inserts new rows; unread state comes from the latest.
* **Touch of the task:** `fModifiedTs` in [`tPri_Job`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_job.md) becomes now.
* **Pushes:** queued `SendFcmNotification` jobs to Firebase Cloud Messaging. A push goes to the devices of the group's admins, members with "view all tasks", and the task's assignees and followers ("the task's people"). It is shown or silent depending on each person's group mute and notification settings, and always silent on the caller's own devices. A silent update push makes the apps reload. Endpoints that don't name a push type send their silent update push only when the server setting `VIA_QUEUE` is on \[[ASK-12](https://github.com/snapfix/docs/blob/main/ASK.md#ask-12-which-settings-do-the-production-api-servers-use)].
* **Firebase task counter:** `task_count` under `parentPackageUsage/<site>` in the Firebase Realtime Database, through the queued `FirebaseRealTimeDatabase` job.
* **AI log:** rows in [`log_ai_job`](https://docs.snapfix.com/engineering-reference/db/tables/log_ai_job.md) that record what the AI suggested and what the user kept, only when the site's `fAiSuggestionEnabled` is on.
* **Request log:** after every call, a queued row in that day's `apilog_YYYY_MM_DD` table of the log database, with the request (files left out, `password` fields masked), the headers, the decoded token, and the whole response when it is under about 100 KB.

## Common errors

Every endpoint above answers `{ "status": "success", "message": "...", "data": ... }` on success and `{ "status": "error", "message": "..." }` on failure, with these codes besides its own:

* `401`: no token, a bad or expired token, a token that isn't an access token, or a blocked token.
* `428` "You must set a new password to proceed.": the user signed in with a temporary password.
* `409` when the user's email or phone number still needs verifying: "In order to continue using all Snapfix features, your email address or phone number needs to be verified."
* `400` "There is an issue with the service you are seeking for. ... reference code: X": a blacklisted IP address, country, phone number, email or user.
* `400`: a malformed `X-API-Version` header, or a version other than 1.0.x.
* `429`: a throttling rule for the route was hit, while throttling is on.
* `422`: validation; the message is the first failed rule's text, with " (and N more errors)" when more rules fail, and no list of fields ([API](https://docs.snapfix.com/engineering-reference/api.md#responses)).
* `404` "Resource not found": an ID that doesn't exist.
* `500` "An unexpected error occurred. Please try again later." for server errors, and `400` "Something went wrong" for other unexpected ones. With `APP_DEBUG` on, error bodies also carry `file`, `line` and `backtrace`.


---

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