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

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

Snapfix Comply: compliance systems and their types, contractors, documents and document types, with the dashboard overviews, the timelines and a system's activity log. The web app's Comply pages call almost all of it. The mobile apps only download system types, systems and task links, and upload task links, through two php-apis actions. The screens are in [Compliance screens](https://docs.snapfix.com/how-the-apps-work/screens/compliance.md).

A **compliance item** is a system or a contractor. Both have an expiry date, an alert window and a colour worked out from the two ([Compliance item object](#compliance-item-object)). A system belongs to a system type, and a system type to a site; a contractor belongs to a site directly. Deletes are soft: they set `fDeleted` on one row and leave the rows that point at it ([Common side effects](#common-side-effects)).

* **Services:** `api_php_live_v2` at `https://z4.snapfix.com` (`/v1/app`); `php-apis` at `https://z1.snapfix.com/api/snapfix/index.php`
* **Auth:** api\_php\_live\_v2: user token (authpy access JWT in `Authorization: Bearer`, see [user tokens](https://docs.snapfix.com/engineering-reference/api.md#user-tokens)).
  * Reads need a current membership of the site: a site relation, or a current group in the site. This covers the contractor, system, system type, document type and document lists, getting a contractor, a system or a document, and the system-type and contractor timelines \[[ASK-112](https://github.com/snapfix/docs/blob/main/ASK.md#ask-112-which-comply-reads-should-members-who-are-not-admins-get)]. The web opens Comply to site admins only (`authAdminGuard` and `authComplyGuard`, web\_app\_v2 @ 0989b8e685, `src/app/app.routes.ts:186`), but the task page's system pickers read the system type and system lists as any member. Which reads members should get is open \[[ASK-112](https://github.com/snapfix/docs/blob/main/ASK.md#ask-112-which-comply-reads-should-members-who-are-not-admins-get)].
  * Writes, getting one system type, the four overviews, the system and task timelines and the defaults need the site's admin role: `ParentPolicy::operate` passes only when the caller's site relation has `user_type` `admin`. So two timelines admit members and two need admins \[[ASK-112](https://github.com/snapfix/docs/blob/main/ASK.md#ask-112-which-comply-reads-should-members-who-are-not-admins-get)].
  * Exceptions: the two sort endpoints check membership, not the admin role \[[ASK-112](https://github.com/snapfix/docs/blob/main/ASK.md#ask-112-which-comply-reads-should-members-who-are-not-admins-get)]. [A system's activities](#get-v1appcomplysystemuuidactivities) checks only the token. [Frequencies](#get-v1appfrequencies) is a fixed list behind the token. The two task endpoints need membership of the task's group.
  * php-apis: user token (Bearer JWT, if `JWT_AUTH_ENABLED` is on \[[ASK-12](https://github.com/snapfix/docs/blob/main/ASK.md#ask-12-which-settings-do-the-production-api-servers-use)]). Neither action checks the caller's sites or tasks, and saved rows keep the user fields they are sent with.
* **Used by:** web\_app\_v2 (the Comply pages, the task page's compliance tab, and the planned task editor's compliance tab, which reads systems but saves nothing here); iOS and Android (the two php-apis actions only). 44 Laravel endpoints have a web caller; 6 of the 52 endpoints have no known caller. py\_scheduler and apipy also write task-system links straight to the database when they create planned tasks (py\_scheduler @ c8b1344036, `models/feature_job_from_scheduler.py:499`; apipy @ 0e83c85e5a, `model/scheduler_task/feature_job.py:503`).
* **Answers:** api\_php\_live\_v2 answers `{"status": "success", "message": "Operation was successful", "data": ...}` and fails with `{"status": "error", "message": "..."}`. Every endpoint can also answer the errors in [API conventions](https://docs.snapfix.com/engineering-reference/api.md#responses): `401` for a missing or bad token, `403` "Access denied" for a failed site check, `404` "Resource not found" for an unknown or deleted UUID, `422` with the first validation message, and `400` with the message of a rule the handler checks. None of the lists is paged. The php-apis actions answer with `result` ([responses](https://docs.snapfix.com/engineering-reference/api.md#responses)).

The compliance report, `GET /v1/app/report/comply`, is in [Reports](https://docs.snapfix.com/engineering-reference/api/reports.md).

| Method | Path                                                                                                | Service            | Purpose                                          |
| ------ | --------------------------------------------------------------------------------------------------- | ------------------ | ------------------------------------------------ |
| GET    | [`/v1/app/comply/contractor`](#get-v1appcomplycontractor)                                           | api\_php\_live\_v2 | List contractors                                 |
| POST   | [`/v1/app/comply/contractor`](#post-v1appcomplycontractor)                                          | api\_php\_live\_v2 | Create a contractor                              |
| POST   | [`/v1/app/comply/contractor/assign`](#post-v1appcomplycontractorassign)                             | api\_php\_live\_v2 | Assign a user to a contractor                    |
| POST   | [`/v1/app/comply/contractor/link-asset`](#post-v1appcomplycontractorlink-asset)                     | api\_php\_live\_v2 | Link assets to a contractor                      |
| POST   | `/v1/app/comply/contractor/sort`                                                                    | api\_php\_live\_v2 | Sort contractors (no caller)                     |
| POST   | [`/v1/app/comply/contractor/unassign`](#post-v1appcomplycontractorunassign)                         | api\_php\_live\_v2 | Unassign a user from a contractor                |
| POST   | [`/v1/app/comply/contractor/unlink-asset`](#post-v1appcomplycontractorunlink-asset)                 | api\_php\_live\_v2 | Unlink assets from a contractor                  |
| GET    | [`/v1/app/comply/contractor/{uuid}`](#get-v1appcomplycontractoruuid)                                | api\_php\_live\_v2 | Get a contractor                                 |
| PUT    | [`/v1/app/comply/contractor/{uuid}`](#put-v1appcomplycontractoruuid)                                | api\_php\_live\_v2 | Change a contractor                              |
| DELETE | [`/v1/app/comply/contractor/{uuid}`](#delete-v1appcomplycontractoruuid)                             | api\_php\_live\_v2 | Delete a contractor                              |
| GET    | `/v1/app/comply/document`                                                                           | api\_php\_live\_v2 | List compliance documents in folders (no caller) |
| POST   | [`/v1/app/comply/document`](#post-v1appcomplydocument)                                              | api\_php\_live\_v2 | Create a compliance document                     |
| GET    | [`/v1/app/comply/document/type`](#get-v1appcomplydocumenttype)                                      | api\_php\_live\_v2 | List document types                              |
| POST   | [`/v1/app/comply/document/type`](#post-v1appcomplydocumenttype)                                     | api\_php\_live\_v2 | Create a document type                           |
| PUT    | `/v1/app/comply/document/type/{uuid}`                                                               | api\_php\_live\_v2 | Change a document type (no caller)               |
| DELETE | `/v1/app/comply/document/type/{uuid}`                                                               | api\_php\_live\_v2 | Delete a document type (no caller)               |
| GET    | `/v1/app/comply/document/{uuid}`                                                                    | api\_php\_live\_v2 | Get a compliance document (no caller)            |
| PUT    | [`/v1/app/comply/document/{uuid}`](#put-v1appcomplydocumentuuid)                                    | api\_php\_live\_v2 | Change a compliance document                     |
| DELETE | [`/v1/app/comply/document/{uuid}`](#delete-v1appcomplydocumentuuid)                                 | api\_php\_live\_v2 | Delete a compliance document                     |
| GET    | [`/v1/app/comply/overview/document/{parentUuid}`](#get-v1appcomplyoverviewdocumentparentuuid)       | api\_php\_live\_v2 | Get a site's compliance document overview        |
| GET    | [`/v1/app/comply/overview/job/{parentUuid}`](#get-v1appcomplyoverviewjobparentuuid)                 | api\_php\_live\_v2 | Get a site's compliance task overview            |
| GET    | [`/v1/app/comply/overview/system-type/{parentUuid}`](#get-v1appcomplyoverviewsystem-typeparentuuid) | api\_php\_live\_v2 | Get a site's system type overview                |
| GET    | [`/v1/app/comply/overview/system/{parentUuid}`](#get-v1appcomplyoverviewsystemparentuuid)           | api\_php\_live\_v2 | Get a site's compliance system overview          |
| GET    | [`/v1/app/comply/system`](#get-v1appcomplysystem)                                                   | api\_php\_live\_v2 | List compliance systems                          |
| POST   | [`/v1/app/comply/system`](#post-v1appcomplysystem)                                                  | api\_php\_live\_v2 | Create a compliance system                       |
| GET    | [`/v1/app/comply/system-type`](#get-v1appcomplysystem-type)                                         | api\_php\_live\_v2 | List system types                                |
| POST   | [`/v1/app/comply/system-type`](#post-v1appcomplysystem-type)                                        | api\_php\_live\_v2 | Create a system type                             |
| POST   | [`/v1/app/comply/system-type/sort`](#post-v1appcomplysystem-typesort)                               | api\_php\_live\_v2 | Sort system types                                |
| GET    | `/v1/app/comply/system-type/{uuid}`                                                                 | api\_php\_live\_v2 | Get a system type (no caller)                    |
| PUT    | [`/v1/app/comply/system-type/{uuid}`](#put-v1appcomplysystem-typeuuid)                              | api\_php\_live\_v2 | Change a system type                             |
| DELETE | [`/v1/app/comply/system-type/{uuid}`](#delete-v1appcomplysystem-typeuuid)                           | api\_php\_live\_v2 | Delete a system type                             |
| POST   | [`/v1/app/comply/system/assign`](#post-v1appcomplysystemassign)                                     | api\_php\_live\_v2 | Assign a user to a compliance system             |
| POST   | [`/v1/app/comply/system/link-asset`](#post-v1appcomplysystemlink-asset)                             | api\_php\_live\_v2 | Link assets to a compliance system               |
| POST   | [`/v1/app/comply/system/link-contractor`](#post-v1appcomplysystemlink-contractor)                   | api\_php\_live\_v2 | Link a contractor to a compliance system         |
| POST   | [`/v1/app/comply/system/sort`](#post-v1appcomplysystemsort)                                         | api\_php\_live\_v2 | Sort compliance systems                          |
| POST   | [`/v1/app/comply/system/unassign`](#post-v1appcomplysystemunassign)                                 | api\_php\_live\_v2 | Unassign a user from a compliance system         |
| POST   | [`/v1/app/comply/system/unlink-asset`](#post-v1appcomplysystemunlink-asset)                         | api\_php\_live\_v2 | Unlink assets from a compliance system           |
| POST   | [`/v1/app/comply/system/unlink-contractor`](#post-v1appcomplysystemunlink-contractor)               | api\_php\_live\_v2 | Unlink a contractor from a compliance system     |
| GET    | [`/v1/app/comply/system/{uuid}`](#get-v1appcomplysystemuuid)                                        | api\_php\_live\_v2 | Get a compliance system                          |
| PUT    | [`/v1/app/comply/system/{uuid}`](#put-v1appcomplysystemuuid)                                        | api\_php\_live\_v2 | Change a compliance system                       |
| DELETE | [`/v1/app/comply/system/{uuid}`](#delete-v1appcomplysystemuuid)                                     | api\_php\_live\_v2 | Delete a compliance system                       |
| GET    | [`/v1/app/comply/system/{uuid}/activities`](#get-v1appcomplysystemuuidactivities)                   | api\_php\_live\_v2 | List a compliance system's activities            |
| GET    | [`/v1/app/comply/timeline/contractor/{parentUuid}`](#get-v1appcomplytimelinecontractorparentuuid)   | api\_php\_live\_v2 | Get a site's contractor timeline                 |
| GET    | [`/v1/app/comply/timeline/job/{systemTypeUuid}`](#get-v1appcomplytimelinejobsystemtypeuuid)         | api\_php\_live\_v2 | Get a system type's task timeline                |
| GET    | [`/v1/app/comply/timeline/system-type/{parentUuid}`](#get-v1appcomplytimelinesystem-typeparentuuid) | api\_php\_live\_v2 | Get a site's system type timeline                |
| GET    | [`/v1/app/comply/timeline/system/{systemTypeUuid}`](#get-v1appcomplytimelinesystemsystemtypeuuid)   | api\_php\_live\_v2 | Get a system type's system timeline              |
| GET    | [`/v1/app/frequencies`](#get-v1appfrequencies)                                                      | api\_php\_live\_v2 | List compliance frequencies                      |
| POST   | [`/v1/app/parents/comply-defaults`](#post-v1appparentscomply-defaults)                              | api\_php\_live\_v2 | Create a site's compliance defaults              |
| POST   | [`/v1/app/tasks/system-add`](#post-v1apptaskssystem-add)                                            | api\_php\_live\_v2 | Link a compliance system to a task               |
| POST   | [`/v1/app/tasks/system-remove`](#post-v1apptaskssystem-remove)                                      | api\_php\_live\_v2 | Unlink a compliance system from a task           |
| POST   | [`?action=read_parent_comply_data`](#post-actionread_parent_comply_data)                            | php-apis           | Read a site's compliance master data             |
| POST   | [`?action=save_job_comply_system`](#post-actionsave_job_comply_system)                              | php-apis           | Save a task's compliance systems                 |

Notes on the table:

* Rows marked "(no caller)" have no caller in the pinned clones. The web has service methods for `GET /v1/app/comply/document` (`ComplyDocService.getAllComplyDocs`) and for reading one system type (`ComplySystemTypeService.getComplySystemType`, which sends `GET /v1/app/comply/system-type?uuid=…`), but nothing calls them (web\_app\_v2 @ 0989b8e685, `src/app/services/comply/comply-doc/comply-doc.service.ts:43`, `src/app/services/comply/comply-system-type/comply-system-type.service.ts:36`).
* `GET /v1/app/comply/document` takes `subject` and `uuid`: a system type's documents for `system` (with a system type UUID), or a site's contractor documents for `contractor` (with a site UUID), grouped as `{ "folder", "files" }` by system or contractor name.
* `POST /v1/app/comply/contractor/sort` checks membership, not the admin role \[[ASK-112](https://github.com/snapfix/docs/blob/main/ASK.md#ask-112-which-comply-reads-should-members-who-are-not-admins-get)].
* The two php-apis rows were `ANY` in the stub: iOS and Android call both actions with `POST`.

## GET /v1/app/comply/contractor

Lists a site's contractors in sort order, each with its documents.

* **Auth:** user token; any member of the site in `parentUuid`, not only admins \[[ASK-112](https://github.com/snapfix/docs/blob/main/ASK.md#ask-112-which-comply-reads-should-members-who-are-not-admins-get)].
* **Used by:** web\_app\_v2 (`ComplyContractorService.getAllComplyContractors`, from the contractors page, the folders page and the contractor picker on a system's details tab).

**Request**

| Name         | In    | Type   | Required | Rules                                                                                                     |
| ------------ | ----- | ------ | -------- | --------------------------------------------------------------------------------------------------------- |
| `parentUuid` | query | string | yes      | The site. Missing: `422` "The parent uuid field is required."; a site the caller isn't a member of: `403` |

**Response** `200`: `data` is a list of [compliance item objects](#compliance-item-object) with `documents`, one per live contractor of the site.

```json
{
  "status": "success",
  "message": "Operation was successful",
  "data": [
    {
      "uuid": "contractor-123",
      "name": "Acme Plumbing",
      "parentUuid": "site-200",
      "email": "jane@example.com",
      "phoneCountryIso": null,
      "phoneCountryCode": null,
      "phoneNumber": null,
      "serviceType": "Plumbing",
      "contactName": "Jane Smith",
      "color": "amber",
      "note": null,
      "frequencyUuid": null,
      "frequencyDescription": "Annually",
      "expiryTs": 1795000000000,
      "expiryAlertDays": 30,
      "sortOrder": 1000,
      "createdBy": { "uuid": "user-301", "name": "Jane Smith", "image": null, "username": "jane@example.com" },
      "documents": []
    }
  ]
}
```

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

**Side effects:** none.

## POST /v1/app/comply/contractor

Creates a contractor in a site.

* **Auth:** user token; admin of the site in `parentUuid`.
* **Used by:** web\_app\_v2 (`ComplyContractorService.createComplyContractor`: a new row on the contractors page, which then opens the new contractor).

**Request** (JSON body)

| Name                   | In   | Type    | Required | Rules                                                   |
| ---------------------- | ---- | ------- | -------- | ------------------------------------------------------- |
| `parentUuid`           | body | string  | yes      | The site                                                |
| `name`                 | body | string  | yes      | Missing: "The name field is required."                  |
| `frequencyDescription` | body | string  | no       | The frequency name. Default `None`, which the web sends |
| `sortOrder`            | body | integer | no       | 0 or more. Stored as `sort_order`                       |

The web also passes a `frequencyUuid`, but the [frequency list](#get-v1appfrequencies) has no UUIDs, so the value is empty, and the request has no rule for it: nothing stores it.

**Response** `200`: the new [compliance item object](#compliance-item-object), read back from the database, without relations. It has no expiry, so `color` is `green`; `expiryAlertDays` is 30 and `createdBy` is the caller.

**Errors:** `403` "Access denied" when the caller isn't an admin of the site; `422` with the first failed rule.

**Side effects:** inserts a [`comply_Contractor`](https://docs.snapfix.com/engineering-reference/db/tables/comply_contractor.md) row with `expiryAlertDays` 30; an [activity line](#common-side-effects).

## POST /v1/app/comply/contractor/assign

Assigns a user to a contractor.

* **Auth:** user token; admin of the contractor's site. The user is not checked against the site: any existing user can be assigned.
* **Used by:** web\_app\_v2 (`ComplyContractorService.assignUser`, the "Users" dialog on the contractor page). The dialog picks from the site's users, [`GET /v1/app/parents/{uuid}/users`](https://docs.snapfix.com/engineering-reference/api/users.md).

**Request** (JSON body)

| Name             | In   | Type   | Required | Rules                                                                                                      |
| ---------------- | ---- | ------ | -------- | ---------------------------------------------------------------------------------------------------------- |
| `contractorUuid` | body | string | yes      | The contractor. Unknown or deleted: `404`                                                                  |
| `userUuid`       | body | string | yes      | An existing user (else `404`), not assigned to this contractor yet: `422` "User has been assigned already" |

**Response** `200`, with the message "User assigned successfully". `data.user` is the user's [user object](https://docs.snapfix.com/engineering-reference/api/tasks.md#user-object), with the mobile number, address and notes, also for a user of another site.

```json
{
  "status": "success",
  "message": "User assigned successfully",
  "data": { "user": { "uuid": "user-301", "username": "jane@example.com", "name": "Jane Smith", "userType": "User" } }
}
```

**Errors:** `403` "Access denied"; `404` "Resource not found" for an unknown contractor or user; `422` as above.

**Side effects:** restores the user's removed assignment, or inserts a [`comply_ContractorUserAssigned`](https://docs.snapfix.com/engineering-reference/db/tables/comply_contractoruserassigned.md) row; an [activity line](#common-side-effects).

## POST /v1/app/comply/contractor/link-asset

Links assets to a contractor.

* **Auth:** user token; admin of the contractor's site. The assets are not checked against the site, so an asset of another site can be linked and its details come back.
* **Used by:** web\_app\_v2 (`ComplyContractorService.linkAsset`, the asset picker on the contractor page).

**Request** (JSON body)

| Name             | In   | Type             | Required | Rules                                                                                      |
| ---------------- | ---- | ---------------- | -------- | ------------------------------------------------------------------------------------------ |
| `contractorUuid` | body | string           | yes      | The contractor                                                                             |
| `assetUuids`     | body | array of strings | yes      | Not empty. Assets that are already linked, and unknown UUIDs, are skipped without an error |

**Response** `200`: `data.assets` lists every asset now linked to the contractor, as [task objects](https://docs.snapfix.com/engineering-reference/api/tasks.md#task-object) with `status` and `assetRegister`.

```json
{
  "status": "success",
  "message": "Operation was successful",
  "data": { "assets": [{ "uuid": "asset-700", "title": "Boiler 1", "status": { "uuid": "status-1", "name": "green" }, "assetRegister": { "uuid": "register-10", "name": "Boilers", "image": null } }] }
}
```

**Errors:** `403` "Access denied"; `404` for an unknown contractor; `422` when `assetUuids` is missing, empty or not a list.

**Side effects:** inserts [`comply_ContractorAsset`](https://docs.snapfix.com/engineering-reference/db/tables/comply_contractorasset.md) rows, or restores removed ones; an [activity line](#common-side-effects).

## POST /v1/app/comply/contractor/unassign

Removes a user from a contractor.

* **Auth:** user token; admin of the contractor's site. The assignment is looked up before the admin check, so a caller who isn't an admin can tell whether a user is assigned.
* **Used by:** web\_app\_v2 (`ComplyContractorService.unassignUser`, the "Users" dialog on the contractor page).

**Request** (JSON body)

| Name             | In   | Type   | Required | Rules             |
| ---------------- | ---- | ------ | -------- | ----------------- |
| `contractorUuid` | body | string | yes      | The contractor    |
| `userUuid`       | body | string | yes      | The assigned user |

**Response** `200`, with the message "User unassigned successfully": `data.user` is the removed user's [user object](https://docs.snapfix.com/engineering-reference/api/tasks.md#user-object), as in [assign](#post-v1appcomplycontractorassign).

**Errors:** `400` "Job user relation does not exist" when there is no live assignment, which also covers an unknown contractor or user; then `403` "Access denied"; `404` only when the contractor or the user of a live assignment is deleted; `422` when a field is missing.

**Side effects:** soft-deletes the [`comply_ContractorUserAssigned`](https://docs.snapfix.com/engineering-reference/db/tables/comply_contractoruserassigned.md) row; an [activity line](#common-side-effects).

## POST /v1/app/comply/contractor/unlink-asset

Removes assets from a contractor.

* **Auth:** user token; admin of the contractor's site.
* **Used by:** web\_app\_v2 (`ComplyContractorService.unlinkAsset`, the asset picker on the contractor page).

**Request** (JSON body)

| Name             | In   | Type             | Required | Rules                           |
| ---------------- | ---- | ---------------- | -------- | ------------------------------- |
| `contractorUuid` | body | string           | yes      | The contractor                  |
| `assetUuids`     | body | array of strings | yes      | Not empty. The assets to unlink |

**Response** `200`: `data.assets` lists the assets still linked, as in [link-asset](#post-v1appcomplycontractorlink-asset).

**Errors:** `403` "Access denied"; `404` for an unknown contractor; `422` when `assetUuids` is missing or empty.

**Side effects:** soft-deletes the [`comply_ContractorAsset`](https://docs.snapfix.com/engineering-reference/db/tables/comply_contractorasset.md) rows of those assets; an [activity line](#common-side-effects).

## GET /v1/app/comply/contractor/{uuid}

Gets one contractor with its assets, assigned users and documents.

* **Auth:** user token; any member of the contractor's site \[[ASK-112](https://github.com/snapfix/docs/blob/main/ASK.md#ask-112-which-comply-reads-should-members-who-are-not-admins-get)].
* **Used by:** web\_app\_v2 (`ComplyContractorService.getComplyContractor`, the contractor page).

**Request**

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

**Response** `200`: a [compliance item object](#compliance-item-object) with `assets`, `assignedUsers` and `documents`.

**Errors:** `404` "Resource not found"; `403` "Access denied" when the caller isn't a member of the site.

**Side effects:** none.

## PUT /v1/app/comply/contractor/{uuid}

Changes one field of a contractor. The field is named by `action`.

* **Auth:** user token; admin of the contractor's site.
* **Used by:** web\_app\_v2 (`ComplyContractorService.updateComplyContractor`, the contractor page: the name, the status colour, the contact details, the service type, the expiry, the alert days, the frequency and the note).

**Request** (JSON body)

| Name     | In   | Type                | Required  | Rules                                                                                                                                       |
| -------- | ---- | ------------------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
| `uuid`   | path | string              | yes       | The contractor                                                                                                                              |
| `action` | body | string              | yes       | One of the actions below. Anything else: `422`                                                                                              |
| `value`  | body | depends on `action` | by action | See below. Leaving it out where the rule allows that (`name`, `note`, `email`, `contactName`, `serviceType`, `color`) fails with HTTP `500` |

| `action`                     | `value`                                                                                                                                         | Stored in                                                                                 |
| ---------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- |
| `name`                       | string or null                                                                                                                                  | `name`                                                                                    |
| `email`                      | an email address or null. The rule takes addresses without a top-level domain, such as `jane@example`                                           | `email`                                                                                   |
| `mobile`                     | required object: `countryCode` and `phoneNumber`, integers, each required with the other; `phoneCountryIso` optional, a code in `std_countries` | `phone_countrycode`, `phone_number`, and `phone_country_iso`, which is kept when not sent |
| `contactName`, `serviceType` | string or null                                                                                                                                  | `contact_name`, `service_type`                                                            |
| `expiryTs`                   | required integer, epoch ms                                                                                                                      | `expiryTs`                                                                                |
| `expiryAlertDays`            | required integer                                                                                                                                | `expiryAlertDays`                                                                         |
| `frequencyDescription`       | required string                                                                                                                                 | `frequencyDescription`                                                                    |
| `frequencyUuid`              | string or null                                                                                                                                  | nothing                                                                                   |
| `note`                       | string or null                                                                                                                                  | `note`                                                                                    |
| `color`                      | a string; no rule                                                                                                                               | nothing: the colour is always worked out from the expiry                                  |

**Response** `200`: the contractor as a [compliance item object](#compliance-item-object) with `assets` and `assignedUsers`.

**Errors:** `422` with the first failed rule; `403` "Access denied"; `404` "Resource not found"; `500` as above.

**Side effects:** updates the [`comply_Contractor`](https://docs.snapfix.com/engineering-reference/db/tables/comply_contractor.md) row; an "updated" [activity line](#common-side-effects), also for `color` and `frequencyUuid`, which change nothing.

## DELETE /v1/app/comply/contractor/{uuid}

Deletes a contractor.

* **Auth:** user token; admin of the contractor's site.
* **Used by:** web\_app\_v2 (`ComplyContractorService.deleteComplyContractor`, the contractor page's menu).

**Request**

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

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

**Errors:** `403` "Access denied"; `404` "Resource not found".

**Side effects:** soft-deletes the [`comply_Contractor`](https://docs.snapfix.com/engineering-reference/db/tables/comply_contractor.md) row. Its links to systems, users, assets and documents stay; an [activity line](#common-side-effects).

## POST /v1/app/comply/document

Uploads a document and files it under a system or a contractor.

* **Auth:** user token; admin of the site of the system or contractor. The document type is only checked to exist, so a document can be filed under another site's type.
* **Used by:** web\_app\_v2 (`ComplyDocService.createComplyDoc`, the upload dialog on the system page, the contractor page and the folders page).

**Request** (multipart form)

| Name          | In   | Type    | Required | Rules                                                                                                                                                          |
| ------------- | ---- | ------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `subject`     | body | string  | yes      | `system` or `contractor`                                                                                                                                       |
| `subjectUuid` | body | string  | yes      | The system or contractor. Unknown or deleted: `404`                                                                                                            |
| `typeUuid`    | body | string  | yes      | Any existing document type row, of any site, even a deleted one                                                                                                |
| `file`        | body | file    | yes      | `jpg`, `jpeg`, `png`, `gif`, `txt`, `doc`, `docx`, `xls`, `xlsx`, `zip`, `pdf`, `md`, `epub`, `csv`, `json` or `eml`. Up to `FILE_MAX_SIZE`, 100 MB by default |
| `expiryTs`    | body | integer | no       | Epoch ms. `0` or none means no expiry; the web sends `0` for "no expiry". A past date is accepted                                                              |

**Response** `200`: the new [document object](#document-object), with its type and subject.

```json
{
  "status": "success",
  "message": "Operation was successful",
  "data": {
    "uuid": "doc-501",
    "name": "QA_docs_insurance.pdf",
    "url": "https://bucket.example.com/doc/9f2c1a.pdf",
    "expiryTs": 1795000000000,
    "inactive": 0,
    "type": { "uuid": "doctype-201", "name": "Public Liability Insurance" },
    "attached_type": "contractor",
    "contractor": { "uuid": "contractor-123" }
  }
}
```

**Errors:** `403` "Access denied"; `404` for an unknown system or contractor; `422` for a missing or unknown type, a file of another type or over the size, or another `subject`.

**Side effects:**

* Stores the file under a random name in `img/` or `doc/` on the default disk ([files](https://docs.snapfix.com/engineering-reference/api.md#files)) and records its plain bucket URL, which is not signed \[[ASK-115](https://github.com/snapfix/docs/blob/main/ASK.md#ask-115-can-compliance-documents-report-files-and-the-comply-report-be-opened-from-their-link-without-signing-in)].
* Inserts a [`comply_Document`](https://docs.snapfix.com/engineering-reference/db/tables/comply_document.md) row and a [`comply_SystemDocument`](https://docs.snapfix.com/engineering-reference/db/tables/comply_systemdocument.md) or [`comply_ContractorDocument`](https://docs.snapfix.com/engineering-reference/db/tables/comply_contractordocument.md) link. `key_full_path_and_filename` records `{system type}/{system}/{file name}` for a system and `{contractor}/{file name}` for a contractor.
* The file name is cleaned: spaces become underscores, and characters other than letters, digits, `.`, `-` and `_` are dropped (`QA docs report.txt` becomes `QA_docs_report.txt`). A name the subject already has gets `-(1)`, `-(2)` and so on.
* No activity line.

## GET /v1/app/comply/document/type

Lists a site's document types. A site with none gets the default types first.

* **Auth:** user token; any member of the site \[[ASK-112](https://github.com/snapfix/docs/blob/main/ASK.md#ask-112-which-comply-reads-should-members-who-are-not-admins-get)].
* **Used by:** web\_app\_v2 (`ComplyDocTypeService.getAllComplyDocTypes`, the upload dialog, which sorts them by name).

**Request**

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

**Response** `200`: `data` is a list of [document type objects](#document-type-object), in no set order.

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

**Side effects:** when the site has no live document types, inserts the 15 defaults into [`comply_DocumentType`](https://docs.snapfix.com/engineering-reference/db/tables/comply_documenttype.md) before it answers: Certification, Contract, Elevator Inspection Certificate, Employers Liability Insurance, Fire Safety Certificate, Food & Beverage License, Food Safety Certificate, Health Inspection Certificate, Hotel Operating License, Method Statement, Permit to work, Policy, Public Liability Insurance, Risk Assessment and Waste Permit. The check and the inserts are not locked.

## POST /v1/app/comply/document/type

Creates a document type for a site.

* **Auth:** user token; admin of the site.
* **Used by:** web\_app\_v2 (`ComplyDocTypeService.createComplyDocType`, "Create new document type" in the upload dialog).

**Request** (JSON body)

| Name         | In   | Type   | Required | Rules                                                                                 |
| ------------ | ---- | ------ | -------- | ------------------------------------------------------------------------------------- |
| `parentUuid` | body | string | yes      | The site                                                                              |
| `name`       | body | string | yes      | Unique among the site's live document types: `422` "The name has already been taken." |

**Response** `200`: the new [document type object](#document-type-object).

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

**Side effects:** inserts a [`comply_DocumentType`](https://docs.snapfix.com/engineering-reference/db/tables/comply_documenttype.md) row. No activity line.

## PUT /v1/app/comply/document/{uuid}

Changes a document's type, expiry or inactive flag, or replaces its file.

* **Auth:** user token; admin of the site of the document's type.
* **Used by:** web\_app\_v2 (`ComplyDocService.updateComplyDoc`: "Edit Info" sends the type and the expiry; "Set As Inactive" sends `inactive` 1, and the folders page also sends `inactive` 0 to set a document active again). The web sends `POST` with `_method=PUT` in the query string and a form body, as [Requests](https://docs.snapfix.com/engineering-reference/api.md#requests) describes.

**Request** (form or JSON body; at least one of the four fields)

| Name       | In   | Type    | Required        | Rules                                                                                                                                                |
| ---------- | ---- | ------- | --------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
| `uuid`     | path | string  | yes             | The document                                                                                                                                         |
| `typeUuid` | body | string  | one of the four | A live document type of the same site as the document's current type. Another site's: `422` "The selected typeUuid is invalid."                      |
| `expiryTs` | body | integer | one of the four | Epoch ms; `0` for no expiry                                                                                                                          |
| `inactive` | body | integer | one of the four | `0` or `1`. Stored as `fInactive`                                                                                                                    |
| `file`     | body | file    | one of the four | `txt`, `doc`, `docx`, `xls`, `xlsx`, `zip`, `pdf`, `md`, `epub`, `csv`, `json` or `eml`, up to `FILE_MAX_SIZE`. Images are refused, unlike on create |

**Response** `200`: the changed [document object](#document-object).

**Errors:** `403` "Access denied"; `404` "Resource not found"; `422` when none of the four is sent or a rule fails; `400` "Unknown document owner" when a file is sent for a document with no system or contractor link.

**Side effects:** updates the [`comply_Document`](https://docs.snapfix.com/engineering-reference/db/tables/comply_document.md) row. A new file is stored as on [create](#post-v1appcomplydocument), named with `-(n)` when the subject has the name already, and replaces the URL and the recorded name; the old file stays in the bucket. No activity line.

## DELETE /v1/app/comply/document/{uuid}

Deletes a document.

* **Auth:** user token; admin of the site of the document's type.
* **Used by:** web\_app\_v2 (`ComplyDocService.deleteComplyDoc`, the document menu on the system, contractor and folders pages).

**Request**

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

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

**Errors:** `403` "Access denied"; `404` "Resource not found".

**Side effects:** soft-deletes the [`comply_Document`](https://docs.snapfix.com/engineering-reference/db/tables/comply_document.md) row. Its links to systems and contractors stay, and so does the file. No activity line.

## GET /v1/app/comply/overview/document/{parentUuid}

Lists a site's expired documents and the documents that expire within 30 days, for the dashboard.

* **Auth:** user token; admin of the site.
* **Used by:** web\_app\_v2 (`ComplyHttpService.getDocumentOverview`, the dashboard).

**Request**

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

**Response** `200`: `data.expired_documents` and `data.expiring_documents` (snake\_case, unlike the rest of the group), each a list of [document objects](#document-object), oldest expiry first.

```json
{
  "status": "success",
  "message": "Operation was successful",
  "data": {
    "expired_documents": [{ "uuid": "doc-501", "name": "fire_certificate.pdf", "expiryTs": 1700000000000, "inactive": 0 }],
    "expiring_documents": []
  }
}
```

* A document counts for the site of its document type. It must not be deleted or inactive, and it must be filed under a live system of a live system type, or under a live contractor.
* Expired: `expiryTs` is above 0 and before now.
* Expiring: `expiryTs` is from now to 30 days ahead. The window is fixed; systems and contractors use their own alert days \[[ASK-110](https://github.com/snapfix/docs/blob/main/ASK.md#ask-110-should-expiring-documents-use-a-fixed-30-day-window)].

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

**Side effects:** none.

## GET /v1/app/comply/overview/job/{parentUuid}

Lists a site's compliance tasks for the dashboard: overdue, due today, due soon, and medium or high priority.

* **Auth:** user token; admin of the site.
* **Used by:** web\_app\_v2 (`ComplyHttpService.getJobOverview`, the dashboard's "Compliance Tasks" card).

**Request**

| Name               | In     | Type   | Required | Rules                                                                                |
| ------------------ | ------ | ------ | -------- | ------------------------------------------------------------------------------------ |
| `parentUuid`       | path   | string | yes      | The site                                                                             |
| `device-tz-offset` | header | string | no       | The caller's offset, such as `GMT+0100`. Default `GMT+0000`. Sets the day boundaries |

**Response** `200`

```json
{
  "status": "success",
  "message": "Operation was successful",
  "data": {
    "overdueJobs": [{ "uuid": "task-300", "title": "Fire alarm test", "dueDateTs": 1794300000000, "status": { "uuid": "status-1", "name": "red" } }],
    "dueTodayJobs": [],
    "dueSoonJobs": [],
    "priorityJobs": { "medium": [], "high": [] }
  }
}
```

Each item is a task list item (`JobItemResource`): the [task object](https://docs.snapfix.com/engineering-reference/api/tasks.md#task-object) fields `uuid`, `title`, `largeTitle`, `description`, `image`, `enumType`, the priority, lock, archive, due date, time range and reference fields, `status`, `business`, `users` (`assigned`, `following`, `createdBy`, `modifiedBy`), `tags`, `rooms` and `areas`.

Which tasks count: tasks that aren't deleted, in a live group of the site, with a live link in [`tPri_JobComplySystem`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_jobcomplysystem.md). The linked system is not checked: a system of another site counts, and so does a deleted system.

* `overdueJobs`: a due date before now, and the task is not green, or it turned green after the due date.
* `dueTodayJobs`: due today in the caller's offset, and not green.
* `dueSoonJobs`: due from tomorrow to 30 days ahead, and not green.
* `priorityJobs`: `fPriority` 1 with priority level medium (10) or high (20). Green tasks are included.

The lists have no limit, and each task loads its users and tags with more queries. On the QA site on 2026-11-13 the call took about 90 to 108 seconds in two checks, once ending in `504`, and 58 seconds in a third.

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

**Side effects:** none.

## GET /v1/app/comply/overview/system-type/{parentUuid}

Lists a site's live system types in sort order, each with its systems and their compliance status, for the dashboard.

* **Auth:** user token; admin of the site.
* **Used by:** web\_app\_v2 (`ComplyHttpService.getSystemTypeOverview`, the dashboard).

**Request**

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

**Response** `200`: `data` is a list of `{ "uuid", "name", "sortOrder", "systems" }`, with each live system as a [system overview object](#system-overview-object) whose `color` is worked out as in the [compliance item object](#compliance-item-object).

```json
{
  "status": "success",
  "message": "Operation was successful",
  "data": [
    {
      "uuid": "type-201",
      "name": "Fire Safety",
      "sortOrder": 1000,
      "systems": [{ "uuid": "system-401", "name": "Fire doors & exits inspection", "expiryTs": 1795000000000, "expiryAlertDays": 30, "color": "amber", "note": null, "complianceStatus": "expiringCompliance" }]
    }
  ]
}
```

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

**Side effects:** none.

## GET /v1/app/comply/overview/system/{parentUuid}

Groups a site's systems by compliance status, for the dashboard.

* **Auth:** user token; admin of the site.
* **Used by:** web\_app\_v2 (`ComplyHttpService.getSystemOverview`, the dashboard).

**Request**

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

**Response** `200`: `data.inCompliance`, `data.expiringCompliance` and `data.outOfCompliance`, each a list of [system overview objects](#system-overview-object), from the live systems of the site's live system types. Here `color` is inverted: an expired system gets `green`, and a system in compliance, also one without an expiry, gets `red`; only `amber` is right.

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

**Side effects:** none.

## GET /v1/app/comply/system

Lists the systems of one system type in sort order, with their assets, assigned users, contractor and documents.

* **Auth:** user token; any member of the type's site \[[ASK-112](https://github.com/snapfix/docs/blob/main/ASK.md#ask-112-which-comply-reads-should-members-who-are-not-admins-get)].
* **Used by:** web\_app\_v2 (`ComplySystemService.getAllComplySystems`: each system type card on the systems page loads its own systems, one call per type; the folders page; and the system picker of the task page's and the planned task editor's compliance tabs).

**Request**

| Name             | In    | Type   | Required | Rules           |
| ---------------- | ----- | ------ | -------- | --------------- |
| `systemTypeUuid` | query | string | yes      | The system type |

**Response** `200`: `data` is a list of [compliance item objects](#compliance-item-object) with `assets`, `assignedUsers`, `contractor` and `documents`.

**Errors:** `404` "Resource not found" for an unknown or deleted type; `403` "Access denied"; `422` when `systemTypeUuid` is missing.

**Side effects:** none.

## POST /v1/app/comply/system

Creates a system in a system type.

* **Auth:** user token; admin of the type's site.
* **Used by:** web\_app\_v2 (`ComplySystemService.createComplySystem`, the new system row on a type card of the systems page, which then opens the new system).

**Request** (JSON body)

| Name                   | In   | Type    | Required | Rules                                      |
| ---------------------- | ---- | ------- | -------- | ------------------------------------------ |
| `systemTypeUuid`       | body | string  | yes      | The system type. Unknown or deleted: `404` |
| `name`                 | body | string  | yes      | Any text                                   |
| `frequencyDescription` | body | string  | no       | Default `None`, which the web sends        |
| `sortOrder`            | body | integer | no       | 0 or more. Stored as `sort_order`          |

As on [contractors](#post-v1appcomplycontractor), the web's `frequencyUuid` is not stored.

**Response** `200`: the new [compliance item object](#compliance-item-object) as saved, not read back: no relations, `expiryAlertDays` 30, `createdBy` the caller, and `color` `null`.

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

**Side effects:** inserts a [`comply_System`](https://docs.snapfix.com/engineering-reference/db/tables/comply_system.md) row with `expiryAlertDays` 30; an [activity line](#common-side-effects).

## GET /v1/app/comply/system-type

Lists a site's live system types in sort order.

* **Auth:** user token; any member of the site \[[ASK-112](https://github.com/snapfix/docs/blob/main/ASK.md#ask-112-which-comply-reads-should-members-who-are-not-admins-get)].
* **Used by:** web\_app\_v2 (`ComplySystemTypeService.getAllComplySystemTypes`: the systems page, and the system type picker on the folders page, the timeline, and the task page's and planned task editor's compliance tabs).

**Request**

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

**Response** `200`: `data` is a list of [system type objects](#system-type-object), without `systems`.

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

**Side effects:** none.

## POST /v1/app/comply/system-type

Creates a system type in a site.

* **Auth:** user token; admin of the site.
* **Used by:** web\_app\_v2 (`ComplySystemTypeService.createComplySystemType`, a new type on the systems page).

**Request** (JSON body)

| Name         | In   | Type    | Required | Rules                                                                               |
| ------------ | ---- | ------- | -------- | ----------------------------------------------------------------------------------- |
| `parentUuid` | body | string  | yes      | The site                                                                            |
| `name`       | body | string  | yes      | Unique among the site's live system types: `422` "The name has already been taken." |
| `sortOrder`  | body | integer | no       | 0 or more. Stored as `sort_order`                                                   |

**Response** `200`: the new [system type object](#system-type-object).

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

**Side effects:** inserts a [`comply_SystemType`](https://docs.snapfix.com/engineering-reference/db/tables/comply_systemtype.md) row. No activity line.

## POST /v1/app/comply/system-type/sort

Sets the order of a site's system types.

* **Auth:** user token; any member of the site. The admin role isn't checked, so a member can reorder the types \[[ASK-112](https://github.com/snapfix/docs/blob/main/ASK.md#ask-112-which-comply-reads-should-members-who-are-not-admins-get)].
* **Used by:** web\_app\_v2 (`ComplySystemTypeService.reorderComplySystemTypes`, drag and drop on the systems page).

**Request** (JSON body)

| Name          | In   | Type   | Required | Rules                                                                                                                    |
| ------------- | ---- | ------ | -------- | ------------------------------------------------------------------------------------------------------------------------ |
| `parentUuid`  | body | string | yes      | The site                                                                                                                 |
| `systemTypes` | body | array  | yes      | Not empty. Each item has `uuid` (string, required) and `sortOrder` (integer, required). Types of other sites are skipped |

**Response** `200`: `data` is every live system type of the site, as [system type objects](#system-type-object), in the new order.

**Errors:** `403` "Access denied" when the caller isn't a member, which includes an unknown site; `422` when `systemTypes` is missing or malformed.

**Side effects:** updates `sort_order` on the listed [`comply_SystemType`](https://docs.snapfix.com/engineering-reference/db/tables/comply_systemtype.md) rows. No activity line.

## PUT /v1/app/comply/system-type/{uuid}

Renames a system type.

* **Auth:** user token; admin of the type's site.
* **Used by:** web\_app\_v2 (`ComplySystemTypeService.updateComplySystemType`, renaming a type on the systems page).

**Request** (JSON body)

| Name   | In   | Type   | Required | Rules           |
| ------ | ---- | ------ | -------- | --------------- |
| `uuid` | path | string | yes      | The system type |
| `name` | body | string | yes      | The new name    |

**Response** `200`: the renamed [system type object](#system-type-object).

**Errors:** `400` "The system type already exists" when another live type of the site has the name; `403` "Access denied"; `404` "Resource not found"; `422` when `name` is missing.

**Side effects:** updates the [`comply_SystemType`](https://docs.snapfix.com/engineering-reference/db/tables/comply_systemtype.md) row. No activity line.

## DELETE /v1/app/comply/system-type/{uuid}

Deletes a system type.

* **Auth:** user token; admin of the type's site.
* **Used by:** web\_app\_v2 (`ComplySystemTypeService.deleteComplySystemType`, the menu of a type on the systems page).

**Request**

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

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

**Errors:** `403` "Access denied"; `404` "Resource not found".

**Side effects:** soft-deletes the [`comply_SystemType`](https://docs.snapfix.com/engineering-reference/db/tables/comply_systemtype.md) row only. Its systems, their documents and their task and contractor links stay, although the web's dialog says they are removed; the web has code that would delete the systems first, but nothing calls it. The systems can't be read afterwards: [the system list](#get-v1appcomplysystem) and [the system](#get-v1appcomplysystemuuid) answer `404`, because both look the type up. Their task links still count in the [task overview](#get-v1appcomplyoverviewjobparentuuid). No activity line.

## POST /v1/app/comply/system/assign

Assigns a user to a system.

* **Auth:** user token; admin of the system's site. The user is not checked against the site.
* **Used by:** web\_app\_v2 (`ComplySystemService.assignUser`, the "Users" dialog on the system's details tab).

**Request** (JSON body)

| Name         | In   | Type   | Required | Rules                                                                                                  |
| ------------ | ---- | ------ | -------- | ------------------------------------------------------------------------------------------------------ |
| `systemUuid` | body | string | yes      | The system. Unknown or deleted: `404`                                                                  |
| `userUuid`   | body | string | yes      | An existing user (else `404`), not assigned to this system yet: `422` "User has been assigned already" |

**Response** `200`, with the message "User assigned successfully": `data.user` is the user's [user object](https://docs.snapfix.com/engineering-reference/api/tasks.md#user-object), as in [the contractor's assign](#post-v1appcomplycontractorassign).

**Errors:** `403` "Access denied"; `404` for an unknown system or user; `422` as above.

**Side effects:** restores the user's removed assignment, or inserts a [`comply_SystemUserAssigned`](https://docs.snapfix.com/engineering-reference/db/tables/comply_systemuserassigned.md) row; an [activity line](#common-side-effects).

## POST /v1/app/comply/system/link-asset

Links assets to a system.

* **Auth:** user token; admin of the system's site. The assets are not checked against the site.
* **Used by:** web\_app\_v2 (`ComplySystemService.linkAsset`, the asset picker on the system's details tab).

**Request** (JSON body)

| Name         | In   | Type             | Required | Rules                                                                     |
| ------------ | ---- | ---------------- | -------- | ------------------------------------------------------------------------- |
| `systemUuid` | body | string           | yes      | The system                                                                |
| `assetUuids` | body | array of strings | yes      | Not empty. Assets that are already linked, and unknown UUIDs, are skipped |

**Response** `200`: `data.assets` lists every asset now linked to the system, as in [the contractor's link-asset](#post-v1appcomplycontractorlink-asset).

**Errors:** `403` "Access denied"; `404` for an unknown system; `422` when `assetUuids` is missing or empty.

**Side effects:** inserts [`comply_SystemAsset`](https://docs.snapfix.com/engineering-reference/db/tables/comply_systemasset.md) rows, or restores removed ones; an [activity line](#common-side-effects).

## POST /v1/app/comply/system/link-contractor

Sets the contractor of a system. A system has one contractor: the call removes the current link first.

* **Auth:** user token; admin of the system's site. The contractor must be in the same site.
* **Used by:** web\_app\_v2 (`ComplySystemService.linkContractor`, the contractor picker on the system's details tab).

**Request** (JSON body)

| Name             | In   | Type   | Required | Rules                         |
| ---------------- | ---- | ------ | -------- | ----------------------------- |
| `systemUuid`     | body | string | yes      | The system                    |
| `contractorUuid` | body | string | yes      | A contractor of the same site |

**Response** `200`: `data` is the contractor, as a [compliance item object](#compliance-item-object) without relations.

**Errors:** `403` "Access denied" when the caller isn't an admin, or the contractor is in another site; `404` for an unknown system or contractor; `422` when a field is missing.

**Side effects:** soft-deletes every [`comply_SystemContractor`](https://docs.snapfix.com/engineering-reference/db/tables/comply_systemcontractor.md) row of the system, then restores this contractor's latest removed link or inserts a new one. The old link is gone even when the call then fails with `403` or `404`. An [activity line](#common-side-effects).

## POST /v1/app/comply/system/sort

Sets the order of the systems in one system type.

* **Auth:** user token; admin of the type's site.
* **Used by:** web\_app\_v2 (`ComplySystemService.reorderComplySystems`, drag and drop of the systems on a type card).

**Request** (JSON body)

| Name             | In   | Type   | Required | Rules                                                                                                                      |
| ---------------- | ---- | ------ | -------- | -------------------------------------------------------------------------------------------------------------------------- |
| `systemTypeUuid` | body | string | yes      | The system type                                                                                                            |
| `systems`        | body | array  | yes      | Not empty. Each item has `uuid` (string, required) and `sortOrder` (integer, required). Systems of other types are skipped |

**Response** `200`: `data` is the type's live systems in the new order, as [compliance item objects](#compliance-item-object) without relations.

**Errors:** `403` "Access denied"; `404` for an unknown type; `422` when `systems` is missing or malformed.

**Side effects:** updates `sort_order` on the listed [`comply_System`](https://docs.snapfix.com/engineering-reference/db/tables/comply_system.md) rows. No activity line.

## POST /v1/app/comply/system/unassign

Removes a user from a system.

* **Auth:** user token; admin of the system's site. The assignment is looked up before the admin check.
* **Used by:** web\_app\_v2 (`ComplySystemService.unassignUser`, the "Users" dialog on the system's details tab).

**Request** (JSON body)

| Name         | In   | Type   | Required | Rules             |
| ------------ | ---- | ------ | -------- | ----------------- |
| `systemUuid` | body | string | yes      | The system        |
| `userUuid`   | body | string | yes      | The assigned user |

**Response** `200`, with the message "User unassigned successfully": `data.user` is the removed user's [user object](https://docs.snapfix.com/engineering-reference/api/tasks.md#user-object).

**Errors:** as [the contractor's unassign](#post-v1appcomplycontractorunassign): `400` "Job user relation does not exist" when there is no live assignment, also for an unknown system or user; then `403`; `404` only when the system or the user of a live assignment is deleted.

**Side effects:** soft-deletes the [`comply_SystemUserAssigned`](https://docs.snapfix.com/engineering-reference/db/tables/comply_systemuserassigned.md) row; an [activity line](#common-side-effects).

## POST /v1/app/comply/system/unlink-asset

Removes assets from a system.

* **Auth:** user token; admin of the system's site.
* **Used by:** web\_app\_v2 (`ComplySystemService.unlinkAsset`, the asset picker on the system's details tab).

**Request** (JSON body)

| Name         | In   | Type             | Required | Rules                           |
| ------------ | ---- | ---------------- | -------- | ------------------------------- |
| `systemUuid` | body | string           | yes      | The system                      |
| `assetUuids` | body | array of strings | yes      | Not empty. The assets to unlink |

**Response** `200`: `data.assets` lists the assets still linked.

**Errors:** `403` "Access denied"; `404` for an unknown system; `422` when `assetUuids` is missing or empty.

**Side effects:** soft-deletes the [`comply_SystemAsset`](https://docs.snapfix.com/engineering-reference/db/tables/comply_systemasset.md) rows of those assets; an [activity line](#common-side-effects).

## POST /v1/app/comply/system/unlink-contractor

Removes the contractor from a system.

* **Auth:** user token; admin of the system's site. The contractor must be in the same site.
* **Used by:** web\_app\_v2 (`ComplySystemService.unlinkContractor`, the system's details tab).

**Request** (JSON body)

| Name             | In   | Type   | Required | Rules                 |
| ---------------- | ---- | ------ | -------- | --------------------- |
| `systemUuid`     | body | string | yes      | The system            |
| `contractorUuid` | body | string | yes      | The linked contractor |

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

**Errors:** `403` "Access denied", also when the contractor is in another site; `404` for an unknown system or contractor, or a contractor that isn't linked to the system.

**Side effects:** soft-deletes the [`comply_SystemContractor`](https://docs.snapfix.com/engineering-reference/db/tables/comply_systemcontractor.md) row; an [activity line](#common-side-effects).

## GET /v1/app/comply/system/{uuid}

Gets one system with its assets, assigned users, contractor and documents.

* **Auth:** user token; any member of the system's site \[[ASK-112](https://github.com/snapfix/docs/blob/main/ASK.md#ask-112-which-comply-reads-should-members-who-are-not-admins-get)].
* **Used by:** web\_app\_v2 (`ComplySystemService.getComplySystem`: the system page, and the planned task editor's compliance tab).

**Request**

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

**Response** `200`: a [compliance item object](#compliance-item-object) with `assets`, `assignedUsers`, `contractor` and `documents`.

**Errors:** `404` "Resource not found" for an unknown system, or a system whose type is deleted; `403` "Access denied".

**Side effects:** none.

## PUT /v1/app/comply/system/{uuid}

Changes one field of a system. The field is named by `action`.

* **Auth:** user token; admin of the system's site.
* **Used by:** web\_app\_v2 (`ComplySystemService.updateComplySystem`: the system page's name, status colour, expiry, alert days, frequency and note, and renaming a system on its type card).

**Request** (JSON body)

| Name     | In   | Type                | Required  | Rules                                                                                                                                                                                                                                                |
| -------- | ---- | ------------------- | --------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `uuid`   | path | string              | yes       | The system                                                                                                                                                                                                                                           |
| `action` | body | string              | yes       | `name`, `expiryTs`, `expiryAlertDays`, `frequencyUuid`, `frequencyDescription`, `note` or `color`. Anything else: `422`                                                                                                                              |
| `value`  | body | depends on `action` | by action | `name`: a string, not null. `note`, `frequencyUuid`: string or null. `frequencyDescription`: required string. `expiryTs`, `expiryAlertDays`: required integers. `color`: no rule. Leaving it out for `name`, `note` or `color` fails with HTTP `500` |

`frequencyUuid` and `color` are accepted and not stored, as on [contractors](#put-v1appcomplycontractoruuid).

**Response** `200`: the system as a [compliance item object](#compliance-item-object) with `assets`, `assignedUsers` and `contractor`, without `documents`.

**Errors:** `422` with the first failed rule; `403` "Access denied"; `404` "Resource not found"; `500` as above.

**Side effects:** updates the [`comply_System`](https://docs.snapfix.com/engineering-reference/db/tables/comply_system.md) row; an "updated" [activity line](#common-side-effects).

## DELETE /v1/app/comply/system/{uuid}

Deletes a system.

* **Auth:** user token; admin of the system's site.
* **Used by:** web\_app\_v2 (`ComplySystemService.deleteComplySystem`, the system page's menu).

**Request**

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

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

**Errors:** `403` "Access denied"; `404` "Resource not found".

**Side effects:** soft-deletes the [`comply_System`](https://docs.snapfix.com/engineering-reference/db/tables/comply_system.md) row. Its document, user, asset and contractor links stay, and so do its task links in [`tPri_JobComplySystem`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_jobcomplysystem.md), which keep counting in the [task overview](#get-v1appcomplyoverviewjobparentuuid). The web's dialog says the system's related data is removed from its tasks and contractors. An [activity line](#common-side-effects).

## GET /v1/app/comply/system/{uuid}/activities

Lists the activity of one system, newest first.

* **Auth:** user token. Nothing is checked about the system or the caller, so any signed-in user can read the log of a system whose UUID they know.
* **Used by:** web\_app\_v2 (`ComplySystemService.getComplySystemActivity`, the system page's "Activity" tab).

**Request**

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

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

```json
{
  "status": "success",
  "message": "Operation was successful",
  "data": [
    {
      "uuid": "log-601",
      "text": "Compliance item <b>\"Fire doors & exits inspection\"</b> created",
      "type": "compliance_item_created",
      "createdTs": 1794387600000,
      "modifiedTs": 1794387600000,
      "user": { "uuid": "user-301", "name": "Jane Smith", "image": null, "username": "jane@example.com", "businessName": null }
    }
  ]
}
```

**Errors:** none of its own. An unknown UUID answers with an empty list.

**Side effects:** none.

## GET /v1/app/comply/timeline/contractor/{parentUuid}

Gets one [timeline item](#timeline-item-object) per live contractor of a site, in sort order.

* **Auth:** user token; any member of the site \[[ASK-112](https://github.com/snapfix/docs/blob/main/ASK.md#ask-112-which-comply-reads-should-members-who-are-not-admins-get)].
* **Used by:** web\_app\_v2 (`ComplyTimelineService.getComplyContractorTimeline`, the timeline's "Contractors" filter).

**Request**

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

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

```json
{
  "status": "success",
  "message": "Operation was successful",
  "data": [{ "uuid": "contractor-123", "name": "Acme Plumbing", "greenStart": "2026-11-10 00:00:00", "amberStart": "2026-11-18 00:00:00", "redStart": "2026-12-18 00:00:00", "sortOrder": 1000 }]
}
```

**Errors:** `403` "Access denied", which includes an unknown site.

**Side effects:** none.

## GET /v1/app/comply/timeline/job/{systemTypeUuid}

Lists the tasks linked to the systems of a type, for the timeline's "Tasks" filter. Planned tasks are grouped by title.

* **Auth:** user token; admin of the type's site \[[ASK-112](https://github.com/snapfix/docs/blob/main/ASK.md#ask-112-which-comply-reads-should-members-who-are-not-admins-get)].
* **Used by:** web\_app\_v2 (`ComplyTimelineService.getComplyJobTimeline`, after a system type is picked), always with `X-API-Version: 1.0.1`.

**Request**

| Name             | In     | Type   | Required | Rules                                                                                                                  |
| ---------------- | ------ | ------ | -------- | ---------------------------------------------------------------------------------------------------------------------- |
| `systemTypeUuid` | path   | string | yes      | The system type                                                                                                        |
| `X-API-Version`  | header | string | no       | `1.0.1` returns the status-log shape; other `1.0.x` versions return the plain shape. The group has `1.0` handlers only |

**Response** `200`: `data` lists the tasks with a live link to a live system of the type, in live groups and sites, oldest first. Planned tasks come first, grouped by title as `{ "name", "type": "planned", "jobs" }`; then one item per other task, with `name` (its title) and `type` `normal`.

* **Plain shape**, per task: `name`, `type`, `businessUuid`, `uuid`, `fImage` (`""` when none), and `redStart` (the task's `fJobTs`), `amberStart` (`fAmberTs`), `greenStart` (`fGreenTs`) and `dueDate` (`fDueDateTs`) as `YYYY-MM-DD HH:MM:SS`, or `null` when not set. These times are in the server's time zone (UTC), not the site's. A planned group's `jobs` hold the same items.
* **Status-log shape** (`1.0.1`), per normal task: `uuid`, `businessUuid`, `name`, `type`, `fImage`, `color`, `approvalRequired`, `approvalStatus`, `dueDate` (ISO 8601, `2026-11-20T09:00:00.000000Z`), and `statusLog`: the task's status changes, each `{ "status", "approvalStatus", "startTime" }`, starting with an added red entry at the task's red time when the first logged status isn't red. Planned groups lack the keys this shape reads, so a type with a linked planned task makes the call fail with HTTP `500`.

```json
{
  "status": "success",
  "message": "Operation was successful",
  "data": [{ "name": "Fire alarm test", "type": "normal", "businessUuid": "group-200", "uuid": "task-300", "fImage": "", "redStart": "2026-11-01 09:00:00", "amberStart": null, "greenStart": null, "dueDate": "2026-11-20 17:00:00" }]
}
```

**Errors:** `403` "Access denied"; `404` for an unknown type; `500` as above.

**Side effects:** none.

## GET /v1/app/comply/timeline/system-type/{parentUuid}

Gets one [timeline item](#timeline-item-object) per live system type of a site, in sort order.

* **Auth:** user token; any member of the site \[[ASK-112](https://github.com/snapfix/docs/blob/main/ASK.md#ask-112-which-comply-reads-should-members-who-are-not-admins-get)].
* **Used by:** web\_app\_v2 (`ComplyTimelineService.getAllComplySystemTypeTimelines`, the timeline's "System types" filter).

**Request**

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

**Response** `200`: `data` is a list of [timeline item objects](#timeline-item-object). A type's green start is the day it was created. Its amber and red starts are the earliest of its live systems'; amber is never before green, and red never before amber.

**Errors:** `403` "Access denied", which includes an unknown site.

**Side effects:** none.

## GET /v1/app/comply/timeline/system/{systemTypeUuid}

Gets one [timeline item](#timeline-item-object) per live system of a type, in sort order.

* **Auth:** user token; admin of the type's site \[[ASK-112](https://github.com/snapfix/docs/blob/main/ASK.md#ask-112-which-comply-reads-should-members-who-are-not-admins-get)].
* **Used by:** web\_app\_v2 (`ComplyTimelineService.getComplySystemTimeline`, the timeline's "Systems" filter, after a system type is picked).

**Request**

| Name             | In   | Type   | Required | Rules           |
| ---------------- | ---- | ------ | -------- | --------------- |
| `systemTypeUuid` | path | string | yes      | The system type |

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

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

**Side effects:** none.

## GET /v1/app/frequencies

Lists the frequencies a system or contractor can have.

* **Auth:** user token. No site is checked.
* **Used by:** web\_app\_v2 (`CommonService.getFrequencyList`, the frequency pickers on the system and contractor pages).

**Request:** no parameters.

**Response** `200`: `data` is a list of `{ "name": "..." }`, in this order: `None`, `Daily`, `Weekly`, `Fortnightly`, `Monthly`, `Quarterly`, `Semiannually`, `Annually`, `2 years`, `3 years`, `4 years` and `5 years`. There is no `uuid`. Systems and contractors keep the chosen name in `frequencyDescription`.

```json
{ "status": "success", "message": "Operation was successful", "data": [{ "name": "None" }, { "name": "Daily" }] }
```

**Errors:** none of its own.

**Side effects:** none.

## POST /v1/app/parents/comply-defaults

Creates the default system types and systems of sites that have no system types.

* **Auth:** user token. Each site needs the admin role. Sites where the caller isn't an admin, and sites that have system types, are skipped without an error.
* **Used by:** web\_app\_v2 (`ComplyHttpService.defaultSystems`: the dashboard and the systems page call it when the site has no system types, then load again; while the answer creates nothing, they ask again with no limit).

**Request** (JSON body)

| Name          | In   | Type             | Required | Rules                |
| ------------- | ---- | ---------------- | -------- | -------------------- |
| `parentUuids` | body | array of strings | yes      | Not empty. The sites |

**Response** `200`: `data` is `{ "parentUuid", "systemTypes" }` for a site that got defaults, with each new type as a [system type object](#system-type-object) with `systems`. When several sites get defaults, only the last one appears. When nothing was created, `data` is `[]`.

```json
{
  "status": "success",
  "message": "Operation was successful",
  "data": {
    "parentUuid": "site-200",
    "systemTypes": [
      { "uuid": "type-201", "name": "Company Certificates", "sortOrder": 1000, "systems": [{ "uuid": "system-401", "name": "Insurance Certificate", "frequencyDescription": "Annually", "expiryAlertDays": null, "color": "green" }] }
    ]
  }
}
```

The defaults are "Company Certificates", with three annual systems (Insurance Certificate, Annual Operating Licence, Fire Safety Certificate), and "Fire Safety", with ten systems, from monthly fire alarm testing to annual hydrant testing.

**Errors:** `422` when `parentUuids` is missing, empty or holds a non-string.

**Side effects:** inserts the [`comply_SystemType`](https://docs.snapfix.com/engineering-reference/db/tables/comply_systemtype.md) and [`comply_System`](https://docs.snapfix.com/engineering-reference/db/tables/comply_system.md) rows, with sort orders 1000, 2000 and so on. The systems get their `frequencyDescription` but no `expiryAlertDays`, unlike [new systems](#post-v1appcomplysystem), which get 30, so they never turn amber until someone sets one \[[ASK-140](https://github.com/snapfix/docs/blob/main/ASK.md#ask-140-should-the-default-compliance-systems-get-the-30-day-expiry-alert)]. The check and the inserts are not locked, so two first loads can create two sets. No activity line.

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

Links a compliance system to a task, replacing its current link. The task page's compliance tab saves with it. The [Tasks API](https://docs.snapfix.com/engineering-reference/api/tasks.md) has no row for it.

* **Auth:** user token; any member of the task's group, not only admins. The task must be [editable](https://docs.snapfix.com/engineering-reference/api/tasks.md#task-permissions).
* **Used by:** web\_app\_v2 (`TaskHttpService.createSystemTask`, the task page's compliance tab). The planned task editor's tab keeps its choice in the schedule instead.

**Request** (JSON body)

| Name          | In   | Type             | Required | Rules                                                                                                                                        |
| ------------- | ---- | ---------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
| `jobUuid`     | body | string           | yes      | The task. Unknown: `404`                                                                                                                     |
| `systemUuids` | body | array of strings | yes      | Not empty; repeats are dropped. Only the first system that belongs to the task's site is linked, and the rest aren't read. The web sends one |

**Response** `200`: `data.jobSystems` holds the new link (`uuid` is the system's UUID, `name`, and `date`, when it was linked, ISO 8601); `systems` the linked [compliance item objects](#compliance-item-object); `jobchats` the [chat item](https://docs.snapfix.com/engineering-reference/api/tasks.md#chat-item-object) added.

```json
{
  "status": "success",
  "message": "Operation was successful",
  "data": {
    "jobSystems": [{ "uuid": "system-401", "name": "Fire doors & exits inspection", "date": "2026-11-13T09:00:00.000000Z" }],
    "systems": [{ "uuid": "system-401", "name": "Fire doors & exits inspection", "color": "green" }],
    "jobchats": [{ "uuid": "chat-900", "text": "Added : Fire doors & exits inspection", "type": 82 }]
  }
}
```

**Errors:** `403` "Access denied" for a non-member; `400` "The task can not be updated"; `404` for an unknown task, or for an unknown system named before the first valid one.

**Side effects:** soft-deletes all of the task's links in [`tPri_JobComplySystem`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_jobcomplysystem.md) before it checks the systems, so a request that links nothing still removes the current link, and succeeds. Then inserts or restores one link, and adds an audit line "Added : {system}" (chat type 82), pushes, a touch of the task and viewed rows ([common side effects](https://docs.snapfix.com/engineering-reference/api/tasks.md#common-side-effects)).

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

Unlinks a compliance system from a task.

* **Auth:** user token; any member of the task's group, not only admins. The task must be [editable](https://docs.snapfix.com/engineering-reference/api/tasks.md#task-permissions).
* **Used by:** web\_app\_v2 (`TaskHttpService.deleteSystemTask`, the task page's compliance tab, when the system is removed or replaced by another).

**Request** (JSON body)

| Name         | In   | Type   | Required | Rules             |
| ------------ | ---- | ------ | -------- | ----------------- |
| `jobUuid`    | body | string | yes      | The task          |
| `systemUuid` | body | string | yes      | The linked system |

**Response** `200`: `data.jobchat` is the [chat item](https://docs.snapfix.com/engineering-reference/api/tasks.md#chat-item-object) added, "Removed : {system}" (chat type 83).

**Errors:** `404` when the task has no live link to the system (checked first), for an unknown task, or when the linked system is deleted; `403` "Access denied"; `400` "The task can not be updated".

**Side effects:** soft-deletes the [`tPri_JobComplySystem`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_jobcomplysystem.md) row, and adds an audit line, pushes, a touch of the task and viewed rows ([common side effects](https://docs.snapfix.com/engineering-reference/api/tasks.md#common-side-effects)).

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

Reads the compliance master data of some sites for the apps' local database: the system types, their systems, and the task links of those systems.

* **Auth:** user token (Bearer JWT, if `JWT_AUTH_ENABLED` is on \[[ASK-12](https://github.com/snapfix/docs/blob/main/ASK.md#ask-12-which-settings-do-the-production-api-servers-use)]). The action reads no user and checks no membership, so any signed-in user can read the compliance data of a site whose UUID they know.
* **Used by:** iOS (`APIManager.readParentComplyData`, in the background download of the sites' data after sign-in), Android (`LoginSubDataWork`, the last step of the sign-in data download, and `BusinessViewModel.callGetParentComplyData` after sites are added). Both send `POST`.

**Request** (JSON body)

| Name           | In   | Type             | Required | Rules                                                                                |
| -------------- | ---- | ---------------- | -------- | ------------------------------------------------------------------------------------ |
| `parent_uuids` | body | array of strings | yes      | The sites; repeats are dropped. Missing, not a list or empty: "invalid parent uuids" |
| `user_uuid`    | body | string           | no       | iOS sends it; the action ignores it                                                  |

**Response** `200`: `data` holds three lists of rows with every column as stored, none deleted: [`comply_SystemType`](https://docs.snapfix.com/engineering-reference/db/tables/comply_systemtype.md) (the sites' types), [`comply_System`](https://docs.snapfix.com/engineering-reference/db/tables/comply_system.md) (those types' systems) and [`tPri_JobComplySystem`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_jobcomplysystem.md) (the links to those systems, read through the write connection).

```json
{
  "result": true,
  "message": "SUCCESS",
  "data": {
    "comply_SystemType": [{ "uuid": "type-201", "uuid_tParent": "site-200", "name": "Fire Safety", "sort_order": 1000, "fDeleted": 0 }],
    "comply_System": [{ "uuid": "system-401", "uuid_SystemType": "type-201", "name": "Fire doors & exits inspection", "expiryTs": 1795000000000, "fDeleted": 0 }],
    "tPri_JobComplySystem": [{ "uuid": "link-901", "uuid_tJob": "task-300", "uuid_System": "system-401", "fDeleted": 0 }]
  },
  "serverTs": 1794387600000
}
```

When the sites have no live system types, the answer is `{"result": true, "message": "No data found"}` with no `data`.

**Errors:** `200` with `result: false`: "invalid parent uuids"; "Data cannot be blank!" for an empty body. Token errors as in [API conventions](https://docs.snapfix.com/engineering-reference/api.md#user-tokens).

**Side effects:** none.

## POST ?action=save\_job\_comply\_system

Saves the links between tasks and compliance systems that the apps made offline.

* **Auth:** user token (Bearer JWT, if `JWT_AUTH_ENABLED` is on \[[ASK-12](https://github.com/snapfix/docs/blob/main/ASK.md#ask-12-which-settings-do-the-production-api-servers-use)]). Each row is saved with no check on the task, its group or the caller, with the user fields the row carries. Only when the legacy queue is on does the action also need a user in the token ("invalid access!").
* **Used by:** iOS (`TaskManager.getJobComplySystem`, the sync step for pending links, up to 500 rows a call; iOS makes them when it copies a task that has a system), Android (`SyncRepository`, the `JOB_COMPLY_SYSTEM` sync task; Android makes them when a system is picked or changed on a task, and when a task is copied). Both send `POST`.

**Request** (JSON body)

| Name          | In   | Type             | Required | Rules                                                                                                                                                                                                                                                                                                         |
| ------------- | ---- | ---------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `insert_data` | body | array of objects | yes      | Rows of [`tPri_JobComplySystem`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_jobcomplysystem.md): `uuid`, `uuid_tJob`, `uuid_System`, `fDeleted`, `fCreatedTs`, `fModifiedTs`, `uuid_tUser_CreatedBy`, `uuid_tUser_ModifiedBy`. A row whose `uuid` exists is updated; any other is inserted |

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

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

**Errors:** `200` with `result: false`: "Data cannot be blank!" for an empty body; the counts with `result: false` when any row fails. With `?debug=1` on the URL, a failed row makes the action print the last database error instead of the answer.

**Side effects:** inserts or updates [`tPri_JobComplySystem`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_jobcomplysystem.md) rows through the generic save of the `save_pri_*` actions, which puts field names into the SQL. When the server setting `LEGACY_QUEUE_SUPPORT` is on \[[ASK-12](https://github.com/snapfix/docs/blob/main/ASK.md#ask-12-which-settings-do-the-production-api-servers-use)], the rows go to [`tPri_Queue`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_queue.md) and are written later, and the counts report every row as inserted.

## Compliance item object

A system or a contractor (`ContractorSystemResource`); both share this shape. Relations come only where the endpoint loads them.

| Field                                                                                       | Type            | Meaning                                                                                                                                                                                                                                                |
| ------------------------------------------------------------------------------------------- | --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `uuid`                                                                                      | string          | The system or contractor                                                                                                                                                                                                                               |
| `name`                                                                                      | string          | The name                                                                                                                                                                                                                                               |
| `parentUuid`                                                                                | string          | Contractors only: the site                                                                                                                                                                                                                             |
| `email`, `phoneCountryIso`, `phoneCountryCode`, `phoneNumber`, `serviceType`, `contactName` | string or null  | Contractors only: the contact details. The phone fields are stored as text, so they come back as strings although the update takes integers                                                                                                            |
| `color`                                                                                     | string          | `red` when the expiry has passed, `amber` from `expiryAlertDays` days before it, otherwise `green`, also without an expiry or alert days. Worked out on each read; the stored `color` column is not used. A system just created comes back with `null` |
| `note`                                                                                      | string or null  | The note                                                                                                                                                                                                                                               |
| `frequencyUuid`                                                                             | string or null  | The old frequency ID (`uuid_enumFrequency`), no longer used: nothing writes it, so new items have `null`, while older rows keep their ID. The web shows and changes only `frequencyDescription`                                                        |
| `frequencyDescription`                                                                      | string          | The frequency name, such as `None` or `Annually`                                                                                                                                                                                                       |
| `expiryTs`                                                                                  | integer or null | The expiry, epoch ms                                                                                                                                                                                                                                   |
| `expiryAlertDays`                                                                           | integer or null | Days before the expiry when the item turns amber. 30 when created through this API; `null` on the default systems                                                                                                                                      |
| `sortOrder`                                                                                 | integer or null | The position in its list                                                                                                                                                                                                                               |
| `createdBy`                                                                                 | object or null  | `uuid`, `name`, `image` and `username` of the creator                                                                                                                                                                                                  |
| `assets`                                                                                    | array           | When loaded: the linked assets (`LinkedAssetResource`), with the [task object](https://docs.snapfix.com/engineering-reference/api/tasks.md#task-object) fields, `jobAccess`, `status` and `assetRegister`                                              |
| `assignedUsers`                                                                             | array           | When loaded: the assigned users' [user objects](https://docs.snapfix.com/engineering-reference/api/tasks.md#user-object), with their mobile numbers, addresses and notes                                                                               |
| `documents`                                                                                 | array           | When loaded: the live [document objects](#document-object), inactive ones included                                                                                                                                                                     |
| `contractor`                                                                                | object or null  | Systems only, when loaded: the system's contractor, in this shape without relations                                                                                                                                                                    |

## System type object

| Field       | Type    | Meaning                                                                                    |
| ----------- | ------- | ------------------------------------------------------------------------------------------ |
| `uuid`      | string  | The system type                                                                            |
| `name`      | string  | The name, unique among the site's live types                                               |
| `sortOrder` | integer | The position in the list                                                                   |
| `systems`   | array   | Only in the defaults answer: the type's [compliance item objects](#compliance-item-object) |

## System overview object

A system in the two system overviews.

| Field              | Type            | Meaning                                                                                                                                                              |
| ------------------ | --------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `uuid`             | string          | The system                                                                                                                                                           |
| `name`             | string          | The name                                                                                                                                                             |
| `expiryTs`         | integer or null | The expiry, epoch ms                                                                                                                                                 |
| `expiryAlertDays`  | integer or null | The alert window in days                                                                                                                                             |
| `color`            | string          | As in the [compliance item object](#compliance-item-object) in the system type overview; inverted in the [system overview](#get-v1appcomplyoverviewsystemparentuuid) |
| `note`             | string or null  | The note                                                                                                                                                             |
| `complianceStatus` | string          | `outOfCompliance` once the expiry has passed, `expiringCompliance` within the alert days before it, otherwise `inCompliance`, also without an expiry                 |

## Document object

A document of a system or a contractor (`DocumentResource`). The server loads each document's type and subject with its own queries.

| Field                    | Type            | Meaning                                                                                                                                                                                                                 |
| ------------------------ | --------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `uuid`                   | string          | The document                                                                                                                                                                                                            |
| `name`                   | string          | The cleaned file name, the last part of `key_full_path_and_filename`                                                                                                                                                    |
| `url`                    | string          | The file's plain bucket URL, not signed \[[ASK-115](https://github.com/snapfix/docs/blob/main/ASK.md#ask-115-can-compliance-documents-report-files-and-the-comply-report-be-opened-from-their-link-without-signing-in)] |
| `expiryTs`               | integer or null | The expiry, epoch ms. `0` or `null` means none                                                                                                                                                                          |
| `inactive`               | integer         | `1` when set as inactive (`fInactive`). The system and contractor pages hide inactive documents; the folders page shows them                                                                                            |
| `type`                   | object          | The [document type object](#document-type-object), when the type exists                                                                                                                                                 |
| `attached_type`          | string or null  | `system` or `contractor`: the live system or contractor the document is filed under                                                                                                                                     |
| `system` or `contractor` | object          | Named by `attached_type`: the subject's `uuid`, and for a system its `systemType` with `uuid` and `name`                                                                                                                |

## Document type object

| Field  | Type   | Meaning                                      |
| ------ | ------ | -------------------------------------------- |
| `uuid` | string | The document type                            |
| `name` | string | The name, unique among the site's live types |

## Activity object

One entry of a system's activity log.

| Field                     | Type           | Meaning                                                                                                                                                                                                                        |
| ------------------------- | -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `uuid`                    | string         | The entry                                                                                                                                                                                                                      |
| `text`                    | string         | HTML text, such as `Compliance item <b>"Fire doors"</b> created` or `<b>Jane Smith</b> assigned to system <b>Fire doors</b>`. The update text ends with a stray quotation mark: `Compliance item <b>"Fire doors"</b> updated"` |
| `type`                    | string         | The activity code (`comply_Log.enum_comply_log`), such as `compliance_item_created`, `compliance_item_updated`, `compliance_item_user_assigned`, `compliance_item_asset_added` or `contractor_added`                           |
| `createdTs`, `modifiedTs` | integer        | Epoch ms                                                                                                                                                                                                                       |
| `user`                    | object or null | `uuid`, `name`, `image` and `username` of the person who acted, and `businessName`, which is always `null`: the log rows have no business name                                                                                 |

## Timeline item object

A system type, system or contractor on the timeline chart.

| Field        | Type           | Meaning                                                                                                                                   |
| ------------ | -------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
| `uuid`       | string         | The system type, system or contractor                                                                                                     |
| `name`       | string         | The name                                                                                                                                  |
| `greenStart` | string or null | The day it was created, `YYYY-MM-DD HH:MM:SS`                                                                                             |
| `amberStart` | string or null | The day its alert window opens: the expiry day minus `expiryAlertDays`, never before `greenStart`. `null` without an expiry or alert days |
| `redStart`   | string or null | The expiry day, never before `amberStart` or `greenStart`. `null` without an expiry                                                       |
| `sortOrder`  | integer        | The position in the list                                                                                                                  |

The expiry days are worked out in the site's time zone (`timezone_name`).

## Common side effects

What the sections above mean by these words.

* **Activity line:** after a change to a system or a contractor (create, update, delete, a user assigned or unassigned, assets added or removed, a contractor linked or unlinked), a queued job writes a visible row to [`comply_Log`](https://docs.snapfix.com/engineering-reference/db/tables/comply_log.md) and one to [`comply_SystemLog`](https://docs.snapfix.com/engineering-reference/db/tables/comply_systemlog.md) or [`comply_ContractorLog`](https://docs.snapfix.com/engineering-reference/db/tables/comply_contractorlog.md). System types, document types, documents, sorts and task links write none. Only systems have an endpoint that reads the log ([activities](#get-v1appcomplysystemuuidactivities)).
* **Soft delete:** a delete sets `fDeleted` on its row only. The rows that point at it (users, assets, contractor, documents, task links) and stored files stay.


---

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