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

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

Checklist templates for sites, multi-sites and the Snapfix library, their folders and permissions, the tasks and planned tasks they are attached to, and the checklist items inside each task, with their notes and photos.

* **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`
* **Auth:** api\_php\_live\_v2: user token (authpy access JWT in `Authorization: Bearer`). Each route then checks the caller against the site, multi-site or group it works on, as its section says ([access checks](#checklist-access-checks)); the template and activity reads and the routes that attach templates to tasks check less. php-apis: user token (Bearer JWT, checked only when `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)]), otherwise the shared Basic login. The save actions act on the user named in the rows, not the token's user, and check no access to the rows they write. `read_parent_checklist_data` takes the user from the token payload and answers for any site named.
* **Used by:** web\_app\_v2 (every api\_php\_live\_v2 route with a caller, and no php-apis action); iOS and Android (the php-apis save actions and `read_parent_checklist_data`, and no api\_php\_live\_v2 checklist route); 35 of the 91 endpoints have no known caller

The product side is in [checklists](https://docs.snapfix.com/product/features/checklists/checklists.md) and [checklist templates](https://docs.snapfix.com/product/features/checklists/checklist-templates.md).

Two systems hold checklist data. The web reads and writes through api\_php\_live\_v2. The apps keep a local copy: they load a site's templates through `read_parent_checklist_data` and send their changes to the php-apis save actions, which write the same tables.

`{scope}` is `site` or `multiSite`, a route constraint; any other value gives `404`. Site templates, folders and permissions live in the `tPri_CL_Site*` tables, keyed by site (`uuid_tParent`); multi-site ones live in the `tPri_CL_MultiSite*` tables, keyed by multi-site (`uuid_tMultiSite`). Every template points at one [`tPri_CL`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_cl.md) checklist, whose [`tPri_CL_Item`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_cl_item.md) rows are its sections and items. The routes without a scope (`/library`, `/tags` and `/folders`) work on the Snapfix library. The request rules see the path's `scope`, because api\_php\_live\_v2 merges path parameters into the request ([API conventions](https://docs.snapfix.com/engineering-reference/api.md#requests)).

| Method | Path                                                                                                                                                                               | Service            | Purpose                                                                          |
| ------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------ | -------------------------------------------------------------------------------- |
| GET    | `/v1/app/checklists/folders`                                                                                                                                                       | api\_php\_live\_v2 | List the library's folders; checks nothing beyond the token (no caller)          |
| POST   | `/v1/app/checklists/folders`                                                                                                                                                       | api\_php\_live\_v2 | Create a library folder (no caller)                                              |
| GET    | `/v1/app/checklists/folders/{uuid}`                                                                                                                                                | api\_php\_live\_v2 | Get a library folder (no caller)                                                 |
| PUT    | `/v1/app/checklists/folders/{uuid}`                                                                                                                                                | api\_php\_live\_v2 | Change a library folder (no caller)                                              |
| DELETE | `/v1/app/checklists/folders/{uuid}`                                                                                                                                                | api\_php\_live\_v2 | Delete a library folder (no caller)                                              |
| POST   | [`/v1/app/checklists/library`](#post-v1appchecklistslibrary)                                                                                                                       | api\_php\_live\_v2 | List library checklists                                                          |
| GET    | [`/v1/app/checklists/library/{uuid}`](#get-v1appchecklistslibraryuuid)                                                                                                             | api\_php\_live\_v2 | Get a library checklist with its items                                           |
| GET    | [`/v1/app/checklists/multiSite/jobs/{templateUuid}/parent/{parentUuid}`](#get-v1appchecklistsmultisitejobstemplateuuidparentparentuuid)                                            | api\_php\_live\_v2 | List a site's tasks for a multi-site checklist template                          |
| PUT    | [`/v1/app/checklists/multiSite/permissions/group`](#put-v1appchecklistsmultisitepermissionsgroup)                                                                                  | api\_php\_live\_v2 | Show or hide a multi-site checklist template for a group                         |
| PUT    | [`/v1/app/checklists/multiSite/permissions/group/all`](#put-v1appchecklistsmultisitepermissionsgroupall)                                                                           | api\_php\_live\_v2 | Show or hide a multi-site checklist template for every group of a site           |
| PUT    | [`/v1/app/checklists/multiSite/permissions/parent`](#put-v1appchecklistsmultisitepermissionsparent)                                                                                | api\_php\_live\_v2 | Show or hide a multi-site checklist template for a site                          |
| PUT    | [`/v1/app/checklists/multiSite/permissions/parent/all`](#put-v1appchecklistsmultisitepermissionsparentall)                                                                         | api\_php\_live\_v2 | Show or hide a multi-site checklist template for every site                      |
| POST   | `/v1/app/checklists/multiSite/templates/download/site`                                                                                                                             | api\_php\_live\_v2 | Copy a site checklist template into the multi-site (no caller)                   |
| GET    | [`/v1/app/checklists/multiSite/{templateUuid}/permissions/{multiSiteUuid}`](#get-v1appchecklistsmultisitetemplateuuidpermissionsmultisiteuuid)                                     | api\_php\_live\_v2 | List the sites of a multi-site with a checklist template's visibility            |
| GET    | [`/v1/app/checklists/multiSite/{templateUuid}/permissions/{multiSiteUuid}/groups/{parentUuid}`](#get-v1appchecklistsmultisitetemplateuuidpermissionsmultisiteuuidgroupsparentuuid) | api\_php\_live\_v2 | List a site's groups with a multi-site checklist template's visibility           |
| GET    | [`/v1/app/checklists/site/folders/group/{groupUuid}`](#get-v1appchecklistssitefoldersgroupgroupuuid)                                                                               | api\_php\_live\_v2 | List the folders of a group's site, counting the templates the group can see     |
| GET    | [`/v1/app/checklists/site/folders/{parentUuid}/multiSite`](#get-v1appchecklistssitefoldersparentuuidmultisite)                                                                     | api\_php\_live\_v2 | List the folders of a site's multi-site, counting the templates the site can see |
| PUT    | [`/v1/app/checklists/site/permissions/group`](#put-v1appchecklistssitepermissionsgroup)                                                                                            | api\_php\_live\_v2 | Show or hide a site checklist template for a group                               |
| PUT    | [`/v1/app/checklists/site/permissions/group/all`](#put-v1appchecklistssitepermissionsgroupall)                                                                                     | api\_php\_live\_v2 | Show or hide a site checklist template for the caller's groups of the site       |
| POST   | [`/v1/app/checklists/site/templates/download/multiSite`](#post-v1appchecklistssitetemplatesdownloadmultisite)                                                                      | api\_php\_live\_v2 | Copy multi-site checklist templates into a site                                  |
| GET    | [`/v1/app/checklists/site/templates/group/{groupUuid}/list-by-folder/{folderUuid}`](#get-v1appchecklistssitetemplatesgroupgroupuuidlist-by-folderfolderuuid)                       | api\_php\_live\_v2 | List the site checklist templates in a folder that a group can use               |
| GET    | [`/v1/app/checklists/site/templates/{parentUuid}/list-by-folder/{folderUuid}/multiSite`](#get-v1appchecklistssitetemplatesparentuuidlist-by-folderfolderuuidmultisite)             | api\_php\_live\_v2 | List the multi-site checklist templates in a folder that a site can use          |
| GET    | [`/v1/app/checklists/site/{templateUuid}/permissions/{parentUuid}/groups`](#get-v1appchecklistssitetemplateuuidpermissionsparentuuidgroups)                                        | api\_php\_live\_v2 | List the caller's groups of a site with a site checklist template's visibility   |
| GET    | [`/v1/app/checklists/tags`](#get-v1appcheckliststags)                                                                                                                              | api\_php\_live\_v2 | List the library's checklist tags                                                |
| GET    | [`/v1/app/checklists/{entityUuid}/activities`](#get-v1appchecklistsentityuuidactivities)                                                                                           | api\_php\_live\_v2 | List a checklist template's activity log                                         |
| GET    | [`/v1/app/checklists/{scope}/folders`](#get-v1appchecklistsscopefolders)                                                                                                           | api\_php\_live\_v2 | List checklist folders                                                           |
| POST   | [`/v1/app/checklists/{scope}/folders`](#post-v1appchecklistsscopefolders)                                                                                                          | api\_php\_live\_v2 | Create a checklist folder                                                        |
| GET    | `/v1/app/checklists/{scope}/folders/{uuid}`                                                                                                                                        | api\_php\_live\_v2 | Get a checklist folder (no caller)                                               |
| PUT    | [`/v1/app/checklists/{scope}/folders/{uuid}`](#put-v1appchecklistsscopefoldersuuid)                                                                                                | api\_php\_live\_v2 | Change a checklist folder                                                        |
| DELETE | [`/v1/app/checklists/{scope}/folders/{uuid}`](#delete-v1appchecklistsscopefoldersuuid)                                                                                             | api\_php\_live\_v2 | Delete a checklist folder                                                        |
| POST   | [`/v1/app/checklists/{scope}/jobs`](#post-v1appchecklistsscopejobs)                                                                                                                | api\_php\_live\_v2 | Put a checklist template on tasks, replacing their checklists                    |
| POST   | [`/v1/app/checklists/{scope}/jobs/all`](#post-v1appchecklistsscopejobsall)                                                                                                         | api\_php\_live\_v2 | Put a checklist template on a group's tasks that match a filter (`storeAllJobs`) |
| POST   | [`/v1/app/checklists/{scope}/jobs/delete`](#post-v1appchecklistsscopejobsdelete)                                                                                                   | api\_php\_live\_v2 | Take a checklist template off tasks                                              |
| GET    | [`/v1/app/checklists/{scope}/jobs/{templateUuid}/group/{businessUuid}`](#get-v1appchecklistsscopejobstemplateuuidgroupbusinessuuid)                                                | api\_php\_live\_v2 | List a group's tasks for a checklist template                                    |
| POST   | [`/v1/app/checklists/{scope}/schedules`](#post-v1appchecklistsscopeschedules)                                                                                                      | api\_php\_live\_v2 | Put a checklist template on planned tasks                                        |
| POST   | [`/v1/app/checklists/{scope}/schedules/delete`](#post-v1appchecklistsscopeschedulesdelete)                                                                                         | api\_php\_live\_v2 | Take a checklist template off planned tasks                                      |
| GET    | `/v1/app/checklists/{scope}/templates`                                                                                                                                             | api\_php\_live\_v2 | List the checklist templates of a site or multi-site (no caller)                 |
| POST   | [`/v1/app/checklists/{scope}/templates`](#post-v1appchecklistsscopetemplates)                                                                                                      | api\_php\_live\_v2 | Create a checklist template                                                      |
| POST   | [`/v1/app/checklists/{scope}/templates/copy`](#post-v1appchecklistsscopetemplatescopy)                                                                                             | api\_php\_live\_v2 | Copy checklist templates                                                         |
| POST   | [`/v1/app/checklists/{scope}/templates/download`](#post-v1appchecklistsscopetemplatesdownload)                                                                                     | api\_php\_live\_v2 | Create a checklist template from a library checklist                             |
| GET    | [`/v1/app/checklists/{scope}/templates/list-by-folder/{folderUuid}`](#get-v1appchecklistsscopetemplateslist-by-folderfolderuuid)                                                   | api\_php\_live\_v2 | List the checklist templates in a folder                                         |
| POST   | [`/v1/app/checklists/{scope}/templates/move`](#post-v1appchecklistsscopetemplatesmove)                                                                                             | api\_php\_live\_v2 | Move checklist templates                                                         |
| PUT    | [`/v1/app/checklists/{scope}/templates/{templateUuid}`](#put-v1appchecklistsscopetemplatestemplateuuid)                                                                            | api\_php\_live\_v2 | Change a checklist template                                                      |
| DELETE | [`/v1/app/checklists/{scope}/templates/{templateUuid}`](#delete-v1appchecklistsscopetemplatestemplateuuid)                                                                         | api\_php\_live\_v2 | Delete a checklist template                                                      |
| GET    | [`/v1/app/checklists/{scope}/templates/{uuid}`](#get-v1appchecklistsscopetemplatesuuid)                                                                                            | api\_php\_live\_v2 | Get a checklist template with its items                                          |
| POST   | [`/v1/app/todo-medias`](#post-v1apptodo-medias)                                                                                                                                    | api\_php\_live\_v2 | Add a photo or video to a checklist item                                         |
| DELETE | [`/v1/app/todo-medias/{uuid}`](#delete-v1apptodo-mediasuuid)                                                                                                                       | api\_php\_live\_v2 | Delete a checklist item's photo or video                                         |
| GET    | [`/v1/app/todos`](#get-v1apptodos)                                                                                                                                                 | api\_php\_live\_v2 | List a task's checklist items                                                    |
| POST   | `/v1/app/todos`                                                                                                                                                                    | api\_php\_live\_v2 | Create checklist items (no caller)                                               |
| DELETE | `/v1/app/todos`                                                                                                                                                                    | api\_php\_live\_v2 | Delete checklist items (no caller)                                               |
| PUT    | [`/v1/app/todos/check/{uuid}`](#put-v1apptodoscheckuuid)                                                                                                                           | api\_php\_live\_v2 | Check a checklist item                                                           |
| POST   | `/v1/app/todos/file`                                                                                                                                                               | api\_php\_live\_v2 | Upload a file to a checklist item; always fails the version check (no caller)    |
| POST   | [`/v1/app/todos/multi`](#post-v1apptodosmulti)                                                                                                                                     | api\_php\_live\_v2 | Add, change and delete a task's checklist items                                  |
| GET    | [`/v1/app/todos/reset`](#get-v1apptodosreset)                                                                                                                                      | api\_php\_live\_v2 | Clear every answer and photo of a task's checklist                               |
| POST   | `/v1/app/todos/section-copy`                                                                                                                                                       | api\_php\_live\_v2 | Copy a checklist section (no caller)                                             |
| PUT    | `/v1/app/todos/settings/{uuid}`                                                                                                                                                    | api\_php\_live\_v2 | Change a checklist item's settings (no caller)                                   |
| POST   | `/v1/app/todos/sort`                                                                                                                                                               | api\_php\_live\_v2 | Sort checklist items (no caller)                                                 |
| PUT    | [`/v1/app/todos/uncheck/{uuid}`](#put-v1apptodosuncheckuuid)                                                                                                                       | api\_php\_live\_v2 | Uncheck a checklist item                                                         |
| PUT    | [`/v1/app/todos/{uuid}`](#put-v1apptodosuuid)                                                                                                                                      | api\_php\_live\_v2 | Answer a checklist item, or change its note                                      |
| ANY    | `?action=create_pri_job_todo`                                                                                                                                                      | php-apis           | Create checklist items, generic table action (no caller)                         |
| ANY    | `?action=delete_pri_job_todo`                                                                                                                                                      | php-apis           | Delete checklist items, generic table action (no caller)                         |
| ANY    | `?action=modify_pri_job_todo`                                                                                                                                                      | php-apis           | Change checklist items, generic table action (no caller)                         |
| POST   | [`?action=read_parent_checklist_data`](#post-actionread_parent_checklist_data)                                                                                                     | php-apis           | Read sites' checklist rows for the apps' local database                          |
| ANY    | `?action=read_pri_job_todo`                                                                                                                                                        | php-apis           | Read checklist items by UUID, generic table action (no caller)                   |
| ANY    | `?action=read_pri_job_todo_media`                                                                                                                                                  | php-apis           | Read checklist item media by UUID, generic table action (no caller)              |
| POST   | [`?action=save_cl`](#post-actionsave_cl)                                                                                                                                           | php-apis           | Save checklists (app sync)                                                       |
| POST   | [`?action=save_cl_item`](#post-actionsave_cl_item)                                                                                                                                 | php-apis           | Save checklist template items (app sync)                                         |
| ANY    | `?action=save_cl_item_media`                                                                                                                                                       | php-apis           | Save checklist item media (no caller)                                            |
| POST   | [`?action=save_cl_item_notes`](#post-actionsave_cl_item_notes)                                                                                                                     | php-apis           | Save checklist template item notes (app sync)                                    |
| ANY    | `?action=save_cl_multisite_template_permissions`                                                                                                                                   | php-apis           | Save multi-site checklist template permissions (no caller)                       |
| POST   | [`?action=save_cl_permissions`](#post-actionsave_cl_permissions)                                                                                                                   | php-apis           | Save checklist permissions (app sync)                                            |
| POST   | [`?action=save_cl_site_template`](#post-actionsave_cl_site_template)                                                                                                               | php-apis           | Save site checklist templates (app sync)                                         |
| POST   | [`?action=save_cl_site_template_permissions`](#post-actionsave_cl_site_template_permissions)                                                                                       | php-apis           | Save site checklist template permissions (app sync)                              |
| ANY    | `?action=save_cl_site_template_virtual_folders`                                                                                                                                    | php-apis           | Save the virtual folders of site checklist templates (no caller)                 |
| POST   | [`?action=save_job_cl_template`](#post-actionsave_job_cl_template)                                                                                                                 | php-apis           | Save a task's checklist template link (app sync)                                 |
| POST   | [`?action=save_pri_job_todo`](#post-actionsave_pri_job_todo)                                                                                                                       | php-apis           | Save the checklist items of tasks (app sync)                                     |
| POST   | [`?action=save_pri_job_todo_media`](#post-actionsave_pri_job_todo_media)                                                                                                           | php-apis           | Save the photos and videos of task checklist items (app sync)                    |
| POST   | [`?action=save_pri_job_todo_notes`](#post-actionsave_pri_job_todo_notes)                                                                                                           | php-apis           | Save the notes of task checklist items (app sync)                                |
| ANY    | `?action=webcust_create_jobtodo`                                                                                                                                                   | php-apis web       | Create a checklist item (no caller)                                              |
| ANY    | `?action=webcust_create_jobtodo_media`                                                                                                                                             | php-apis web       | Add media to a checklist item (no caller)                                        |
| ANY    | `?action=webcust_delete_jobtodo`                                                                                                                                                   | php-apis web       | Delete a checklist item (no caller)                                              |
| ANY    | `?action=webcust_delete_jobtodo_media`                                                                                                                                             | php-apis web       | Delete a checklist item's media (no caller)                                      |
| ANY    | `?action=webcust_delete_jobtodos`                                                                                                                                                  | php-apis web       | Delete checklist items (no caller)                                               |
| ANY    | `?action=webcust_jobtodo_check`                                                                                                                                                    | php-apis web       | Check a checklist item (no caller)                                               |
| ANY    | `?action=webcust_jobtodo_uncheck`                                                                                                                                                  | php-apis web       | Uncheck a checklist item (no caller)                                             |
| ANY    | `?action=webcust_list_todos_v2`                                                                                                                                                    | php-apis web       | List checklist items (v2) (no caller)                                            |
| ANY    | `?action=webcust_reset_checklist`                                                                                                                                                  | php-apis web       | Reset a checklist (no caller)                                                    |
| ANY    | `?action=webcust_update_jobtodo_mandatory`                                                                                                                                         | php-apis web       | Set whether a checklist item is mandatory (no caller)                            |
| ANY    | `?action=webcust_update_jobtodo_media`                                                                                                                                             | php-apis web       | Change a checklist item's media (no caller)                                      |
| ANY    | `?action=webcust_update_jobtodo_name`                                                                                                                                              | php-apis web       | Rename a checklist item (no caller)                                              |
| ANY    | `?action=webcust_update_jobtodo_sortorder`                                                                                                                                         | php-apis web       | Change the order of checklist items (no caller)                                  |

Notes on the table:

* **No caller** means that no client code sends the request. The web has a service method for `GET /v1/app/checklists/{scope}/folders/{uuid}` (`ChecklistTemplateHttpService.getSingleChecklistFolder`) that no component calls. iOS lists `GET` and `POST /v1/app/checklists/{scope}/templates` in its endpoint registry, behind two constants that no code uses (ios @ aa31967ac8, `APIManagers/APIManager.swift:296-297`). Whether to remove the endpoints with no caller is open \[[ASK-11](https://github.com/snapfix/docs/blob/main/ASK.md#ask-11-which-unused-api-endpoints-are-still-needed)].
* The five `/v1/app/checklists/folders` routes without a scope work on the library's folders, and none of them checks anything beyond the token.
* Related endpoints in other groups: the checklist reports (`checklist_report`, `checklist_report_excel`) are in [Reports](https://docs.snapfix.com/engineering-reference/api/reports.md); `admin_create_checklist` and `admin_copy_job_todo` are in [Staff](https://docs.snapfix.com/engineering-reference/api/staff.md); the task list for assigning checklists ([POST /v1/app/tasks/list-for-checklist](https://docs.snapfix.com/engineering-reference/api/tasks.md#post-v1apptaskslist-for-checklist)), the checklist name ([PUT /v1/app/tasks/{uuid}/todo-name](https://docs.snapfix.com/engineering-reference/api/tasks.md#put-v1apptasksuuidtodo-name)) and the web's signature reset ([`webcust_reset_job_signature`](https://docs.snapfix.com/engineering-reference/api/tasks.md#post-actionwebcust_reset_job_signature)) are in [Tasks](https://docs.snapfix.com/engineering-reference/api/tasks.md).

## Checklist access checks

Most api\_php\_live\_v2 checklist routes check one of these rules, and each section names the one it uses.

* **Site admin:** the caller is an admin of the site (`operate` on `ParentModel`, which needs the caller's site role to be admin). Site routes check it on the site of the template, the folder or the request.
* **First multi-site:** the multi-site must be the first multi-site the caller belongs to (`auth()->user()->multiSites->first()`). Multi-site routes and the multi-site permission routes use it.
* **Group view:** the caller is a member of the group, or a multi-site user of its site (`view` on `BusinessModel`). The group's folder and template pickers use it.

These routes check nothing about the caller's relation to the data beyond the token: the library and tag lists; [GET /v1/app/checklists/{scope}/templates/{uuid}](#get-v1appchecklistsscopetemplatesuuid) and [GET /v1/app/checklists/{entityUuid}/activities](#get-v1appchecklistsentityuuidactivities); and [POST /v1/app/checklists/{scope}/jobs](#post-v1appchecklistsscopejobs) for `site` and [POST /v1/app/checklists/{scope}/jobs/delete](#post-v1appchecklistsscopejobsdelete). The schedule routes check the template but not the schedules. The checks of the checklist item routes and the php-apis actions are in their sections.

## POST /v1/app/checklists/library

Lists the checklists of the Snapfix library. Sites copy them into their own templates with [POST /v1/app/checklists/{scope}/templates/download](#post-v1appchecklistsscopetemplatesdownload).

* **Auth:** user token; any signed-in user. The library is shared by all sites.
* **Used by:** web\_app\_v2 (`ChecklistTemplateHttpService.getChecklistLibrary`, from the library dialog in manage checklists).

**Request:** the web sends `tags` in a JSON body and `searchText` in the query string; the server reads both from either.

| Name         | In            | Type            | Required | Rules                                                                                                                                      |
| ------------ | ------------- | --------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
| `searchText` | query or body | string          | no       | Case-insensitive match on the checklist name                                                                                               |
| `tags`       | query or body | array of string | no       | Tag UUIDs ([`tPri_CL_Tag`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_cl_tag.md)); a checklist with any of them matches |

**Response** `200`: `data.checklistLibrary` is a list of [checklist template objects](#checklist-template-object), each with its `tags`.

```json
{
  "status": "success",
  "message": "Operation was successful",
  "data": {
    "checklistLibrary": [
      {
        "uuid": "library-123",
        "checklistUuid": "checklist-123",
        "name": "Fire door check",
        "description": null,
        "note": null,
        "signatureRequired": 0,
        "version": 1,
        "sortOrder": 1000,
        "isArchived": 0,
        "visible": 1,
        "locked": 0,
        "priority": 0,
        "modifiedTs": 1794387600000,
        "tags": [{ "uuid": "tag-600", "name": "Safety", "tagHeader": { "uuid": "header-700", "name": "Compliance" } }]
      }
    ]
  }
}
```

**Errors:** `422` when `searchText` is not a string or `tags` is not an array ([common errors](#common-errors)).

**Side effects:** none.

## GET /v1/app/checklists/library/{uuid}

Gets one library checklist with its sections and items.

* **Auth:** user token; any signed-in user.
* **Used by:** web\_app\_v2 (`ChecklistTemplateHttpService.getSingleChecklistLibraryTemplate`, the preview in the library dialog).

**Request**

| Name   | In   | Type   | Required | Rules                                                                                                                  |
| ------ | ---- | ------ | -------- | ---------------------------------------------------------------------------------------------------------------------- |
| `uuid` | path | string | yes      | A library checklist ([`tPri_CL_Library`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_cl_library.md)) |

**Response** `200`: `data` is a [checklist template object](#checklist-template-object) with `checklistItems`, each with its `media` and `subItems`. It has no `tags`.

**Errors:** `404` "Resource not found" for an unknown UUID.

**Side effects:** none.

## GET /v1/app/checklists/multiSite/jobs/{templateUuid}/parent/{parentUuid}

Lists the tasks of one site that use a multi-site template, with a count of each colour.

* **Auth:** user token. The template's multi-site must be the caller's [first multi-site](#checklist-access-checks), or `403`. `parentUuid` is not checked against that multi-site, but the list holds only tasks the caller can see as a group member: tasks in the site's active task groups where the caller is an admin or has "view all tasks", or created, follows or is assigned to the task.
* **Used by:** web\_app\_v2 (`ChecklistTemplateHttpService.getManageChecklistTemplateTaskList` with `parent`, the template's task list in manage checklists, for one site of the multi-site).

**Request**

| Name           | In   | Type   | Required | Rules                           |
| -------------- | ---- | ------ | -------- | ------------------------------- |
| `templateUuid` | path | string | yes      | A multi-site template           |
| `parentUuid`   | path | string | yes      | The site whose tasks are listed |

**Response** `200`: `data.jobs` is a list of [checklist job objects](#checklist-job-object), and `data.totalCount` counts them by colour.

```json
{
  "status": "success",
  "message": "Operation was successful",
  "data": {
    "jobs": [
      { "uuid": "job-400", "color": "red", "title": "Check fire doors", "largeTitle": null, "image": "", "priority": 0, "priorityLevel": 0, "dueDateTs": 0, "dueDateDailyReminder": 0, "modifiedTs": 1794387600000, "checklistPercent": 40 }
    ],
    "totalCount": { "red": 1, "amber": 0, "green": 0 }
  }
}
```

**Errors:** `403` "Access denied" for another multi-site's template; `404` for an unknown template.

**Side effects:** none. Each task's checklist percentage is read with queries of its own.

## PUT /v1/app/checklists/multiSite/permissions/group

Shows or hides a multi-site template for one group. Each call flips the group's setting. A group with no permission row counts as visible, so the first call creates a hidden row.

* **Auth:** user token. `multiSiteUuid` must be the caller's [first multi-site](#checklist-access-checks) (`403`), and the group's site must be one of its sites (`400`). The template is not checked against the multi-site.
* **Used by:** web\_app\_v2 (`ChecklistTemplateHttpService.updateChecklistPermission` with `group` and `multiSite`, the template's Groups tab in the multi-site console).

**Request** (JSON body)

| Name            | In   | Type   | Required | Rules                                                                                                                              |
| --------------- | ---- | ------ | -------- | ---------------------------------------------------------------------------------------------------------------------------------- |
| `templateUuid`  | body | string | yes      | Must exist in [`tPri_CL_MultiSiteTemplate`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_cl_multisitetemplate.md) |
| `multiSiteUuid` | body | string | yes      | Must exist in [`tPri_MultiSite`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_multisite.md)                       |
| `groupUuid`     | body | string | yes      | Must exist in [`tPri_Business`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_business.md)                         |

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

**Errors:** `403` "Access denied" for another multi-site; `400` with the text `messages.is_not_an_multisite_parent` when the group's site is not in the multi-site; `422` for a UUID that doesn't exist.

**Side effects:** creates a hidden row in [`tPri_CL_Permissions`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_cl_permissions.md) (`uuid_tMultiSite` and `uuid_tBusiness`) and its link in [`tPri_CL_MultiSiteTemplatePermissions`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_cl_multisitetemplatepermissions.md), or flips `fVisible` on the existing row. No activity line and no push.

## PUT /v1/app/checklists/multiSite/permissions/group/all

Shows or hides a multi-site template for every group of one site.

* **Auth:** user token. `multiSiteUuid` must be the caller's [first multi-site](#checklist-access-checks) (`403`), and `parentUuid` one of its sites (`400`). The template is not checked against the multi-site.
* **Used by:** web\_app\_v2 (`updateChecklistPermission` with `group`, `multiSite` and `all`, the all-groups switch on the Groups tab).

**Request** (JSON body)

| Name            | In   | Type    | Required | Rules                                                                                                                              |
| --------------- | ---- | ------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------- |
| `templateUuid`  | body | string  | yes      | Must exist in [`tPri_CL_MultiSiteTemplate`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_cl_multisitetemplate.md) |
| `multiSiteUuid` | body | string  | yes      | Must exist in [`tPri_MultiSite`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_multisite.md)                       |
| `parentUuid`    | body | string  | yes      | A site of the multi-site; must exist in [`tPri_Parent`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_parent.md)   |
| `visible`       | body | integer | yes      | `0` or `1`                                                                                                                         |

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

**Errors:** `403` "Access denied"; `400` with the text `messages.is_not_an_multisite_parent` when `parentUuid` is not one of the multi-site's sites; `422`.

**Side effects:** sets `fVisible` on the existing rows of the site's groups and creates the missing ones, as the single-group route does. No activity line.

## PUT /v1/app/checklists/multiSite/permissions/parent

Shows or hides a multi-site template for one site. Each call flips the site's setting; the first call creates a hidden row.

* **Auth:** user token. `multiSiteUuid` must be the caller's [first multi-site](#checklist-access-checks) (`403`), and `parentUuid` one of its sites (`400`). The template is not checked against the multi-site.
* **Used by:** web\_app\_v2 (`updateChecklistPermission` with `parent`, the template's Sites tab in the multi-site console).

**Request** (JSON body)

| Name            | In   | Type   | Required | Rules                                                                                                                              |
| --------------- | ---- | ------ | -------- | ---------------------------------------------------------------------------------------------------------------------------------- |
| `templateUuid`  | body | string | yes      | Must exist in [`tPri_CL_MultiSiteTemplate`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_cl_multisitetemplate.md) |
| `multiSiteUuid` | body | string | yes      | Must exist in [`tPri_MultiSite`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_multisite.md)                       |
| `parentUuid`    | body | string | yes      | Must exist in [`tPri_Parent`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_parent.md)                             |

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

**Errors:** `403` "Access denied"; `400` with the text `messages.is_not_an_multisite_parent` when `parentUuid` is not one of the multi-site's sites; `422`.

**Side effects:** creates a hidden row in [`tPri_CL_Permissions`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_cl_permissions.md) (`uuid_tMultiSite` and `uuid_tParent`) and its link in [`tPri_CL_MultiSiteTemplatePermissions`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_cl_multisitetemplatepermissions.md), or flips the existing row. No activity line and no push.

## PUT /v1/app/checklists/multiSite/permissions/parent/all

Shows or hides a multi-site template for every site of the multi-site.

* **Auth:** user token. `multiSiteUuid` must be the caller's [first multi-site](#checklist-access-checks) (`403`). The template is not checked against the multi-site.
* **Used by:** web\_app\_v2 (`updateChecklistPermission` with `parent` and `all`, the all-sites switch on the Sites tab).

**Request** (JSON body)

| Name            | In   | Type    | Required | Rules                                                                                                                              |
| --------------- | ---- | ------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------- |
| `templateUuid`  | body | string  | yes      | Must exist in [`tPri_CL_MultiSiteTemplate`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_cl_multisitetemplate.md) |
| `multiSiteUuid` | body | string  | yes      | Must exist in [`tPri_MultiSite`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_multisite.md)                       |
| `visible`       | body | integer | yes      | `0` or `1`                                                                                                                         |

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

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

**Side effects:** sets `fVisible` on the existing site rows and creates the missing ones, for every site of the multi-site. No activity line.

## GET /v1/app/checklists/multiSite/{templateUuid}/permissions/{multiSiteUuid}

Lists the sites of a multi-site with a multi-site template's visibility in each.

* **Auth:** user token. `multiSiteUuid` must be the caller's [first multi-site](#checklist-access-checks) (`403`). `templateUuid` is not checked.
* **Used by:** web\_app\_v2 (`ChecklistTemplateHttpService.getManageChecklistTemplateSiteList`, the template's Sites tab).

**Request**

| Name            | In   | Type   | Required | Rules                   |
| --------------- | ---- | ------ | -------- | ----------------------- |
| `templateUuid`  | path | string | yes      | A multi-site template   |
| `multiSiteUuid` | path | string | yes      | The caller's multi-site |

**Response** `200`: `data` is a list of site rows of the [checklist permission object](#checklist-permission-object). A site with no permission row shows `visible` 1.

```json
{ "status": "success", "message": "Operation was successful", "data": [ { "uuid": "site-100", "name": "Example Hotel", "image": null, "visible": 1 } ] }
```

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

**Side effects:** none.

## GET /v1/app/checklists/multiSite/{templateUuid}/permissions/{multiSiteUuid}/groups/{parentUuid}

Lists the groups of one site of the multi-site with a multi-site template's visibility in each.

* **Auth:** user token. `multiSiteUuid` must be the caller's [first multi-site](#checklist-access-checks) (`403`), and `parentUuid` one of its sites (`400`). `templateUuid` is not checked.
* **Used by:** web\_app\_v2 (`ChecklistTemplateHttpService.getManageChecklistTemplateGroupList` with `multiSite`, the template's Groups tab in the multi-site console).

**Request**

| Name            | In   | Type   | Required | Rules                     |
| --------------- | ---- | ------ | -------- | ------------------------- |
| `templateUuid`  | path | string | yes      | A multi-site template     |
| `multiSiteUuid` | path | string | yes      | The caller's multi-site   |
| `parentUuid`    | path | string | yes      | A site of that multi-site |

**Response** `200`: `data` is a list of group rows of the [checklist permission object](#checklist-permission-object). A group with no permission row shows `visible` 1.

**Errors:** `403` "Access denied"; `400` with the text `messages.is_not_an_multisite_parent` when `parentUuid` is not one of the multi-site's sites.

**Side effects:** none.

## GET /v1/app/checklists/site/folders/group/{groupUuid}

Lists the folders of a group's site, each with the number of its templates the group can see. The web's checklist picker for a group's tasks uses it.

* **Auth:** user token; [group view](#checklist-access-checks) on the group (`403`).
* **Used by:** web\_app\_v2 (`ChecklistTemplateHttpService.getSiteFolderForGroup`, the checklist template list for a group).

**Request**

| Name        | In   | Type   | Required | Rules   |
| ----------- | ---- | ------ | -------- | ------- |
| `groupUuid` | path | string | yes      | A group |

**Response** `200`: `data` is a list of [checklist folder objects](#checklist-folder-object): every folder of the group's site, with `checklistCount` counting the templates that are visible to the group or have no permission row for it.

```json
{ "status": "success", "message": "Operation was successful", "data": [ { "uuid": "folder-200", "multiSiteUuid": null, "siteUuid": "site-100", "name": "Fire safety", "description": null, "note": null, "sortOrder": 1000, "checklistCount": 2 } ] }
```

**Errors:** `403` "Access denied"; `404` for an unknown group.

**Side effects:** none. The count query puts the group UUID into its SQL as text; the group must exist first, so a crafted value can't reach the query today.

## GET /v1/app/checklists/site/folders/{parentUuid}/multiSite

Lists the folders of a site's multi-site, each with the number of its templates the site can see.

* **Auth:** user token; [site admin](#checklist-access-checks) of `parentUuid` (`403`).
* **Used by:** web\_app\_v2 (`ChecklistTemplateHttpService.getMultiSiteFolderForSite`, the multi-site part of the checklist template list).

**Request**

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

**Response** `200`: `data` is a list of [checklist folder objects](#checklist-folder-object): every folder of the site's multi-site, with `checklistCount` counting the templates that are visible to the site or have no permission row for it. A site in no multi-site gets an empty list.

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

**Side effects:** none. The site UUID goes into the count query as text; only a site the caller administers gets that far.

## PUT /v1/app/checklists/site/permissions/group

Shows or hides a site template for one group. Each call flips the group's setting; the first call creates a hidden row.

* **Auth:** user token; [site admin](#checklist-access-checks) of `parentUuid` (`403`). Neither the template nor the group is checked to belong to that site.
* **Used by:** web\_app\_v2 (`updateChecklistPermission` with `group` and `site`, the template's Groups tab in the site console).

**Request** (JSON body)

| Name           | In   | Type   | Required | Rules                                                                                                                    |
| -------------- | ---- | ------ | -------- | ------------------------------------------------------------------------------------------------------------------------ |
| `templateUuid` | body | string | yes      | Must exist in [`tPri_CL_SiteTemplate`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_cl_sitetemplate.md) |
| `parentUuid`   | body | string | yes      | Must exist in [`tPri_Parent`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_parent.md)                   |
| `groupUuid`    | body | string | yes      | Must exist in [`tPri_Business`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_business.md)               |

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

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

**Side effects:** creates a hidden row in [`tPri_CL_Permissions`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_cl_permissions.md) (`uuid_tParent` and `uuid_tBusiness`) and its link in [`tPri_CL_SiteTemplatePermissions`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_cl_sitetemplatepermissions.md), or flips the existing row. No activity line and no push.

## PUT /v1/app/checklists/site/permissions/group/all

Shows or hides a site template for the groups of the site that the caller is a member of \[[ASK-139](https://github.com/snapfix/docs/blob/main/ASK.md#ask-139-should-a-site-templates-group-settings-cover-only-the-admins-own-groups)].

* **Auth:** user token; [site admin](#checklist-access-checks) of `parentUuid` (`403`). The template is not checked against the site.
* **Used by:** web\_app\_v2 (`updateChecklistPermission` with `group`, `site` and `all`, the all-groups switch on the Groups tab).

**Request** (JSON body)

| Name           | In   | Type    | Required | Rules                                                                                                                    |
| -------------- | ---- | ------- | -------- | ------------------------------------------------------------------------------------------------------------------------ |
| `templateUuid` | body | string  | yes      | Must exist in [`tPri_CL_SiteTemplate`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_cl_sitetemplate.md) |
| `parentUuid`   | body | string  | yes      | Must exist in [`tPri_Parent`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_parent.md)                   |
| `visible`      | body | integer | yes      | `0` or `1`                                                                                                               |

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

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

**Side effects:** sets `fVisible` on those groups' existing rows and creates the missing ones, as the single-group route does. No activity line.

## POST /v1/app/checklists/site/templates/download/multiSite

Copies multi-site templates into a folder of a site. Each copy gets its own checklist, with copies of the items and their notes; item photos are not copied.

* **Auth:** user token; [site admin](#checklist-access-checks) of `parentUuid` (`403`). The templates are not checked against the caller's multi-site, because that check is commented out, and the folder is not checked against `parentUuid`.
* **Used by:** web\_app\_v2 (`ChecklistTemplateHttpService.createChecklistTemplatesFromMutliSite`, the pick templates dialog in a site).

**Request** (JSON body)

| Name                     | In   | Type            | Required | Rules                                                                                                                                                |
| ------------------------ | ---- | --------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
| `multiSiteTemplateUuids` | body | array of string | yes      | Each must exist in [`tPri_CL_MultiSiteTemplate`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_cl_multisitetemplate.md)              |
| `folderUuid`             | body | string          | yes      | Must exist in [`tPri_CL_SiteTemplateVirtualFolders`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_cl_sitetemplatevirtualfolders.md) |
| `parentUuid`             | body | string          | yes      | The target site; must exist in [`tPri_Parent`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_parent.md)                              |

**Response** `200`: `data` is a list of the new [checklist template objects](#checklist-template-object), one per copy.

**Errors:** `403` "Access denied"; `422` for a UUID that doesn't exist.

**Side effects:** for each template, a new [`tPri_CL`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_cl.md) checklist with copies of its [`tPri_CL_Item`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_cl_item.md) and [`tPri_CL_Item_Notes`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_cl_item_notes.md) rows, a [`tPri_CL_SiteTemplate`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_cl_sitetemplate.md) row with the source's name, description and note, and a `template_download` [activity line](#common-side-effects). Unlike the library download, the name is not checked against the site's other templates.

## GET /v1/app/checklists/site/templates/group/{groupUuid}/list-by-folder/{folderUuid}

Lists the site templates in a folder that a group can use: those visible to the group, or with no permission row for it.

* **Auth:** user token; [group view](#checklist-access-checks) on the group (`403`). The folder is not checked against the group's site.
* **Used by:** web\_app\_v2 (`ChecklistTemplateHttpService.getSiteTemplateForGroup`, the checklist template list for a group).

**Request**

| Name         | In   | Type   | Required | Rules         |
| ------------ | ---- | ------ | -------- | ------------- |
| `groupUuid`  | path | string | yes      | A group       |
| `folderUuid` | path | string | yes      | A site folder |

**Response** `200`: `data` is a list of [checklist template objects](#checklist-template-object), without items.

**Errors:** `403` "Access denied"; `404` for an unknown group.

**Side effects:** none.

## GET /v1/app/checklists/site/templates/{parentUuid}/list-by-folder/{folderUuid}/multiSite

Lists the multi-site templates in a folder that a site can use: those visible to the site, or with no permission row for it.

* **Auth:** user token; [site admin](#checklist-access-checks) of `parentUuid` (`403`). The folder is not checked against the site's multi-site.
* **Used by:** web\_app\_v2 (`ChecklistTemplateHttpService.getMultiSiteTemplateForSite`, the multi-site part of the checklist template list).

**Request**

| Name         | In   | Type   | Required | Rules               |
| ------------ | ---- | ------ | -------- | ------------------- |
| `parentUuid` | path | string | yes      | A site              |
| `folderUuid` | path | string | yes      | A multi-site folder |

**Response** `200`: `data` is a list of [checklist template objects](#checklist-template-object), without items. A site in no multi-site gets an empty list.

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

**Side effects:** none.

## GET /v1/app/checklists/site/{templateUuid}/permissions/{parentUuid}/groups

Lists the groups of a site that the caller is a member of, with a site template's visibility in each \[[ASK-139](https://github.com/snapfix/docs/blob/main/ASK.md#ask-139-should-a-site-templates-group-settings-cover-only-the-admins-own-groups)].

* **Auth:** user token; [site admin](#checklist-access-checks) of `parentUuid` (`403`). `templateUuid` is not checked.
* **Used by:** web\_app\_v2 (`ChecklistTemplateHttpService.getManageChecklistTemplateGroupList` with `site`, the template's Groups tab in the site console).

**Request**

| Name           | In   | Type   | Required | Rules           |
| -------------- | ---- | ------ | -------- | --------------- |
| `templateUuid` | path | string | yes      | A site template |
| `parentUuid`   | path | string | yes      | A site          |

**Response** `200`: `data` is a list of group rows of the [checklist permission object](#checklist-permission-object). A group with no permission row shows `visible` 1.

```json
{ "status": "success", "message": "Operation was successful", "data": [ { "uuid": "group-300", "name": "Maintenance", "image": null, "type": 1, "visible": 1 } ] }
```

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

**Side effects:** none.

## GET /v1/app/checklists/tags

Lists the library's tag headers with their tags.

* **Auth:** user token; any signed-in user.
* **Used by:** web\_app\_v2 (`ChecklistTemplateHttpService.getChecklistTag`, the tag filter in the library dialog).

**Request**

| Name         | In    | Type   | Required | Rules                                                                                            |
| ------------ | ----- | ------ | -------- | ------------------------------------------------------------------------------------------------ |
| `searchText` | query | string | no       | Keeps the tags whose name contains the text. Every header is still listed, possibly with no tags |

**Response** `200`: `data` is a list of [checklist tag header objects](#checklist-tag-header-object).

```json
{ "status": "success", "message": "Operation was successful", "data": [ { "uuid": "header-700", "name": "Compliance", "tags": [ { "uuid": "tag-600", "name": "Safety" } ] } ] }
```

**Errors:** `422` when `searchText` is not a string.

**Side effects:** none.

## GET /v1/app/checklists/{entityUuid}/activities

Lists the activity log of a template, newest first.

* **Auth:** user token only. The template is not checked against the caller's site or multi-site, so any signed-in user can read any template's log.
* **Used by:** web\_app\_v2 (`ChecklistHttpService.getChecklistActivity`, the audit trail dialog in manage checklists).

**Request**

| Name         | In   | Type   | Required | Rules                                                                                                                    |
| ------------ | ---- | ------ | -------- | ------------------------------------------------------------------------------------------------------------------------ |
| `entityUuid` | path | string | yes      | A template's UUID (`entity_uuid` in the log). Folder changes write no activity lines. An unknown UUID gets an empty list |

**Response** `200`: `data` is a list of [checklist activity objects](#checklist-activity-object).

```json
{
  "status": "success",
  "message": "Operation was successful",
  "data": [
    { "uuid": "log-1000", "entityUuid": "template-123", "text": "created site template item <b>\"Fire door check\"</b>", "action": "template_create", "entity": "site", "createdTs": 1794387600000, "modifiedTs": 1794387600000, "user": { "uuid": "user-500", "name": "Jane Smith", "image": null, "username": "jane@example.com", "businessName": null } }
  ]
}
```

**Errors:** none of its own.

**Side effects:** none.

## GET /v1/app/checklists/{scope}/folders

Lists the folders of a site or multi-site, each with its number of templates.

* **Auth:** user token. For `site`, [site admin](#checklist-access-checks) of `uuid`; for `multiSite`, `uuid` must be the caller's [first multi-site](#checklist-access-checks). Otherwise `403`.
* **Used by:** web\_app\_v2 (`ChecklistTemplateHttpService.getChecklistFolderList`, the folder list in manage checklists, the checklist template list and the folder picker of the library dialog).

**Request**

| Name         | In    | Type   | Required | Rules                                           |
| ------------ | ----- | ------ | -------- | ----------------------------------------------- |
| `scope`      | path  | string | yes      | `site` or `multiSite`                           |
| `uuid`       | query | string | yes      | The site or multi-site whose folders are listed |
| `searchText` | query | string | no       | Keeps the folders whose name contains the text  |

**Response** `200`: `data` is a list of [checklist folder objects](#checklist-folder-object). `checklistCount` counts every template filed in the folder that isn't deleted.

```json
{ "status": "success", "message": "Operation was successful", "data": [ { "uuid": "folder-200", "multiSiteUuid": null, "siteUuid": "site-100", "name": "Fire safety", "description": null, "note": null, "sortOrder": 1000, "checklistCount": 3 } ] }
```

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

**Side effects:** none.

## POST /v1/app/checklists/{scope}/folders

Creates a folder in a site or multi-site.

* **Auth:** user token. For `site`, [site admin](#checklist-access-checks) of `parentUuid`; for `multiSite`, `multiSiteUuid` must be the caller's [first multi-site](#checklist-access-checks). Otherwise `403`.
* **Used by:** web\_app\_v2 (`ChecklistTemplateHttpService.createChecklistFolder`, the create folder dialog), sent as form data.

**Request** (form or JSON body)

| Name            | In   | Type           | Required         | Rules                                                                                                        |
| --------------- | ---- | -------------- | ---------------- | ------------------------------------------------------------------------------------------------------------ |
| `scope`         | path | string         | yes              | `site` or `multiSite`                                                                                        |
| `name`          | body | string         | yes              | The folder's name                                                                                            |
| `description`   | body | string or null | no               | Text                                                                                                         |
| `note`          | body | string         | no               | Text; null is refused                                                                                        |
| `sortOrder`     | body | integer        | no               | Position                                                                                                     |
| `parentUuid`    | body | string         | with `site`      | Must exist in [`tPri_Parent`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_parent.md)       |
| `multiSiteUuid` | body | string         | with `multiSite` | Must exist in [`tPri_MultiSite`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_multisite.md) |

**Response** `200`: `data` is the new [checklist folder object](#checklist-folder-object), with `checklistCount` `null`.

**Errors:** `403` "Access denied"; `422` for a missing name, a missing site or multi-site, or one that doesn't exist.

**Side effects:** inserts a row in [`tPri_CL_SiteTemplateVirtualFolders`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_cl_sitetemplatevirtualfolders.md) or [`tPri_CL_MultiSiteTemplateVirtualFolders`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_cl_multisitetemplatevirtualfolders.md). No activity line: the folder log calls are commented out.

## PUT /v1/app/checklists/{scope}/folders/{uuid}

Changes a folder's name, description, note or position.

* **Auth:** user token. For `site`, [site admin](#checklist-access-checks) of the folder's site; for `multiSite`, the folder's multi-site must be the caller's [first multi-site](#checklist-access-checks). Otherwise `403`.
* **Used by:** web\_app\_v2 (`ChecklistTemplateHttpService.updateChecklistFolder`, the create folder dialog in edit mode and the folder list in manage checklists).

**Request** (JSON body; every field optional)

| Name          | In   | Type            | Required | Rules                 |
| ------------- | ---- | --------------- | -------- | --------------------- |
| `scope`       | path | string          | yes      | `site` or `multiSite` |
| `uuid`        | path | string          | yes      | The folder            |
| `name`        | body | string          | no       | The folder's name     |
| `description` | body | string or null  | no       | Text                  |
| `note`        | body | string or null  | no       | Text                  |
| `sortOrder`   | body | integer or null | no       | Position              |

**Response** `200`: `data` is the changed [checklist folder object](#checklist-folder-object), with `checklistCount` `null`.

**Errors:** `403` "Access denied"; `404` for an unknown folder; `422`.

**Side effects:** updates the folder row. No activity line.

## DELETE /v1/app/checklists/{scope}/folders/{uuid}

Deletes a folder. Its templates lose the folder, and a template left in no folder is deleted too; the web's confirmation says so.

* **Auth:** user token, with the check of [PUT /v1/app/checklists/{scope}/folders/{uuid}](#put-v1appchecklistsscopefoldersuuid).
* **Used by:** web\_app\_v2 (`ChecklistTemplateHttpService.deleteChecklistFolder`, the folder menu in manage checklists).

**Request**

| Name    | In   | Type   | Required | Rules                 |
| ------- | ---- | ------ | -------- | --------------------- |
| `scope` | path | string | yes      | `site` or `multiSite` |
| `uuid`  | path | string | yes      | The folder            |

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

**Errors:** `403` "Access denied"; `404` for an unknown folder.

**Side effects:** removes the folder's UUID from the folder list of each template filed in it ([`tPri_CL_SiteTemplate`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_cl_sitetemplate.md) or [`tPri_CL_MultiSiteTemplate`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_cl_multisitetemplate.md)), marks the templates left with no folder deleted (`fDeleted`), then marks the folder deleted. No activity line. The tasks of a template deleted this way fare as in [DELETE /v1/app/checklists/{scope}/templates/{templateUuid}](#delete-v1appchecklistsscopetemplatestemplateuuid).

## POST /v1/app/checklists/{scope}/jobs

Puts a template on tasks. Each task's own checklist items are deleted, and the task is linked to the template instead. Until the web saves a copy, the task's checklist shows the template's items ([GET /v1/app/todos](#get-v1apptodos)).

* **Auth:** user token. For `multiSite`, the template's multi-site must be the caller's [first multi-site](#checklist-access-checks) (`403`). For `site`, the template is not checked against the caller, and for both scopes the tasks are not checked against the caller's groups. For `site`, only tasks whose group is in the template's site change; for `multiSite`, every listed task changes, whatever its site.
* **Used by:** web\_app\_v2 (`ChecklistTemplateHttpService.AssignChecklistToTask` with `task`, from the assign to tasks dialog in manage checklists, the task's checklist and the task's add checklist dialog).

**Request** (JSON body)

| Name              | In   | Type            | Required | Rules                                                                                                                                                                                                                                                                   |
| ----------------- | ---- | --------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `scope`           | path | string          | yes      | `site` or `multiSite`                                                                                                                                                                                                                                                   |
| `templateUuid`    | body | string          | yes      | Must exist in [`tPri_CL_SiteTemplate`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_cl_sitetemplate.md) (`site`) or [`tPri_CL_MultiSiteTemplate`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_cl_multisitetemplate.md) (`multiSite`) |
| `jobUuids`        | body | array of string | yes      | The tasks; at most `CHECKLIST_SELECT_ALL_LIMIT`, 5,000 by default                                                                                                                                                                                                       |
| `oldTemplateUuid` | body | string          | no       | The template this one replaces; must exist in the same table. When sent, the template is made visible to the groups of the changed tasks, and for `multiSite` to their sites too                                                                                        |

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

**Errors:** `403` "Access denied" for another multi-site's template; `422` for a missing or too long `jobUuids`, or a template that doesn't exist.

**Side effects:**

* Marks each changed task's items deleted in [`tPri_JobTodo`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_jobtodo.md), one at a time. Their notes and photos rows are left as they are.
* Replaces the task's links in [`tPri_Job_CL_Template`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_job_cl_template.md): every link is marked deleted, then the link to this template is restored or created.
* Sets `fTodoSignatureRequired` in [`tPri_Job`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_job.md) from the template's `fSignatureRequired`, and [touches](#common-side-effects) the tasks.
* Sends the [template push](#common-side-effects) for each task.
* With `oldTemplateUuid`: creates visible rows in [`tPri_CL_Permissions`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_cl_permissions.md) with their links in [`tPri_CL_SiteTemplatePermissions`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_cl_sitetemplatepermissions.md) or [`tPri_CL_MultiSiteTemplatePermissions`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_cl_multisitetemplatepermissions.md), or sets existing ones visible.

## POST /v1/app/checklists/{scope}/jobs/all

Puts a template on every task of one group that matches the task list's filters.

* **Auth:** user token. The template is checked as for [POST /v1/app/checklists/{scope}/jobs](#post-v1appchecklistsscopejobs): for `site` not at all. The tasks come from the group's task list as the caller sees it: unless the caller is a multi-site user of the site, only tasks of the group where the caller is an admin or has "view all tasks", or that they created, follow or are assigned to. A caller outside the group gets `403` "Jobs not found".
* **Used by:** web\_app\_v2 (`ChecklistTemplateHttpService.AssignChecklistToAllTasks` with `site`, from the task's add checklist dialog).

**Request** (JSON body)

| Name                                                                  | In   | Type            | Required        | Rules                                                                                |
| --------------------------------------------------------------------- | ---- | --------------- | --------------- | ------------------------------------------------------------------------------------ |
| `scope`                                                               | path | string          | yes             | `site` or `multiSite`                                                                |
| `templateUuid`                                                        | body | string          | yes             | As in [POST /v1/app/checklists/{scope}/jobs](#post-v1appchecklistsscopejobs)         |
| `oldTemplateUuid`                                                     | body | string          | no              | As there; the template is made visible to the group, and for `multiSite` to its site |
| `businessUuid`                                                        | body | string          | yes             | The group. Unknown: `404`                                                            |
| `color`                                                               | body | string          | unless `colors` | `red`, `amber` or `green`; `amber` also matches old yellow tasks                     |
| `colors`                                                              | body | array of string | unless `color`  | Each as `color`                                                                      |
| `searchText`                                                          | body | string          | no              | Task text                                                                            |
| `normalTasks`, `archivedTasks`, `unreadTasks`, `priority`, `withCost` | body | boolean         | no              | Task list filters                                                                    |
| `tags`, `rooms`, `assets`, `createdBy`, `assignedTo`                  | body | array           | no              | Task list filters by ID                                                              |
| `assetAttributeValue`                                                 | body | string          | no              | Asset attribute filter                                                               |
| `createdStartDate`, `createdEndDate`                                  | body | date `Y-m-d`    | together        | Created between the two days; the end not before the start                           |
| `updatedStartDate`, `updatedEndDate`                                  | body | date `Y-m-d`    | together        | Changed between the two days                                                         |

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

**Errors:** `403` with the text "Jobs not found" when no task matches; `403` "Access denied" for another multi-site's template; `404` for an unknown group; `422` for a bad filter.

**Side effects:** as [POST /v1/app/checklists/{scope}/jobs](#post-v1appchecklistsscopejobs), for every matching task (for `site`, those in the template's site), with no limit on how many.

## POST /v1/app/checklists/{scope}/jobs/delete

Takes a template off tasks. The tasks' own items stay.

* **Auth:** user token only. Neither the template nor the tasks are checked against the caller; the check is commented out in the code.
* **Used by:** web\_app\_v2 (`ChecklistTemplateHttpService.RemoveChecklistFromTask` with `task`, from the remove checklist dialog, the replace step of the assign dialog and the task's checklist).

**Request** (JSON body)

| Name           | In   | Type            | Required | Rules                                                                                                                  |
| -------------- | ---- | --------------- | -------- | ---------------------------------------------------------------------------------------------------------------------- |
| `scope`        | path | string          | yes      | `site` or `multiSite`                                                                                                  |
| `templateUuid` | body | string          | yes      | Must exist in the scope's template table, as in [POST /v1/app/checklists/{scope}/jobs](#post-v1appchecklistsscopejobs) |
| `jobUuids`     | body | array of string | yes      | The tasks; at most `CHECKLIST_SELECT_ALL_LIMIT`                                                                        |

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

**Errors:** `422` for a bad body or a template that doesn't exist.

**Side effects:** marks the listed tasks' links to this template deleted in [`tPri_Job_CL_Template`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_job_cl_template.md). Sets `fTodoSignatureRequired` to 0 on every listed task, also one whose link to another template stays, and [touches](#common-side-effects) them. Sends the [template push](#common-side-effects) for each removed link.

## GET /v1/app/checklists/{scope}/jobs/{templateUuid}/group/{businessUuid}

Lists the tasks of one group that use a template, with a count of each colour.

* **Auth:** user token. For `site`, [site admin](#checklist-access-checks) of the template's site; for `multiSite`, the template's multi-site must be the caller's [first multi-site](#checklist-access-checks). Otherwise `403`. The group is not checked against the template's site.
* **Used by:** web\_app\_v2 (`ChecklistTemplateHttpService.getManageChecklistTemplateTaskList` with `group`, the template's task list in manage checklists).

**Request**

| Name           | In   | Type   | Required | Rules                    |
| -------------- | ---- | ------ | -------- | ------------------------ |
| `scope`        | path | string | yes      | `site` or `multiSite`    |
| `templateUuid` | path | string | yes      | A template of that scope |
| `businessUuid` | path | string | yes      | A group                  |

**Response** `200`: as in [GET /v1/app/checklists/multiSite/jobs/{templateUuid}/parent/{parentUuid}](#get-v1appchecklistsmultisitejobstemplateuuidparentparentuuid). Old yellow tasks are counted as amber.

**Errors:** `403` "Access denied"; `404` for an unknown template.

**Side effects:** none. Each task's checklist percentage is read with queries of its own.

## POST /v1/app/checklists/{scope}/schedules

Puts a template on planned tasks (schedules), so that the tasks they create get it.

* **Auth:** user token. For `site`, [site admin](#checklist-access-checks) of the template's site; for `multiSite`, the template's multi-site must be the caller's [first multi-site](#checklist-access-checks). Otherwise `403`. The schedules are not checked against the caller.
* **Used by:** web\_app\_v2 (`ChecklistTemplateHttpService.AssignChecklistToTask` with `schedule`, from the assign to tasks dialog, the planned task's checklist and the add checklist dialog of a planned task).

**Request** (JSON body)

| Name            | In   | Type            | Required | Rules                                               |
| --------------- | ---- | --------------- | -------- | --------------------------------------------------- |
| `scope`         | path | string          | yes      | `site` or `multiSite`                               |
| `templateUuid`  | body | string          | yes      | Must exist in the scope's template table            |
| `scheduleUuids` | body | array of string | yes      | The schedules; at most `CHECKLIST_SELECT_ALL_LIMIT` |

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

**Errors:** `403` "Access denied"; `422` for a bad body or a template that doesn't exist.

**Side effects:** for each schedule in [`schedule_v3`](https://docs.snapfix.com/engineering-reference/db/tables/schedule_v3.md) that isn't deleted, removes both template keys (`uuid_tSiteTemplate`, `uuid_tMultiSiteTemplate`) from `job_json`, sets the scope's key to the template, and saves the row. Tasks already created don't change. No activity line and no push.

## POST /v1/app/checklists/{scope}/schedules/delete

Takes a template off planned tasks (schedules).

* **Auth:** as [POST /v1/app/checklists/{scope}/schedules](#post-v1appchecklistsscopeschedules): the template is checked, the schedules are not.
* **Used by:** web\_app\_v2 (`ChecklistTemplateHttpService.RemoveChecklistFromTask` with `schedule`, from the remove checklist dialog, the replace step of the assign dialog and the planned task's checklist).

**Request** (JSON body)

| Name            | In   | Type            | Required | Rules                                               |
| --------------- | ---- | --------------- | -------- | --------------------------------------------------- |
| `scope`         | path | string          | yes      | `site` or `multiSite`                               |
| `templateUuid`  | body | string          | yes      | Must exist in the scope's template table            |
| `scheduleUuids` | body | array of string | yes      | The schedules; at most `CHECKLIST_SELECT_ALL_LIMIT` |

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

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

**Side effects:** for each schedule whose `job_json` has the scope's template key, removes that key, whatever template it names, and saves the row in [`schedule_v3`](https://docs.snapfix.com/engineering-reference/db/tables/schedule_v3.md). Schedules without the key are skipped.

## POST /v1/app/checklists/{scope}/templates

Creates a template, with its sections and items, in a site or multi-site.

* **Auth:** user token. For `site`, [site admin](#checklist-access-checks) of `parentUuid`; for `multiSite`, `multiSiteUuid` must be the caller's [first multi-site](#checklist-access-checks). Otherwise `403`.
* **Used by:** web\_app\_v2 (`ChecklistTemplateHttpService.createChecklistTemplates`, from the create checklist dialog: a new template, or "make template" from a task's checklist).

**Request** (JSON body)

| Name                  | In   | Type           | Required         | Rules                                                                                                        |
| --------------------- | ---- | -------------- | ---------------- | ------------------------------------------------------------------------------------------------------------ |
| `scope`               | path | string         | yes              | `site` or `multiSite`                                                                                        |
| `name`                | body | string         | yes              | At most 255 characters                                                                                       |
| `folderUuid`          | body | string         | yes              | Not checked: it need not exist or belong to the site                                                         |
| `description`, `note` | body | string or null | no               | Text                                                                                                         |
| `signatureRequired`   | body | integer        | no               | `0` (default) or `1`                                                                                         |
| `todos`               | body | array          | yes              | The sections and items, as [template item bodies](#template-item-body)                                       |
| `parentUuid`          | body | string         | with `site`      | Must exist in [`tPri_Parent`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_parent.md)       |
| `multiSiteUuid`       | body | string         | with `multiSite` | Must exist in [`tPri_MultiSite`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_multisite.md) |

**Response** `200`: `data` is the new [checklist template object](#checklist-template-object), without its items.

```json
{ "status": "success", "message": "Operation was successful", "data": { "uuid": "template-123", "checklistUuid": "checklist-123", "name": "Fire door check", "description": null, "note": null, "signatureRequired": 0, "siteTemplateFolderUuids": ["folder-200"], "modifiedTs": 1794387600000 } }
```

**Errors:** `403` "Access denied"; `422` with the first failed rule's message.

**Side effects:** creates a [`tPri_CL`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_cl.md) checklist, a [`tPri_CL_SiteTemplate`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_cl_sitetemplate.md) or [`tPri_CL_MultiSiteTemplate`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_cl_multisitetemplate.md) row, and the items in [`tPri_CL_Item`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_cl_item.md) with their notes in [`tPri_CL_Item_Notes`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_cl_item_notes.md). Writes a `template_create` [activity line](#common-side-effects).

## POST /v1/app/checklists/{scope}/templates/copy

Copies templates into a folder. Each copy gets its own checklist, with copies of the items and their notes.

* **Auth:** user token. Each source template is checked: for `site`, [site admin](#checklist-access-checks) of its site; for `multiSite`, its multi-site must be the caller's [first multi-site](#checklist-access-checks). Templates that fail, or don't exist, are skipped, and the call still answers `200` \[[ASK-70](https://github.com/snapfix/docs/blob/main/ASK.md#ask-70-should-a-copy-or-move-that-skips-templates-say-so)]. The target folder is not checked against the caller.
* **Used by:** web\_app\_v2 (`ChecklistTemplateHttpService.copyChecklistTemplates`, the copy dialog in manage checklists).

**Request** (JSON body)

| Name                             | In   | Type           | Required | Rules                                                                                |
| -------------------------------- | ---- | -------------- | -------- | ------------------------------------------------------------------------------------ |
| `scope`                          | path | string         | yes      | `site` or `multiSite`: the sources' kind                                             |
| `copyableData`                   | body | array          | yes      | At least one entry                                                                   |
| `copyableData[].templateUuid`    | body | string         | yes      | A source template                                                                    |
| `copyableData[].newTemplateName` | body | string or null | no       | The copy's name; the source's by default                                             |
| `copyableData[].description`     | body | string or null | no       | The copy's description; none when missing                                            |
| `folderUuid`                     | body | string         | yes      | Must exist in the folder table of `target`, or of the scope when `target` is missing |
| `target`                         | body | string         | no       | `site` or `multiSite`: the copies' kind; the scope by default                        |

With `target`, each copy is a template of that kind in the folder's site or multi-site. Without it, the copy belongs to the source template's site or multi-site and is filed under `folderUuid`, whichever site that folder belongs to.

**Response** `200`: `data` is a list of the new [checklist template objects](#checklist-template-object). Skipped templates are not in it.

**Errors:** `422` for a bad body or a folder that doesn't exist; `404` when `target` is sent and the folder is deleted.

**Side effects:** for each copy, a new [`tPri_CL`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_cl.md) checklist with copies of the source's items and notes, a template row with the name, the description and the source's signature setting but no note, and a `template_copy` [activity line](#common-side-effects). Task links and permission rows are not copied.

## POST /v1/app/checklists/{scope}/templates/download

Creates a template in a site or multi-site from a library checklist, with copies of its items and their notes.

* **Auth:** user token. For `site`, [site admin](#checklist-access-checks) of `parentUuid`; for `multiSite`, `multiSiteUuid` must be the caller's [first multi-site](#checklist-access-checks). Otherwise `403`.
* **Used by:** web\_app\_v2 (`ChecklistTemplateHttpService.createChecklistTemplates` with `isDownload`, from the create checklist dialog opened from the library), sent as form data.

**Request** (form or JSON body)

| Name                   | In   | Type   | Required         | Rules                                                                                                                                                                                    |
| ---------------------- | ---- | ------ | ---------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `scope`                | path | string | yes              | `site` or `multiSite`                                                                                                                                                                    |
| `checklistLibraryUuid` | body | string | yes              | A library checklist. Unknown: `404`                                                                                                                                                      |
| `name`                 | body | string | yes              | Must not match a template of the same site or multi-site that isn't deleted: "This checklist has already been downloaded. Please use another ’Checklist name’ to download another copy." |
| `description`          | body | string | no               | Text                                                                                                                                                                                     |
| `folderUuid`           | body | string | yes              | A folder of the same site or multi-site that isn't deleted                                                                                                                               |
| `parentUuid`           | body | string | with `site`      | Must exist in [`tPri_Parent`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_parent.md)                                                                                   |
| `multiSiteUuid`        | body | string | with `multiSite` | Must exist in [`tPri_MultiSite`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_multisite.md)                                                                             |

**Response** `200`: `data` is the new [checklist template object](#checklist-template-object).

**Errors:** `403` "Access denied"; `404` for an unknown library checklist; `422` for the name, the folder or the site.

**Side effects:** a new [`tPri_CL`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_cl.md) checklist with copies of the library's [`tPri_CL_Item`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_cl_item.md) and [`tPri_CL_Item_Notes`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_cl_item_notes.md) rows, a template row ([`tPri_CL_SiteTemplate`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_cl_sitetemplate.md) or [`tPri_CL_MultiSiteTemplate`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_cl_multisitetemplate.md)), and a `template_download` [activity line](#common-side-effects).

## GET /v1/app/checklists/{scope}/templates/list-by-folder/{folderUuid}

Lists every template filed in a folder, hidden ones too: no permission filter applies.

* **Auth:** user token. For `site`, [site admin](#checklist-access-checks) of the folder's site; for `multiSite`, the folder's multi-site must be the caller's [first multi-site](#checklist-access-checks). Otherwise `403`.
* **Used by:** web\_app\_v2 (`ChecklistTemplateHttpService.getChecklistTemplatesByFolder`, the folder's template list in manage checklists and the checklist template list).

**Request**

| Name         | In   | Type   | Required | Rules                  |
| ------------ | ---- | ------ | -------- | ---------------------- |
| `scope`      | path | string | yes      | `site` or `multiSite`  |
| `folderUuid` | path | string | yes      | A folder of that scope |

**Response** `200`: `data` is a list of [checklist template objects](#checklist-template-object), without items.

**Errors:** `403` "Access denied"; `404` for an unknown folder.

**Side effects:** none.

## POST /v1/app/checklists/{scope}/templates/move

Moves templates into a folder. A moved template keeps its checklist; the tasks that use it are linked to the new template, and its permissions follow it.

* **Auth:** as [POST /v1/app/checklists/{scope}/templates/copy](#post-v1appchecklistsscopetemplatescopy): sources that fail the check are skipped \[[ASK-70](https://github.com/snapfix/docs/blob/main/ASK.md#ask-70-should-a-copy-or-move-that-skips-templates-say-so)], and the target folder is not checked.
* **Used by:** web\_app\_v2 (`ChecklistTemplateHttpService.moveChecklistTemplates`, the move dialog in manage checklists).

**Request:** as [POST /v1/app/checklists/{scope}/templates/copy](#post-v1appchecklistsscopetemplatescopy); `newTemplateName` and `description` are used here too.

**Response** `200`: `data` is a list of the moved templates, as new [checklist template objects](#checklist-template-object).

**Errors:** as for copy.

**Side effects:** for each template: a new template row in the target folder on the same checklist; the tasks' links to the old template marked deleted and links to the new one created in [`tPri_Job_CL_Template`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_job_cl_template.md), and those tasks [touched](#common-side-effects); the new template linked to the old template's permission rows; the old template marked deleted (`fDeleted`); a `template_move` [activity line](#common-side-effects).

## PUT /v1/app/checklists/{scope}/templates/{templateUuid}

Changes a template's name, description, note and signature setting and, when `todos` is sent, its sections and items.

* **Auth:** user token. For `site`, [site admin](#checklist-access-checks) of the template's site; for `multiSite`, the template's multi-site must be the caller's [first multi-site](#checklist-access-checks). Otherwise `403`.
* **Used by:** web\_app\_v2 (`ChecklistTemplateHttpService.updateChecklistTemplate`, from the create checklist dialog in edit mode, the task's checklist editor and the template actions in manage checklists).

**Request** (JSON body)

| Name                  | In   | Type           | Required | Rules                                                                                                                                                                                                                                    |
| --------------------- | ---- | -------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `scope`               | path | string         | yes      | `site` or `multiSite`                                                                                                                                                                                                                    |
| `templateUuid`        | path | string         | yes      | The template                                                                                                                                                                                                                             |
| `name`                | body | string         | yes      | At most 255 characters                                                                                                                                                                                                                   |
| `description`, `note` | body | string or null | no       | Missing or null keeps the stored text, so neither can be cleared                                                                                                                                                                         |
| `signatureRequired`   | body | integer        | no       | `0` or `1`; missing keeps the stored value                                                                                                                                                                                               |
| `todos`               | body | array          | no       | [Template item bodies](#template-item-body). An item with a `uuid` is changed, or deleted with `deleted` 1; an item without one is added; items not sent stay. A sent `uuid` changes that item even when it belongs to another checklist |

**Response** `200`: `data` is the changed [checklist template object](#checklist-template-object), without items.

**Errors:** `403` "Access denied"; `404` for an unknown template; `422` with the first failed rule's message.

**Side effects:** updates the template row. When `todos` is sent, changes the items in [`tPri_CL_Item`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_cl_item.md) and their notes in [`tPri_CL_Item_Notes`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_cl_item_notes.md), and [touches](#common-side-effects) every task linked to a template on this checklist, without a push. Writes a `template_update` [activity line](#common-side-effects).

## DELETE /v1/app/checklists/{scope}/templates/{templateUuid}

Deletes a template. Its checklist, its items and the tasks' links to it stay.

* **Auth:** user token, with the check of [PUT /v1/app/checklists/{scope}/templates/{templateUuid}](#put-v1appchecklistsscopetemplatestemplateuuid).
* **Used by:** web\_app\_v2 (`ChecklistTemplateHttpService.deleteChecklistTemplate`, from the template actions in manage checklists).

**Request**

| Name           | In   | Type   | Required | Rules                 |
| -------------- | ---- | ------ | -------- | --------------------- |
| `scope`        | path | string | yes      | `site` or `multiSite` |
| `templateUuid` | path | string | yes      | The template          |

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

**Errors:** `403` "Access denied"; `404` for an unknown template.

**Side effects:** marks the template row deleted (`fDeleted`) and writes a `template_remove` [activity line](#common-side-effects). The [`tPri_CL`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_cl.md), [`tPri_CL_Item`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_cl_item.md) and [`tPri_CL_Item_Notes`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_cl_item_notes.md) rows and the [`tPri_Job_CL_Template`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_job_cl_template.md) links are not removed; the code has a TODO for the checklist rows.

## GET /v1/app/checklists/{scope}/templates/{uuid}

Gets a template with its sections and items, their photos and their notes.

* **Auth:** user token only. The template is not checked against the caller's site or multi-site, so any signed-in user can read any template by its UUID.
* **Used by:** web\_app\_v2 (`ChecklistTemplateHttpService.getChecklistTemplateDetails`, from the template preview and the Groups tab in manage checklists, the task's checklist and the planned task's checklist).

**Request**

| Name    | In   | Type   | Required | Rules                    |
| ------- | ---- | ------ | -------- | ------------------------ |
| `scope` | path | string | yes      | `site` or `multiSite`    |
| `uuid`  | path | string | yes      | A template of that scope |

**Response** `200`: `data` is a [checklist template object](#checklist-template-object) with `checklistItems`, each with its `media` and `subItems`.

```json
{ "status": "success", "message": "Operation was successful", "data": { "uuid": "template-123", "checklistUuid": "checklist-123", "name": "Fire door check", "signatureRequired": 0, "checklistItems": [ { "uuid": "item-900", "checklistUuid": "checklist-123", "name": "Door closes fully", "type": 0, "sortOrder": 1000, "isDone": 0, "mandatory": 1, "noteMandatory": 0, "todoMediaMandatory": 0, "completionTs": 0, "media": [], "subItems": [], "settings": { "nfc": { "enabled": 0, "value": "0", "scanned": 0 }, "notes": { "enabled": 1, "value": null }, "radio": { "enabled": 1, "failValue": 0, "flagValue": 0, "passValue": 0, "naValue": 0 }, "rating": { "enabled": 0, "value": 0 }, "yesNo": { "enabled": 0, "value": -1 }, "sectionNa": { "enabled": 0, "value": 0 } } } ] } }
```

**Errors:** `404` when no template of that scope has the UUID.

**Side effects:** none.

## POST /v1/app/todo-medias

Adds a photo or video to a checklist item of a task. The web uploads the file first with `POST /v1/app/upload` ([Files](https://docs.snapfix.com/engineering-reference/api/files.md)); this call saves its URL on the item.

* **Auth:** user token. The item's task must be editable ([task permissions](https://docs.snapfix.com/engineering-reference/api/tasks.md#task-permissions)). Nothing else is checked, so any signed-in user can add media to any task's item by its UUID.
* **Used by:** web, the item's photo dialog on the task's [checklist](https://docs.snapfix.com/how-the-apps-work/screens/checklists/checklist.md) (`TaskChecklistMediaDialogComponent`, through `ChecklistHttpService.createChecklistMedia`).

**Request** (JSON body)

| Name       | In   | Type   | Required | Rules                                                                                                                 |
| ---------- | ---- | ------ | -------- | --------------------------------------------------------------------------------------------------------------------- |
| `todoUuid` | body | string | yes      | The checklist item. An item that has 9 media already: "You can add up to 9 Images/Videos for this note."              |
| `type`     | body | string | yes      | `Image` or `Video`                                                                                                    |
| `mediaUrl` | body | string | yes      | Must start with the server's `BO_DOMAIN` address (`https://bo.snapfix.com` unless set otherwise): "Invalid media url" |
| `thumbUrl` | body | string | no       | The thumbnail; same rule as `mediaUrl`                                                                                |

**Response** `200`: `data.todo` is the item as a [task checklist item object](#task-checklist-item-object), without its `media` list, so the new photo is not in the answer. The web's photo dialog looks for it in `data.todo.media`, so the photo shows only after the checklist loads again. The message is "Checklist media added successfully".

```json
{
  "status": "success",
  "message": "Checklist media added successfully",
  "data": {
    "todo": { "uuid": "todo-200", "name": "Check the door seal", "type": 0, "sortOrder": 1000, "isDone": 0, "todoMediaMandatory": 1, "completionTs": 0, "modifiedTs": 1794387600000 }
  }
}
```

**Errors:** [common errors](#common-errors); `400` "The task can not be updated" when the task is locked, archived or outside its time range; `404` for an unknown item; `422` for the media limit, another `type`, or a URL on another host.

**Side effects:**

* Adds a row to [`tPri_JobTodoMedia`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_jobtodomedia.md) with the item's task and group.
* Touches the task ([common side effects](#common-side-effects)).
* Adds viewed rows for the caller, for the task and its group, and sends a silent update push to the task's people, as the tasks group's [common side effects](https://docs.snapfix.com/engineering-reference/api/tasks.md#common-side-effects) describe. The push goes out only while 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)]. Writes no chat line.

## DELETE /v1/app/todo-medias/{uuid}

Deletes a photo or video of a task's checklist item.

* **Auth:** as [POST /v1/app/todo-medias](#post-v1apptodo-medias): the task must be editable, and nothing else is checked.
* **Used by:** web, the delete action on an item's photo (`TaskChecklistMediaComponent`, through `ChecklistHttpService.deleteChecklistMedia`).

**Request**

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

**Response** `200`: `data.todo` is the item the media belonged to, as a [task checklist item object](#task-checklist-item-object) without its `media` list. The message is the untranslated key `messages.todo_media_deleted`.

```json
{ "status": "success", "message": "messages.todo_media_deleted", "data": { "todo": { "uuid": "todo-200", "name": "Check the door seal", "isDone": 1 } } }
```

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

**Side effects:** marks the [`tPri_JobTodoMedia`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_jobtodomedia.md) row deleted (`fDeleted` 1, with a new `fServerTs`). Touches the task, adds the caller's viewed rows and sends the silent update push, as [POST /v1/app/todo-medias](#post-v1apptodo-medias) does. Writes no chat line.

## GET /v1/app/todos

Lists a task's checklist items with their media and description lines. A task with no items of its own answers its checklist template's items instead.

* **Auth:** user token. Multi-site users of the task's site skip the checks. Everyone else must be a member of the task's group (otherwise `404`), and a group admin, have "view all tasks", or follow or be assigned to the task (otherwise `403`). Being the task's creator doesn't count here: a creator who passes none of these checks, for example after unfollowing the task, gets `403`, although the task itself opens for them.
* **Used by:** web: the task's [checklist](https://docs.snapfix.com/how-the-apps-work/screens/checklists/checklist.md) card (`TaskChecklistComponent.getChecklist`), a planned task made from a task, which copies its items (`PlannedTaskComponent`), and the helper that works out a task's checklist percentage (`TaskHelperService.updateTaskChecklistData`).

**Request**

| Name      | In    | Type   | Required | Rules                    |
| --------- | ----- | ------ | -------- | ------------------------ |
| `jobUuid` | query | string | yes      | The task. Missing: `500` |

**Response** `200`: `data` is a list of [task checklist item objects](#task-checklist-item-object). The message is "Operation was successful".

* The task's own items come with `media` and `subItems`, in no set order; the web sorts them by `sortOrder`.
* A task with no items of its own but a checklist template ([POST /v1/app/checklists/{scope}/jobs](#post-v1appchecklistsscopejobs)) gets the items of the [template](#checklist-template-object)'s checklist, sorted by `sortOrder`, with `subItems` and without `media`. Their `uuid` is the template item's ([`tPri_CL_Item`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_cl_item.md)).
* A task with neither gets `[]`.

```json
{
  "status": "success",
  "message": "Operation was successful",
  "data": [
    {
      "uuid": "todo-200",
      "name": "Check the door seal",
      "type": 0,
      "sortOrder": 1000,
      "isDone": 0,
      "mandatory": 1,
      "noteMandatory": 0,
      "todoMediaMandatory": 0,
      "completionTs": 0,
      "modifiedTs": 1794387600000,
      "media": [],
      "subItems": [],
      "settings": {
        "nfc": { "enabled": 0, "value": "", "scanned": 0 },
        "notes": { "enabled": 1, "value": "" },
        "radio": { "enabled": 1, "failValue": 0, "flagValue": 0, "passValue": 0, "naValue": 0 },
        "rating": { "enabled": 0, "value": 0 },
        "yesNo": { "enabled": 0, "value": -1 },
        "sectionNa": { "enabled": 0, "value": 1 }
      }
    }
  ]
}
```

**Errors:** [common errors](#common-errors); `403` "Access denied" when the caller may not see the task; `404` for an unknown task, or when the caller isn't a member of its group; `500` without `jobUuid`.

**Side effects:** none.

## PUT /v1/app/todos/check/{uuid}

Ticks one checklist item of a task.

* **Auth:** user token. The item's task must be editable ([task permissions](https://docs.snapfix.com/engineering-reference/api/tasks.md#task-permissions)). Nothing checks the caller's relation to the task, so any signed-in user can tick any task's item by its UUID. The item's mandatory note and photo are not checked either; the web and both apps ask for them before a tick.
* **Used by:** web, the item's tick box on the task's [checklist](https://docs.snapfix.com/how-the-apps-work/screens/checklists/checklist.md) (`ChecklistHttpService.checklistItemDone`). The apps tick on the device and sync the item with [`save_pri_job_todo`](#post-actionsave_pri_job_todo).

**Request**

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

No body.

**Response** `200`: `data.todo` is the item as a [task checklist item object](#task-checklist-item-object), with `media` and `subItems`, and `data.jobchat` is the new chat line as a [chat item object](https://docs.snapfix.com/engineering-reference/api/tasks.md#chat-item-object). The message is "Checklist checked successfully". An item that is ticked already is not changed: the answer has the same message and only `data.todo`.

```json
{
  "status": "success",
  "message": "Checklist checked successfully",
  "data": {
    "todo": { "uuid": "todo-200", "name": "Check the door seal", "type": 0, "isDone": 1, "completionTs": 1794387660000, "media": [], "subItems": [] },
    "jobchat": { "uuid": "chat-300", "text": "<b>Jane</b> checked 'Check the door seal'", "type": 11 }
  }
}
```

**Errors:** [common errors](#common-errors); `400` "The task can not be updated" when the task is locked, archived or outside its time range; `404` for an unknown item.

**Side effects:**

* Sets `fDone` to 1 in [`tPri_JobTodo`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_jobtodo.md), and `fCompletionTs` to now when the item has none.
* Adds the chat line "{name} checked '{item}'" (type 11, `TODO_SELECTED`) to [`tPri_JobChat`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_jobchat.md), an audit line as in [common side effects](https://docs.snapfix.com/engineering-reference/api/tasks.md#common-side-effects).
* Touches the task and sends a silent update push (`TODO_SELECTED`) to the task's people.
* When this tick brings the checklist to 100 %, also sends the push "{name} - Checklist 100%" (`TODO_COMPLETED`).

## POST /v1/app/todos/multi

Adds, changes and deletes the checklist items of a task in one request, with their description lines. Only the items sent change; the others stay as they are.

* **Auth:** user token. The caller needs the checklist permission on the task's group: group admin, or the site's "manage checklist" flag (`fManageChecklist` in the caller's site relation), and not read-only; otherwise `403` "Access denied". With `convertTemplate` 1 this check is skipped, so any signed-in user can rewrite any editable task's checklist by its UUID. The task must be editable.
* **Used by:** web, the task's checklist ([Edit checklist](https://docs.snapfix.com/how-the-apps-work/screens/checklists/edit-checklist.md), [Checklist](https://docs.snapfix.com/how-the-apps-work/screens/checklists/checklist.md)), through `ChecklistHttpService.saveChecklistEditor`:
  * the checklist editor's save;
  * "Remove From Task" on a checklist that has been started, which sends every item with `deleted` 1;
  * the first "View Checklist" of a checklist that still shows its template's items, which copies them into the task with `convertTemplate` 1, together with [PUT /v1/app/tasks/{uuid}/todo-name](https://docs.snapfix.com/engineering-reference/api/tasks.md#put-v1apptasksuuidtodo-name).

**Request** (JSON body)

| Name              | In   | Type    | Required | Rules                                                |
| ----------------- | ---- | ------- | -------- | ---------------------------------------------------- |
| `jobUuid`         | body | string  | yes      | The task                                             |
| `convertTemplate` | body | integer | no       | `0` (default) or `1`; `1` skips the permission check |
| `todos`           | body | array   | yes      | The items to add, change or delete, as below         |

Each item in `todos`:

| Name                                                                                                                                         | Type           | Required | Rules                                                                                                                                                                                                                |
| -------------------------------------------------------------------------------------------------------------------------------------------- | -------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `uuid`                                                                                                                                       | string or null | no       | Empty for a new item. An existing item is changed by its UUID alone, with no check that it belongs to this task                                                                                                      |
| `itemType`                                                                                                                                   | integer        | yes      | `0` item, `1` section                                                                                                                                                                                                |
| `sortOrder`                                                                                                                                  | integer        | yes      | Position                                                                                                                                                                                                             |
| `name`                                                                                                                                       | string or null | no       | Item or section text                                                                                                                                                                                                 |
| `type`                                                                                                                                       | string         | no       | One of the answer types of [PUT /v1/app/todos/{uuid}](#put-v1apptodosuuid); switches that input on. `noteEnable` passes the rules, but on a new item the save fails with `500`, because the table has no such column |
| `radioEnable`, `yesnoEnable`, `starEnabled`, `sectionNaEnable`                                                                               | integer        | no       | `0` or `1`. Saved as `0` when not sent, also on an existing item                                                                                                                                                     |
| `done`, `deleted`, `radioMandatory`, `noteMandatory`, `todoMediaMandatory`, `notesEnable`, `nfcEnabled`, `nfcScanned`, `satisfactionEnabled` | integer        | no       | `0` or `1`. `deleted` 1 deletes the item                                                                                                                                                                             |
| `radioPassValue`, `radioFollowUpValue`, `radioFailValue`, `radioNaValue`, `sectionNaValue`                                                   | integer        | no       | `0` or `1`                                                                                                                                                                                                           |
| `yesnoValue`                                                                                                                                 | integer        | no       | `-1`, `0` or `1`                                                                                                                                                                                                     |
| `starValue`                                                                                                                                  | integer        | no       | `-1` to `5`                                                                                                                                                                                                          |
| `notesValue`, `nfcSerial`                                                                                                                    | string or null | no       | The note and the NFC tag serial                                                                                                                                                                                      |
| `subItems`                                                                                                                                   | array or null  | no       | Description lines, as in [PUT /v1/app/todos/{uuid}](#put-v1apptodosuuid); the lines sent replace the item's lines                                                                                                    |

A new item gets a new UUID, and the fields not sent start it unticked and unanswered.

**Response** `200`: `data.todos` is every item of the task, sorted by `sortOrder`, as [task checklist item objects](#task-checklist-item-object) with `media` and `subItems`; `data.jobchats` lists the chat lines written, as [chat item objects](https://docs.snapfix.com/engineering-reference/api/tasks.md#chat-item-object). The message is "Operation was successful".

```json
{
  "status": "success",
  "message": "Operation was successful",
  "data": {
    "todos": [ { "uuid": "todo-200", "name": "Check the door seal", "type": 0, "sortOrder": 1000, "isDone": 0, "media": [], "subItems": [] } ],
    "jobchats": [ { "uuid": "chat-301", "text": "<b>Jane</b> created checklist 'Check the door seal'", "type": 10 } ]
  }
}
```

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

**Side effects:**

* Inserts, updates and marks deleted [`tPri_JobTodo`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_jobtodo.md) rows, and syncs their lines in [`tPri_JobTodo_Notes`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_jobtodo_notes.md).
* Writes a chat line to [`tPri_JobChat`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_jobchat.md) for each added item or section ("created checklist", "created section"), each deleted one ("deleted checklist", "deleted section") and each changed item ("Edited Checklist name to ..."). A changed section gets no line.
* Touches the task. Sends a shown push for each added or deleted item and a silent update push for each changed item, to the task's people.

## GET /v1/app/todos/reset

Clears every answer of a task's checklist and deletes its photos and videos. The items themselves stay.

* **Auth:** user token. The task must be editable, and nothing else is checked, so any signed-in user can clear any task's checklist by its UUID. It is a `GET` that changes data.
* **Used by:** web, "Clear Checklist" in the checklist card's menu on the task's [checklist](https://docs.snapfix.com/how-the-apps-work/screens/checklists/checklist.md), after a confirmation (`ChecklistHttpService.clearChecklist`).

**Request**

| Name      | In    | Type   | Required | Rules    |
| --------- | ----- | ------ | -------- | -------- |
| `jobUuid` | query | string | yes      | The task |

**Response** `200`: `data.todos` is the task's items after the reset, as [task checklist item objects](#task-checklist-item-object) without `media` or `subItems`, and `data.jobchat` is the chat line. The message is "Checklist items are unchecked successfully".

```json
{
  "status": "success",
  "message": "Checklist items are unchecked successfully",
  "data": {
    "todos": [ { "uuid": "todo-200", "name": "Check the door seal", "type": 0, "isDone": 0, "completionTs": 0 } ],
    "jobchat": { "uuid": "chat-302", "text": "<b>Jane</b> unchecked all checklist items", "type": 41 }
  }
}
```

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

**Side effects:**

* On every item of the task in [`tPri_JobTodo`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_jobtodo.md): `fDone`, `fCompletionTs`, `nfcScanned`, the four radio values, `starValue` and `satisfactionValue` become 0, `yesnoValue` -1, and `notesValue` empty. The description lines stay.
* Marks every [`tPri_JobTodoMedia`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_jobtodomedia.md) row of the task deleted.
* Adds the chat line "{name} unchecked all checklist items" (type 41, `TODO_UNCHECKED_ALL`), touches the task, and sends a silent update push (`TODO_UNCHECKED_ALL`) to the task's people. No shown push.

## PUT /v1/app/todos/uncheck/{uuid}

Unticks one checklist item of a task.

* **Auth:** as [PUT /v1/app/todos/check/{uuid}](#put-v1apptodoscheckuuid): the task must be editable, and nothing else is checked.
* **Used by:** web, the item's tick box (`ChecklistHttpService.checklistItemDone` with `false`).

**Request**

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

No body.

**Response** `200`: as for [PUT /v1/app/todos/check/{uuid}](#put-v1apptodoscheckuuid), with the message "Checklist unchecked successfully". An item that isn't ticked is not changed: the answer has only `data.todo`.

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

**Side effects:** sets `fDone` to 0 in [`tPri_JobTodo`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_jobtodo.md); `fCompletionTs` stays. Adds the chat line "{name} unchecked '{item}'" (type 12, `TODO_UNSELECTED`), touches the task, and sends a silent update push (`TODO_UNSELECTED`) to the task's people.

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

Answers one checklist item of a task, or changes its note or description lines: pass, flag, fail or N/A, yes or no, a rating, a section's N/A switch, or a note.

* **Auth:** as [PUT /v1/app/todos/check/{uuid}](#put-v1apptodoscheckuuid): the task must be editable, and nothing else is checked. Only the settings route `PUT /v1/app/todos/settings/{uuid}`, which no client calls, checks the checklist permission.
* **Used by:** web, through `ChecklistHttpService.updateChecklistItem`: an item's answers and note (`TaskChecklistItemsComponent`) and a section's N/A switch (`TaskChecklistDetailsComponent`).

**Request** (JSON body)

| Name                                                                     | In   | Type           | Required | Rules                                                                                                                                                                                                                                                                                                                                     |
| ------------------------------------------------------------------------ | ---- | -------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `uuid`                                                                   | path | string         | yes      | The item                                                                                                                                                                                                                                                                                                                                  |
| `type`                                                                   | body | string         | yes      | `radioEnable`, `yesnoEnable`, `starEnabled`, `sectionNaEnable` or `noteEnable`. Any type but `sectionNaEnable` switches the item's input: `radioEnable`, `starEnabled` and `yesnoEnable` become 0 and the named one 1 (`noteEnable` leaves all three off). The web sends the item's current answer type, or `noteEnable` when it has none |
| `radioPassValue`, `radioFollowUpValue`, `radioFailValue`, `radioNaValue` | body | integer        | no       | `0` or `1`; `radioFollowUpValue` is the flag. More than one `1`: "If one of the elements is set to 1, the others must be 0."                                                                                                                                                                                                              |
| `yesnoValue`                                                             | body | integer        | no       | `-1` unanswered, `0` no, `1` yes                                                                                                                                                                                                                                                                                                          |
| `starValue`                                                              | body | integer        | no       | `-1` to `5`                                                                                                                                                                                                                                                                                                                               |
| `sectionNaValue`                                                         | body | integer        | no       | `-1`, `0` or `1`                                                                                                                                                                                                                                                                                                                          |
| `notesValue`                                                             | body | string or null | no       | The note                                                                                                                                                                                                                                                                                                                                  |
| `nfcSerial`                                                              | body | string or null | no       | The NFC tag serial                                                                                                                                                                                                                                                                                                                        |
| `nfcEnabled`, `nfcScanned`                                               | body | integer        | no       | `0` or `1`; accepted but not saved                                                                                                                                                                                                                                                                                                        |
| `subItems`                                                               | body | array or null  | no       | Description lines: `uuid` (none for a new line), `type` (`text`, `image`, `audio` or `video`; required), `value`, `sortOrder`, `deleted` (`0` or `1`). The lines sent replace the item's lines: lines not in the list are deleted, and `[]` deletes them all                                                                              |

`notesValue`, `nfcSerial` and `sectionNaValue` are saved when sent. The answer values are saved only for the named `type`, and one that isn't sent is saved as its default: the radio values 0, `yesnoValue` -1, `starValue` 0, `sectionNaValue` 1. With `type` `sectionNaEnable`, every item after this one up to the next section gets the same `sectionNaValue`.

**Response** `200`: `data.todo` is the changed item as a [task checklist item object](#task-checklist-item-object), with `media` and `subItems`. There is no `jobchat`. The message is "Checklist updated successfully".

```json
{
  "status": "success",
  "message": "Checklist updated successfully",
  "data": {
    "todo": { "uuid": "todo-200", "name": "Check the door seal", "type": 0, "settings": { "radio": { "enabled": 1, "failValue": 1, "flagValue": 0, "passValue": 0, "naValue": 0 } } }
  }
}
```

**Errors:** [common errors](#common-errors); `400` "The task can not be updated"; `404` for an unknown item; `422` for a missing or unknown `type`, a value out of range, or two radio values at once.

**Side effects:** updates the item in [`tPri_JobTodo`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_jobtodo.md), and with `subItems` its lines in [`tPri_JobTodo_Notes`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_jobtodo_notes.md). Touches the task and sends a silent update push (`TODO_INSTANT_UPDATE`) to the task's people. No chat line and no shown push.

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

Reads the checklist rows of one or more sites for the apps' local database: the sites' templates and, for sites in a multi-site, the multi-site's templates, with their folders, permission rows and task links, and the checklists, items, item notes and item media behind them.

* **Auth:** user token. The dispatcher checks the token only while `JWT_AUTH_ENABLED` is on, and the action reads the caller from the token's payload without checking its signature. With no Bearer token, which includes the shared Basic login used while `JWT_AUTH_ENABLED` is off, it answers "invalid access!" \[[ASK-12](https://github.com/snapfix/docs/blob/main/ASK.md#ask-12-which-settings-do-the-production-api-servers-use)]. The sites are not checked against the caller's memberships, so any signed-in user gets any site's checklists by its UUID.
* **Used by:** iOS (`APIManager.readChecklistData`: the sub-data download after sign-in, switching sites, and a task whose template is missing on the device), Android (`LoginSubDataWork` after sign-in, `BusinessViewModel` for newly added sites, `JobChatFragment` to refresh a task's checklist).

**Request** (JSON body)

| Name           | In   | Type            | Required | Rules                                                                                      |
| -------------- | ---- | --------------- | -------- | ------------------------------------------------------------------------------------------ |
| `parent_uuids` | body | array of string | yes      | Site UUIDs; duplicates are dropped. Missing, empty or not an array: "invalid parent uuids" |
| `user_uuid`    | body | string          | no       | iOS sends it; the server doesn't read it                                                   |

**Response** `200`: `data` is a [table data object](https://docs.snapfix.com/engineering-reference/api/tasks.md#table-data-object-php-apis) with up to twelve keys: `tPri_CL_MultiSiteTemplate`, `tPri_CL_MultiSiteTemplatePermissions`, `tPri_CL_MultiSiteTemplateVirtualFolders`, `tPri_CL_SiteTemplate`, `tPri_CL_SiteTemplatePermissions`, `tPri_CL_SiteTemplateVirtualFolders`, `tPri_Job_CL_Template`, `tPri_CL`, `tPri_CL_Item`, `tPri_CL_Item_Notes`, `tPri_CL_ItemMedia` and `tPri_CL_Permissions`. Each lists the table's rows that aren't deleted, with every column, in `fServerTs` order. A table with no rows is left out, except that `tPri_CL_Item_Notes` is `[]` when the checklists have no items at all. The message is "Values Found". When no table has rows, the answer is `result: true` with "Values not Found" and no `data`.

```json
{
  "result": true,
  "message": "Values Found",
  "serverTs": 1794387605000,
  "data": {
    "tPri_CL_SiteTemplate": [ { "uuid": "site-tpl-1", "uuid_tParent": "site-1", "uuid_tCL": "cl-1", "fName": "Room 101 checkout", "fDeleted": 0 } ],
    "tPri_CL": [ { "uuid": "cl-1", "fDeleted": 0 } ],
    "tPri_CL_Item": [ { "uuid": "item-1", "uuid_tCL": "cl-1", "fName": "Check the tap", "item_type": 0, "sort_order": 1000 } ]
  }
}
```

**Errors:** `200` with `result: false`: "Data cannot be blank!" for an empty body; "invalid parent uuids"; "invalid access!" when the token gives no user. A database error comes back the same way, with its text ([API conventions](https://docs.snapfix.com/engineering-reference/api.md#responses)).

**Side effects:** none; the reads use the read-only connection.

## POST ?action=save\_cl

Creates or changes checklists: the [`tPri_CL`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_cl.md) rows that templates point to. The apps' sync sends each checklist row changed on the device.

* **Auth:** user token while `JWT_AUTH_ENABLED` is on, otherwise the shared Basic login ([API conventions](https://docs.snapfix.com/engineering-reference/api.md#basic-logins)) \[[ASK-12](https://github.com/snapfix/docs/blob/main/ASK.md#ask-12-which-settings-do-the-production-api-servers-use)]. The rows' own user fields are saved as the actor; the token's user is not compared with them. No row is checked against the caller's sites, groups or tasks.
* **Used by:** iOS (`TaskManager.getCLTemplate`, in the sync queue), Android (`SyncRepository`, the `save_cl` sync task).

**Request** (JSON body)

| Name          | In   | Type            | Required | Rules                                                                                                                                                                                                                                                               |
| ------------- | ---- | --------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `insert_data` | body | array of object | yes      | Whole local rows of [`tPri_CL`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_cl.md); the apps send up to 500 per request. A row whose `uuid` exists is updated with every field sent; any other row is inserted. Field names reach the SQL as sent |

The other save actions below take the same body, with rows of their own table.

**Response** `200`: a [save result object](https://docs.snapfix.com/engineering-reference/api/tasks.md#save-result-object-php-apis); `result` is `false` when any row failed.

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

**Errors:** `200` with `result: false`: "Data cannot be blank!" for an empty body; "invalid access!" while the queue is on and the token gives no user. The same holds for every save action below, except that [`save_pri_job_todo`](#post-actionsave_pri_job_todo) answers an empty body with `{"success": "0", ...}`.

**Side effects:**

* Inserts or updates [`tPri_CL`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_cl.md) rows by `uuid`.
* While the server setting `LEGACY_QUEUE_SUPPORT` is on, the rows go to [`tPri_Queue`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_queue.md) instead and every row counts as inserted, as the [save result object](https://docs.snapfix.com/engineering-reference/api/tasks.md#save-result-object-php-apis) says \[[ASK-12](https://github.com/snapfix/docs/blob/main/ASK.md#ask-12-which-settings-do-the-production-api-servers-use)]. Only in this mode does a row sent without a `uuid` get one.
* After answering, the dispatcher runs the queue step (`processLogQueue`), which applies every uncommitted queue row of the last hour while a queue setting is on. `save_cl_permissions`, `save_cl_site_template`, `save_cl_site_template_permissions`, `save_job_cl_template`, `save_pri_job_todo` and `save_pri_job_todo_media` run it too. `save_cl_item`, `save_cl_item_notes` and `save_pri_job_todo_notes` don't, so their queued rows wait for another action's run.

## POST ?action=save\_cl\_item

Creates or changes the sections and items of checklists ([`tPri_CL_Item`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_cl_item.md)), the items behind templates.

* **Auth:** as [`save_cl`](#post-actionsave_cl).
* **Used by:** iOS (`TaskManager.getCLItem`), Android (`SyncRepository`, `save_cl_item`).

**Request:** `insert_data` as for [`save_cl`](#post-actionsave_cl), with [`tPri_CL_Item`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_cl_item.md) rows: `uuid`, `uuid_tCL`, `fName`, `item_type`, `sort_order`, `fDone`, the enable, answer and mandatory columns, and `fDeleted`.

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

**Errors:** as for [`save_cl`](#post-actionsave_cl).

**Side effects:** inserts or updates [`tPri_CL_Item`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_cl_item.md) rows. After answering, when the save succeeded, writes one [activity line](#checklist-activity-object) to [`tPri_ChecklistLog`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_checklistlog.md) for each site template that uses those checklists (`saveCL_AuditLine`): `template_update` ("updated site template item ...") when the template has log lines already or is more than two minutes old, otherwise `template_create` ("created site template item ..."). The line's user is the modifier, or else the creator, of the last row sent (`admin` when neither is set), and the whole request is stored with it. Multi-site templates get no line.

## POST ?action=save\_cl\_item\_notes

Creates or changes the notes of checklist template items ([`tPri_CL_Item_Notes`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_cl_item_notes.md)): text, image, audio or video lines.

* **Auth:** as [`save_cl`](#post-actionsave_cl).
* **Used by:** iOS (`TaskManager.getCLItemNotes`), Android (`SyncRepository`, `save_cl_item_notes`).

**Request:** `insert_data` as for [`save_cl`](#post-actionsave_cl), with [`tPri_CL_Item_Notes`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_cl_item_notes.md) rows: `uuid`, `uuid_tCL_Item`, `fType`, `fValue`, `sort_order` and `fDeleted`.

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

**Errors:** as for [`save_cl`](#post-actionsave_cl).

**Side effects:** inserts or updates [`tPri_CL_Item_Notes`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_cl_item_notes.md) rows. No queue step after answering ([`save_cl`](#post-actionsave_cl)).

## POST ?action=save\_cl\_permissions

Creates or changes checklist permission rows ([`tPri_CL_Permissions`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_cl_permissions.md)), which the site and multi-site template permission tables point to.

* **Auth:** as [`save_cl`](#post-actionsave_cl).
* **Used by:** iOS (`TaskManager.getCLPermissions`), Android (`SyncRepository`, `save_cl_permissions`).

**Request:** `insert_data` as for [`save_cl`](#post-actionsave_cl), with [`tPri_CL_Permissions`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_cl_permissions.md) rows: `uuid`, `uuid_tMultiSite`, `uuid_tParent`, `uuid_tBusiness`, `fVisible` and `fDeleted`.

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

**Errors:** as for [`save_cl`](#post-actionsave_cl).

**Side effects:** inserts or updates [`tPri_CL_Permissions`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_cl_permissions.md) rows, then runs the queue step after answering.

## POST ?action=save\_cl\_site\_template

Creates or changes site checklist templates ([`tPri_CL_SiteTemplate`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_cl_sitetemplate.md)).

* **Auth:** as [`save_cl`](#post-actionsave_cl).
* **Used by:** iOS (`TaskManager.getCLSiteTemplate`), Android (`SyncRepository`, `save_cl_site_template`).

**Request:** `insert_data` as for [`save_cl`](#post-actionsave_cl), with [`tPri_CL_SiteTemplate`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_cl_sitetemplate.md) rows: `uuid`, `uuid_tParent`, `uuid_tCL`, `fName`, `fDescription`, `fNote`, `fSignatureRequired`, `uuid_tCL_SiteTemplateVirtualFolder_CSV` (the template's folders) and `fDeleted`. The apps set `fSignatureRequired` on the device: iOS when it creates a template, Android when the signature switch changes on a task that still shows the template's items.

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

**Errors:** as for [`save_cl`](#post-actionsave_cl).

**Side effects:** inserts or updates [`tPri_CL_SiteTemplate`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_cl_sitetemplate.md) rows, then runs the queue step after answering.

## POST ?action=save\_cl\_site\_template\_permissions

Creates or changes the links between site templates and permission rows ([`tPri_CL_SiteTemplatePermissions`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_cl_sitetemplatepermissions.md)).

* **Auth:** as [`save_cl`](#post-actionsave_cl).
* **Used by:** iOS (`TaskManager.getCLSiteTemplatePermissions`), Android (`SyncRepository`, `save_cl_site_template_permissions`).

**Request:** `insert_data` as for [`save_cl`](#post-actionsave_cl), with [`tPri_CL_SiteTemplatePermissions`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_cl_sitetemplatepermissions.md) rows: `uuid`, `uuid_tCL_SiteTemplate`, `uuid_tCL_Permissions` and `fDeleted`.

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

**Errors:** as for [`save_cl`](#post-actionsave_cl).

**Side effects:** inserts or updates [`tPri_CL_SiteTemplatePermissions`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_cl_sitetemplatepermissions.md) rows, then runs the queue step after answering.

## POST ?action=save\_job\_cl\_template

Creates or changes the links between tasks and checklist templates ([`tPri_Job_CL_Template`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_job_cl_template.md)): which template a task's checklist comes from.

* **Auth:** as [`save_cl`](#post-actionsave_cl); neither the task nor the template is checked.
* **Used by:** iOS (`TaskManager.getJobCLTemplate`), Android (`SyncRepository`, `save_job_cl_template`).

**Request:** `insert_data` as for [`save_cl`](#post-actionsave_cl), with [`tPri_Job_CL_Template`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_job_cl_template.md) rows: `uuid`, `uuid_tJob`, `uuid_tSiteTemplate` or `uuid_tMultiSiteTemplate`, and `fDeleted`.

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

**Errors:** as for [`save_cl`](#post-actionsave_cl).

**Side effects:** inserts or updates [`tPri_Job_CL_Template`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_job_cl_template.md) rows, then runs the queue step after answering.

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

Creates or changes the checklist items of tasks ([`tPri_JobTodo`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_jobtodo.md)). The apps tick, answer and edit items on the device and send the changed rows; the web does the same through the `/v1/app/todos` routes.

* **Auth:** as [`save_cl`](#post-actionsave_cl). Neither the caller's access to the task nor the task's lock is checked, and neither are the mandatory note and photo.
* **Used by:** iOS (`TaskManager.getPendingJobTodo`), Android (`SyncRepository`, `save_pri_job_todo`).

**Request:** `insert_data` as for [`save_cl`](#post-actionsave_cl), with [`tPri_JobTodo`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_jobtodo.md) rows: `uuid`, `uuid_tJob`, `uuid_tBusiness`, `fName`, `item_type`, `sort_order`, `fDone`, the enable, answer and mandatory columns, and `fDeleted`.

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

**Errors:** as for [`save_cl`](#post-actionsave_cl), except that an empty body answers `{"success": "0", "message": "Data cannot be blank!"}`.

**Side effects:** inserts or updates [`tPri_JobTodo`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_jobtodo.md) rows, then runs the queue step after answering.

## POST ?action=save\_pri\_job\_todo\_media

Creates or changes the photos and videos of task checklist items ([`tPri_JobTodoMedia`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_jobtodomedia.md)).

* **Auth:** as [`save_cl`](#post-actionsave_cl). Foreign keys are not checked while these rows are saved.
* **Used by:** iOS (`TaskManager.getPendingJobTodoMedia`), Android (`SyncRepository`, `save_pri_job_todo_media`).

**Request:** `insert_data` as for [`save_cl`](#post-actionsave_cl), with [`tPri_JobTodoMedia`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_jobtodomedia.md) rows: `uuid`, `uuid_tJobTodo`, `uuid_tJob`, `uuid_tBusiness`, `fType`, `media_url`, `thumb_url` and `fDeleted`.

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

**Errors:** as for [`save_cl`](#post-actionsave_cl).

**Side effects:** inserts or updates [`tPri_JobTodoMedia`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_jobtodomedia.md) rows, then runs the queue step after answering.

## POST ?action=save\_pri\_job\_todo\_notes

Creates or changes the notes of task checklist items ([`tPri_JobTodo_Notes`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_jobtodo_notes.md)), the lines the web shows as an item's description.

* **Auth:** as [`save_cl`](#post-actionsave_cl).
* **Used by:** iOS (`TaskManager.getPendingJobTodoNotes`), Android (`SyncRepository`, `save_pri_job_todo_notes`).

**Request:** `insert_data` as for [`save_cl`](#post-actionsave_cl), with [`tPri_JobTodo_Notes`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_jobtodo_notes.md) rows: `uuid`, `uuid_tJobTodo`, `fType`, `fValue`, `sort_order` and `fDeleted`.

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

**Errors:** as for [`save_cl`](#post-actionsave_cl).

**Side effects:** inserts or updates [`tPri_JobTodo_Notes`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_jobtodo_notes.md) rows. No queue step after answering ([`save_cl`](#post-actionsave_cl)).

## Checklist template object

A library, site or multi-site template, as the template and library routes return it (`ChecklistLibraryResource`).

| Field                                                                           | Type                                                      | Meaning                                                                                                                                                                                                                                                                                                                                                     |
| ------------------------------------------------------------------------------- | --------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `uuid`                                                                          | string                                                    | The template: a row of [`tPri_CL_SiteTemplate`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_cl_sitetemplate.md), [`tPri_CL_MultiSiteTemplate`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_cl_multisitetemplate.md) or [`tPri_CL_Library`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_cl_library.md) |
| `checklistUuid`                                                                 | string                                                    | Its [`tPri_CL`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_cl.md) checklist, which holds the items                                                                                                                                                                                                                                       |
| `name`, `description`, `note`                                                   | string or null                                            | The template's name and texts                                                                                                                                                                                                                                                                                                                               |
| `signatureRequired`                                                             | integer                                                   | `1` when tasks with this checklist need a signature                                                                                                                                                                                                                                                                                                         |
| `siteTemplateFolderUuids`, `multiSiteTemplateFolderUuids`, `libraryFolderUuids` | array of string                                           | The folders the template is filed in. Only the template's own kind is present, and only when it has a folder                                                                                                                                                                                                                                                |
| `version`, `sortOrder`                                                          | integer                                                   | Stored values                                                                                                                                                                                                                                                                                                                                               |
| `isArchived`, `visible`, `locked`, `priority`                                   | integer                                                   | Stored flags                                                                                                                                                                                                                                                                                                                                                |
| `modifiedTs`                                                                    | integer                                                   | Last change, in ms                                                                                                                                                                                                                                                                                                                                          |
| `tags`                                                                          | array                                                     | Only in [the library list](#post-v1appchecklistslibrary): `uuid`, `name` and `tagHeader` (`uuid`, `name`)                                                                                                                                                                                                                                                   |
| `checklistItems`                                                                | array of [checklist item objects](#checklist-item-object) | Only on the single-template reads. Not sorted: order them by `sortOrder`                                                                                                                                                                                                                                                                                    |

## Checklist item object

A section or item of a template's checklist (`ChecklistItemResource`), in `checklistItems`. The items on a task have a similar shape, described with the checklist item routes.

| Field                                              | Type    | Meaning                                                                                                                                                                                                                                                     |
| -------------------------------------------------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `uuid`, `checklistUuid`, `name`                    | string  | The item, its checklist and its text                                                                                                                                                                                                                        |
| `type`                                             | integer | `0` item, `1` section                                                                                                                                                                                                                                       |
| `sortOrder`                                        | integer | Position                                                                                                                                                                                                                                                    |
| `isDone`, `completionTs`                           | integer | Stored values                                                                                                                                                                                                                                               |
| `mandatory`, `noteMandatory`, `todoMediaMandatory` | integer | `1` when the item must be ticked, needs a note, or needs a photo                                                                                                                                                                                            |
| `media`                                            | array   | The item's photos and videos ([`tPri_CL_ItemMedia`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_cl_itemmedia.md)): `uuid`, `checklistItemUuid`, `checklistUuid`, `type`, `mediaUrl`, `thumbUrl`                                           |
| `subItems`                                         | array   | The item's notes, in order: `uuid`, `type` (`text`, `image`, `audio` or `video`), `value`, `sortOrder`                                                                                                                                                      |
| `settings`                                         | object  | `nfc` (`enabled`, `value`: the tag's serial, `scanned`), `notes` (`enabled`, `value`), `radio` (`enabled`, `passValue`, `failValue`, `flagValue`, `naValue`), `rating` (`enabled`, `value`), `yesNo` (`enabled`, `value`), `sectionNa` (`enabled`, `value`) |

## Task checklist item object

A checklist item or section of a task (`TodoResource`), from [`tPri_JobTodo`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_jobtodo.md). The template fallback of [GET /v1/app/todos](#get-v1apptodos) returns the template's items in the same shape.

| Field                                 | Type    | Meaning                                                                                                                                                                                                                                                                                                       |
| ------------------------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `uuid`                                | string  | The item                                                                                                                                                                                                                                                                                                      |
| `name`                                | string  | Item or section text                                                                                                                                                                                                                                                                                          |
| `type`                                | integer | `0` item, `1` section                                                                                                                                                                                                                                                                                         |
| `sortOrder`                           | integer | Position; the web and the server space items 1000 apart                                                                                                                                                                                                                                                       |
| `isDone`                              | integer | `1` when ticked                                                                                                                                                                                                                                                                                               |
| `mandatory`                           | integer | `1` when the item must be ticked before the checklist is signed off; the server checks it only at sign-off ([POST /v1/app/tasks/{uuid}/signature](https://docs.snapfix.com/engineering-reference/api/tasks.md#post-v1apptasksuuidsignature))                                                                  |
| `noteMandatory`, `todoMediaMandatory` | integer | `1` when the item needs a note or a photo. The web and both apps ask for it before a tick; the server checks it only at sign-off                                                                                                                                                                              |
| `completionTs`                        | integer | When the item was first ticked, in ms; unticking keeps it, a reset clears it                                                                                                                                                                                                                                  |
| `modifiedTs`                          | integer | Last change, in ms                                                                                                                                                                                                                                                                                            |
| `media`                               | array   | Only where the section says so: the item's photos and videos, each `uuid`, `todoUuid` (the item), `jobUuid` (the task), `type` (`Image` or `Video`), `mediaUrl` and `thumbUrl`                                                                                                                                |
| `subItems`                            | array   | Only where the section says so: the item's description lines ([`tPri_JobTodo_Notes`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_jobtodo_notes.md)), each `uuid`, `type` (`text`, `image`, `audio` or `video`), `value` and `sortOrder`. The web shows their text as the item's description |
| `settings.nfc`                        | object  | `enabled`, `value` (the expected tag serial), `scanned`                                                                                                                                                                                                                                                       |
| `settings.notes`                      | object  | `enabled`, `value` (the note)                                                                                                                                                                                                                                                                                 |
| `settings.radio`                      | object  | Pass, flag, fail and N/A: `enabled`, `passValue`, `flagValue` (stored as `radioFollowUpValue`), `failValue`, `naValue`                                                                                                                                                                                        |
| `settings.rating`                     | object  | `enabled`, `value` (`-1` unanswered, `0` to `5`)                                                                                                                                                                                                                                                              |
| `settings.yesNo`                      | object  | `enabled`, `value` (`-1` unanswered, `0` no, `1` yes)                                                                                                                                                                                                                                                         |
| `settings.sectionNa`                  | object  | A section's N/A switch: `enabled`, `value`. With the switch enabled, `0` marks the section N/A and its items leave the checklist percentage; `1` counts them                                                                                                                                                  |

## Template item body

An entry of `todos` in [POST /v1/app/checklists/{scope}/templates](#post-v1appchecklistsscopetemplates) and [PUT /v1/app/checklists/{scope}/templates/{templateUuid}](#put-v1appchecklistsscopetemplatestemplateuuid). A section is an entry with `itemType` 1; the items after it, by `sortOrder`, belong to it.

| Name                                                    | Type           | Required | Rules                                                                                                                                                                                                                                                                                     |
| ------------------------------------------------------- | -------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `uuid`                                                  | string or null | no       | Empty for a new item. A sent UUID changes that existing item, whatever checklist it belongs to, also on create                                                                                                                                                                            |
| `name`                                                  | string or null | no       | The item or section text                                                                                                                                                                                                                                                                  |
| `itemType`                                              | integer        | yes      | `0` item, `1` section                                                                                                                                                                                                                                                                     |
| `sortOrder`                                             | integer        | yes      | Position                                                                                                                                                                                                                                                                                  |
| `type`                                                  | string         | no       | `radioEnable` (pass, flag, fail, N/A), `yesnoEnable`, `starEnabled` (rating), `sectionNaEnable` or `noteEnable`. Switches that answer type on and the other answer types off. `noteEnable` passes the rules, but the item table has no such column, so the save fails with a server error |
| `radioMandatory`, `noteMandatory`, `todoMediaMandatory` | integer        | no       | `0` or `1`: the item must be ticked, needs a note, or needs a photo                                                                                                                                                                                                                       |
| `nfcEnabled`, `notesEnable`                             | integer        | no       | `0` or `1`: the item uses an NFC tag; notes are allowed                                                                                                                                                                                                                                   |
| `nfcSerial`                                             | string or null | no       | The NFC tag's serial; `0` on a new item without one                                                                                                                                                                                                                                       |
| `deleted`                                               | integer        | no       | `1` deletes an existing item                                                                                                                                                                                                                                                              |
| `subItems`                                              | array or null  | no       | The item's notes: `uuid` (empty for a new note), `type` (`text`, `image`, `audio` or `video`; required), `value`, `sortOrder` (1000 by default), `deleted` (`1` deletes)                                                                                                                  |

A new item also gets `yesnoValue` -1.

## Checklist folder object

A site or multi-site folder (`ChecklistFolderResource`), a row of [`tPri_CL_SiteTemplateVirtualFolders`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_cl_sitetemplatevirtualfolders.md) or [`tPri_CL_MultiSiteTemplateVirtualFolders`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_cl_multisitetemplatevirtualfolders.md).

| Field                         | Type            | Meaning                                                                                                                                                                                                   |
| ----------------------------- | --------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `uuid`                        | string          | The folder                                                                                                                                                                                                |
| `multiSiteUuid`, `siteUuid`   | string or null  | The owner: one of the two is set                                                                                                                                                                          |
| `name`, `description`, `note` | string or null  | The folder's name and texts                                                                                                                                                                               |
| `sortOrder`                   | integer or null | Position                                                                                                                                                                                                  |
| `checklistCount`              | integer or null | Templates filed in the folder that aren't deleted. On the group and site picker lists, only those visible to the group or site, or with no permission row for it. `null` in the create and change answers |

## Checklist job object

A task that uses a template (`ChecklistJobsResource`), from [`tPri_Job`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_job.md). The task lists answer `{ "jobs": [...], "totalCount": { "red": 0, "amber": 0, "green": 0 } }`, where `totalCount` counts the tasks by colour.

| Field                               | Type           | Meaning                                                                                              |
| ----------------------------------- | -------------- | ---------------------------------------------------------------------------------------------------- |
| `uuid`                              | string         | The task                                                                                             |
| `color`                             | string         | `red`, `amber` or `green`; old tasks may say `yellow`, which counts as amber                         |
| `title`, `largeTitle`, `image`      | string or null | The task's title, large text and image                                                               |
| `priority`                          | integer        | The old star flag                                                                                    |
| `priorityLevel`                     | integer        | The priority level; `20` when the star is set and the level is 0                                     |
| `dueDateTs`, `dueDateDailyReminder` | integer        | The due date in ms, and the daily reminder flag                                                      |
| `modifiedTs`                        | integer        | The task's last chat change (`fJobChatModifiedTs`), in ms                                            |
| `checklistPercent`                  | integer        | The share of the task's own items that are ticked; `0` for a task that has only the template's items |

## Checklist permission object

A site or group in the permission lists. Site rows (`MultiSiteParentPermissionResource`) have `uuid`, `name`, `image` and `visible`. Group rows (`MultiSiteBusinessPermissionResource`) have `uuid`, `name`, `image`, `type` (the group's [`enum_BusinessType`](https://docs.snapfix.com/engineering-reference/db/tables/enum_businesstype.md)) and `visible`. `visible` is `1` when the template shows for that site or group, which is also the answer when there is no permission row.

## Checklist activity object

A line of a template's activity log (`ChecklistActivityResource`), from [`tPri_ChecklistLog`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_checklistlog.md). The template routes write them ([common side effects](#common-side-effects)), and so does [`?action=save_cl_item`](#post-actionsave_cl_item).

| Field                     | Type           | Meaning                                                                                                                                                                              |
| ------------------------- | -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `uuid`                    | string         | The line                                                                                                                                                                             |
| `entityUuid`              | string         | The template                                                                                                                                                                         |
| `text`                    | string         | HTML, such as `created site template item <b>"Fire door check"</b>` or `moved multi site template item …`. The template name is put in unescaped, and the web shows the text as HTML |
| `action`                  | string         | `template_create`, `template_download`, `template_update`, `template_copy`, `template_move` or `template_remove`                                                                     |
| `entity`                  | string         | `site` or `multi_site`                                                                                                                                                               |
| `createdTs`, `modifiedTs` | integer        | In ms                                                                                                                                                                                |
| `user`                    | object or null | The author: `uuid`, `name`, `image`, `username`, and `businessName`, which is always `null`. `null` when the author isn't found                                                      |

## Checklist tag header object

A tag header of the library (`ChecklistTagHeaderResource`, [`tPri_CL_TagHeader`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_cl_tagheader.md)): `uuid`, `name` and `tags`, a list of `{ "uuid", "name" }` ([`tPri_CL_Tag`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_cl_tag.md)).

## Common side effects

What the sections mean by these words. The effects of the checklist item routes on their task (audit lines, viewed rows, pushes) are the tasks group's [common side effects](https://docs.snapfix.com/engineering-reference/api/tasks.md#common-side-effects).

* **Activity line:** a row in [`tPri_ChecklistLog`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_checklistlog.md) for the template that was created or changed (for a copy or move, the new template), written by a queued job with the caller as the author and the whole request as `request_json`. Only template changes write one: the log calls of the folder, permission, task and schedule routes are commented out. The fields are in the [checklist activity object](#checklist-activity-object).
* **Touch:** the task's `fModifiedTs`, `fJobChatModifiedTs` and `fServerTs` in [`tPri_Job`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_job.md) become now, and the caller is saved as the modifier, so the apps' polling sees the change.
* **Template push:** a silent `JOB_CHECKLIST_TEMPLATE_MODIFY` update for each task, carrying its template link row, to the devices of the task's assignees and of its followers other than the caller.

## Common errors

The checklist routes of api\_php\_live\_v2 answer with the envelope and the codes in the tasks group's [common errors](https://docs.snapfix.com/engineering-reference/api/tasks.md#common-errors). The checklist code adds:

* A success with no data is `{ "status": "success", "message": "Operation was successful", "data": null }`.
* `403` "Access denied" when an [access check](#checklist-access-checks) fails.
* `404` "Resource not found" for a template, folder, group or task ID that doesn't exist.
* `400` with the text `messages.is_not_an_multisite_parent`, a message key with no text, when a site or a group's site is not in the multi-site.
* `422` with the first failed rule's message.

The php-apis actions answer as the [API conventions](https://docs.snapfix.com/engineering-reference/api.md#responses) describe.


---

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