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

# Compliance documents

{% 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/product/features/compliance-documents.md).
{% endhint %}

Site admins upload **compliance documents**, such as certificates or test reports, to a **compliance system** or a **contractor**. Each document has a **document type** from the site's own list, a file and an optional expiry date, and a system's or contractor's expiry date can be copied from one of its documents. The "Folders" tab keeps the documents in a folder per contractor and per system, and the [Comply](https://docs.snapfix.com/product/features/compliance/comply.md) dashboard counts the expired and expiring ones. A document can be set inactive: it then stays only in Folders. Web only.

## Rules

* A document belongs to one system or one contractor, never to a task. Uploading, changing and deleting need the site's admin role ([`POST /v1/app/comply/document`](https://docs.snapfix.com/engineering-reference/api/compliance.md#post-v1appcomplydocument)).
* Each site has its own document types, with names unique among its live types. A site with none gets 15 default types the first time the list is read, also when the upload dialog opens; two first reads at once can create two sets. An admin can add a type from the upload dialog ([`GET /v1/app/comply/document/type`](https://docs.snapfix.com/engineering-reference/api/compliance.md#get-v1appcomplydocumenttype)).
* An upload takes two steps: the type, the folder and the expiry date, then one file ([Upload a Compliance Document](https://docs.snapfix.com/how-the-apps-work/screens/compliance/folders.md#upload-a-compliance-document)).
* A file can be up to 100 MB. The server takes images (`jpg`, `jpeg`, `png`, `gif`) and documents (`txt`, `doc`, `docx`, `xls`, `xlsx`, `pdf`, `md`, `epub`, `csv`, `json`, `eml`), and also `zip`. The page drops a file that is too large or not in its own list without a message, and its list leaves out `.md` and `.eml` although the picker offers them.
* On upload, the server takes a document type of any site; on a change, the type must be of the same site.
* The stored file name has spaces turned into underscores and other characters dropped. A name the system or contractor already has gets `-(1)`, `-(2)` and so on.
* The expiry date is optional: "Document has no expiry date" leaves it empty. A document with no expiry date is never expired or expiring.
* "Edit Info" changes the type and the expiry date, never the file. The API can replace the file, but then refuses images ([`PUT /v1/app/comply/document/{uuid}`](https://docs.snapfix.com/engineering-reference/api/compliance.md#put-v1appcomplydocumentuuid)).
* "Set As Inactive" hides a document from its system's or contractor's card and from the dashboard; it stays in Folders, which is also the only place to set it active again ([Folders](https://docs.snapfix.com/how-the-apps-work/screens/compliance/folders.md#actions)).
* A system's or contractor's expiry date can be set to an active document's date in the Expiry Date dialog ([Expiry Date](https://docs.snapfix.com/how-the-apps-work/screens/compliance/system-detail.md#expiry-date)).
* Folders are fixed: one per contractor, and one per system of the chosen system type. They cannot be made or renamed. A folder's status is red when an active document has expired and green when all are valid ([Folders](https://docs.snapfix.com/how-the-apps-work/screens/compliance/folders.md#layout)).
* The dashboard counts a document as "Expired" when its expiry date has passed, and as "Expiring" when it falls within the next 30 days, a fixed window, while systems 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)]. Only active documents of live systems under live types, and of live contractors, count ([`GET /v1/app/comply/overview/document/{parentUuid}`](https://docs.snapfix.com/engineering-reference/api/compliance.md#get-v1appcomplyoverviewdocumentparentuuid)).
* Deleting a document marks it deleted. Its links stay, and the file stays in storage \[[ASK-111](https://github.com/snapfix/docs/blob/main/ASK.md#ask-111-should-a-deleted-documents-file-be-removed)] ([`DELETE /v1/app/comply/document/{uuid}`](https://docs.snapfix.com/engineering-reference/api/compliance.md#delete-v1appcomplydocumentuuid)).
* A file opens from a plain storage link, not a signed one; whether the link works without a sign-in is open \[[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)] ([document object](https://docs.snapfix.com/engineering-reference/api/compliance.md#document-object)).
* Documents write no line to the activity log ([common side effects](https://docs.snapfix.com/engineering-reference/api/compliance.md#common-side-effects)).
* Documents of a deleted system or contractor leave Folders and the dashboard.

## Flow

```mermaid
flowchart LR
    start["Folders, an Attachment card, or the Expiry Date dialog"] --> details["Type, folder and expiry date"]
    details --> file["Choose one file"]
    file --> saved["Document filed under its system or contractor"]
    saved --> card["Shown on the system or contractor"]
    saved --> folder["Listed in Folders"]
    saved --> copy["Copy its date to the system or contractor"]
    card --> inactive["Set As Inactive: Folders only"]
    saved --> dash["Dashboard: expired, or expiring within 30 days"]
    saved --> del["Delete: the row is marked deleted, the file stays"]
```

## Platforms

| Capability                                            | Web         | iOS | Android |
| ----------------------------------------------------- | ----------- | --- | ------- |
| Folders, upload, edit, set inactive or active, delete | Site admins | No  | No      |
| Open or download a file                               | Site admins | No  | No      |
| Dashboard "Expired" and "Expiring" boxes              | Site admins | No  | No      |

## Screens

* [Folders](https://docs.snapfix.com/how-the-apps-work/screens/compliance/folders.md): the folders, the document rows, the upload dialog and the delete dialog.
* [System detail](https://docs.snapfix.com/how-the-apps-work/screens/compliance/system-detail.md) and [Contractor detail](https://docs.snapfix.com/how-the-apps-work/screens/compliance/contractor-detail.md): the "Attachment" card and the Expiry Date dialog.
* [Dashboard](https://docs.snapfix.com/how-the-apps-work/screens/compliance/dashboard.md): the "Expired" and "Expiring" boxes.

## API and data

* [Compliance API](https://docs.snapfix.com/engineering-reference/api/compliance.md): [upload](https://docs.snapfix.com/engineering-reference/api/compliance.md#post-v1appcomplydocument), [change](https://docs.snapfix.com/engineering-reference/api/compliance.md#put-v1appcomplydocumentuuid) and [delete](https://docs.snapfix.com/engineering-reference/api/compliance.md#delete-v1appcomplydocumentuuid); document types, [list](https://docs.snapfix.com/engineering-reference/api/compliance.md#get-v1appcomplydocumenttype) and [create](https://docs.snapfix.com/engineering-reference/api/compliance.md#post-v1appcomplydocumenttype); the dashboard's [document overview](https://docs.snapfix.com/engineering-reference/api/compliance.md#get-v1appcomplyoverviewdocumentparentuuid). Folders read the documents that come with the [contractor list](https://docs.snapfix.com/engineering-reference/api/compliance.md#get-v1appcomplycontractor) and the [system list](https://docs.snapfix.com/engineering-reference/api/compliance.md#get-v1appcomplysystem).
* Tables: [`comply_Document`](https://docs.snapfix.com/engineering-reference/db/tables/comply_document.md), [`comply_DocumentType`](https://docs.snapfix.com/engineering-reference/db/tables/comply_documenttype.md), [`comply_SystemDocument`](https://docs.snapfix.com/engineering-reference/db/tables/comply_systemdocument.md) and [`comply_ContractorDocument`](https://docs.snapfix.com/engineering-reference/db/tables/comply_contractordocument.md).

## Depends on

* [Compliance systems](https://docs.snapfix.com/product/features/compliance/compliance-systems.md) and [Contractors](https://docs.snapfix.com/product/features/compliance/contractors.md): the owners of the documents, and the expiry dates a document can set.
* [Comply](https://docs.snapfix.com/product/features/compliance/comply.md): the dashboard boxes.

## Edge cases

* **Bad file:** too large, or of a type the page does not list: dropped with no message.
* **Empty new type name:** sent anyway, and the refusal shows as an error alert.
* **Deleted system or contractor:** its documents leave Folders and the dashboard.
* **Deleted document:** the file stays in storage \[[ASK-111](https://github.com/snapfix/docs/blob/main/ASK.md#ask-111-should-a-deleted-documents-file-be-removed)].
* **Last document deleted:** the folder keeps its last status.
* **Time zones:** expiry dates are epoch milliseconds, and "expired" compares them with the server's clock; `0` means no expiry.
* **Offline:** the web needs a connection; the apps have no documents.


---

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