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

# Contractors

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

Site admins keep a record of each **contractor**, a company or person who works on the site's **compliance systems**, such as an electrical firm. A contractor has a name, a service type, a contact name, an email, a phone number, an expiry date with an expiry alert, a frequency and a note, plus assigned **users**, linked assets and **compliance documents**. Each compliance system can link one contractor, and the [Comply](https://docs.snapfix.com/product/features/compliance/comply.md) dashboard and timeline show contractors and their status. Contractors exist on the web only.

## Rules

* A contractor is made by typing its name in a new row on the Contractors tab; its page then opens. An empty name is not sent. Names need not be unique ([Contractors](https://docs.snapfix.com/how-the-apps-work/screens/compliance/contractors.md), [`POST /v1/app/comply/contractor`](https://docs.snapfix.com/engineering-reference/api/compliance.md#post-v1appcomplycontractor)).
* A new contractor starts with the frequency "None", an expiry alert of 30 days, no expiry date and a green status.
* The Contractors table lists every contractor A to Z, with its email, its first document, its expiry date and its status. There is no manual order, and the list is not paged ([Contractors](https://docs.snapfix.com/how-the-apps-work/screens/compliance/contractors.md#layout)).
* Each field saves on its own. Service type, contact name and email are sent on Enter and when the box loses focus. The phone number saves half a second after typing stops, and an empty or invalid number is not saved ([Contractor detail](https://docs.snapfix.com/how-the-apps-work/screens/compliance/contractor-detail.md#inputs)).
* An empty name is not saved on an existing contractor, and the name box stays open.
* The page checks no email format. The server refuses an address that fails its email rule, but takes one with no domain ending, such as "jane\@example".
* The expiry date, the expiry alert, the frequency and the note work as on [Compliance systems](https://docs.snapfix.com/product/features/compliance/compliance-systems.md#systems): the alert range and the note length are checked only in the browser, and the frequency is a label.
* The status follows the expiry date and the alert days, as for systems ([Status](https://docs.snapfix.com/product/features/compliance/compliance-systems.md#status)). The traffic light cannot be set by hand, and the colour the web sends is ignored.
* The "Users" dialog keeps one user \[[ASK-113](https://github.com/snapfix/docs/blob/main/ASK.md#ask-113-should-a-system-or-contractor-have-one-assigned-user-or-several)]. The server does not check that a user or an asset belongs to the site.
* A contractor is linked to systems from each system's page; a system has one contractor, and a contractor can serve several systems ([`POST /v1/app/comply/system/link-contractor`](https://docs.snapfix.com/engineering-reference/api/compliance.md#post-v1appcomplysystemlink-contractor)). The contractor's own page does not list its systems.
* Changes to a contractor are logged ([common side effects](https://docs.snapfix.com/engineering-reference/api/compliance.md#common-side-effects)), but no screen shows a contractor's log.
* Deleting a contractor marks it deleted; its links to systems, users, assets and documents stay. The dialog says its "documents will remain available in Folders", but Folders lists only live contractors, so its documents disappear. The dialog has a grammar slip ([Delete Contractor](https://docs.snapfix.com/how-the-apps-work/screens/compliance/contractor-detail.md#delete-contractor)).
* Any member of the site can read the contractor list and a contractor through the API, although the pages are for admins \[[ASK-112](https://github.com/snapfix/docs/blob/main/ASK.md#ask-112-which-comply-reads-should-members-who-are-not-admins-get)].

## Flow

```mermaid
flowchart LR
    tab["Contractors tab"] --> add["Type a name in a new row"]
    add --> detail["Contractor page"]
    tab --> detail
    detail --> info["Service type, contact, expiry, alert, frequency, note"]
    detail --> people["Users and assets"]
    detail --> docs["Documents"]
    system["System page"] --> link["Link one contractor"]
    detail --> del["Delete: documents leave Folders"]
```

## Platforms

| Capability                                  | Web         | iOS | Android |
| ------------------------------------------- | ----------- | --- | ------- |
| List, create, edit and delete contractors   | Site admins | No  | No      |
| Users, assets and documents of a contractor | Site admins | No  | No      |

## Screens

* [Contractors](https://docs.snapfix.com/how-the-apps-work/screens/compliance/contractors.md): the table, with search and the "+" for a new contractor.
* [Contractor detail](https://docs.snapfix.com/how-the-apps-work/screens/compliance/contractor-detail.md): one contractor.
* [Folders](https://docs.snapfix.com/how-the-apps-work/screens/compliance/folders.md): the contractors' document folders.

## API and data

* [Compliance API](https://docs.snapfix.com/engineering-reference/api/compliance.md): [list](https://docs.snapfix.com/engineering-reference/api/compliance.md#get-v1appcomplycontractor), [create](https://docs.snapfix.com/engineering-reference/api/compliance.md#post-v1appcomplycontractor), [get](https://docs.snapfix.com/engineering-reference/api/compliance.md#get-v1appcomplycontractoruuid), [change one field](https://docs.snapfix.com/engineering-reference/api/compliance.md#put-v1appcomplycontractoruuid) and [delete](https://docs.snapfix.com/engineering-reference/api/compliance.md#delete-v1appcomplycontractoruuid); [assign](https://docs.snapfix.com/engineering-reference/api/compliance.md#post-v1appcomplycontractorassign) and [unassign](https://docs.snapfix.com/engineering-reference/api/compliance.md#post-v1appcomplycontractorunassign) users; [link](https://docs.snapfix.com/engineering-reference/api/compliance.md#post-v1appcomplycontractorlink-asset) and [unlink](https://docs.snapfix.com/engineering-reference/api/compliance.md#post-v1appcomplycontractorunlink-asset) assets. Documents use the endpoints in [Compliance documents](https://docs.snapfix.com/product/features/compliance/compliance-documents.md#api-and-data).
* Tables: [`comply_Contractor`](https://docs.snapfix.com/engineering-reference/db/tables/comply_contractor.md), [`comply_ContractorUserAssigned`](https://docs.snapfix.com/engineering-reference/db/tables/comply_contractoruserassigned.md), [`comply_ContractorAsset`](https://docs.snapfix.com/engineering-reference/db/tables/comply_contractorasset.md), [`comply_ContractorDocument`](https://docs.snapfix.com/engineering-reference/db/tables/comply_contractordocument.md), [`comply_SystemContractor`](https://docs.snapfix.com/engineering-reference/db/tables/comply_systemcontractor.md), [`comply_ContractorLog`](https://docs.snapfix.com/engineering-reference/db/tables/comply_contractorlog.md) and [`comply_Log`](https://docs.snapfix.com/engineering-reference/db/tables/comply_log.md).

## Depends on

* [Compliance systems](https://docs.snapfix.com/product/features/compliance/compliance-systems.md): the systems that link a contractor, and the status rules.
* [Compliance documents](https://docs.snapfix.com/product/features/compliance/compliance-documents.md): the contractor's documents and folder.
* [Comply](https://docs.snapfix.com/product/features/compliance/comply.md): the dashboard and timeline.
* [Asset registers](https://docs.snapfix.com/product/features/assets/asset-registers.md): the assets a contractor links to.
* [Site users](https://docs.snapfix.com/product/features/console/site-users.md): the users assigned to a contractor.

## Edge cases

* **Deleted contractor:** its documents leave Folders and the dashboard, and the systems linked to it stop showing it.
* **Empty table:** only the header row shows, with no text.
* **The row's "⋮" button:** it opens the contractor's page, like a click on the row, not a menu.
* **Failed list:** the Comply tabs stay disabled until the page reloads.
* **Several sites:** a contractor belongs to one site; the pages show the current site.
* **Offline:** the web needs a connection; the apps have no contractors.


---

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