Endpoints for managing documents within RoofLink. Documents are files uploaded and stored by employees, and can be associated with jobs and other entities for better organization. Documents support tagging, metadata updates, and optional e-signature workflows through templates.

Supported Document Operations

Querying Documents

List Documents: Retrieve a paginated list of documents with filtering options by job, tags, related entity, contract status, and more.
Retrieve Document: Get detailed information for a specific document, including its description, tags, download URL, and template management permissions.

Creating and Updating Documents

Upload Document: Upload a new document file and create a document record. The request must use multipart/form-data encoding. The document can be associated with a job and assigned tags at upload time.
Update Document: Perform a full update of a document's metadata (name, description, and tags). The stored file is not modified.
Partially Update Document: Update only the provided metadata fields, leaving unspecified fields unchanged.

Removing Documents

Delete Document: Soft-delete a document. The record is not permanently removed but is excluded from all list and retrieve responses. Only admin employees or employees with the can_delete_documents permission may perform this action.

Document Features

Tags and Categorization

Documents can be assigned one or more free-form tags (e.g., Signed Contract, Pre-Contracts). Tags drive several behaviours in the system:

The is_contract flag is set to true when a document carries the Signed Contract tag or is associated with a contract template
The list endpoint supports filtering by exact tag value using the tags query parameter
Tags are replaced in their entirety on each update — partial tag updates are not supported

Filtering and Search

The List Documents endpoint supports the following filters:

Job filter (job): Return only documents linked to a specific job
Tags filter (tags): Return documents whose tags array contains the specified value
Related entity filter (related_to): Return documents related to one or more entities, specified as a comma-separated list of ClassName{id} tokens (e.g., Job501,Crew7). Supported entity classes: Job, Customer, Payment, WorkOrder, MatOrder, Crew, Supplier
Contract filters (is_contract, is_pre_contract): Filter for contract or pre-contract documents
Search (search): Case-insensitive substring search on the document name field
Template filter (doc_template): Filter by associated template ID
Active filter (all): By default only active documents are returned; pass all=true to include inactive ones

E-Signature Support

Documents created from a template may support e-signature workflows. The list and mutation responses include signing metadata:

sign_meta: Contains the signing status for the customer and the employee representative, including whether each party can currently sign and the timestamp of their signature
signed_date: The date on which all required signers completed signing
version: Indicates the template version (v1 for legacy DocTemplate, v2 for LightDocTemplate)
can_manage_template: true only for admin users when the document uses a v2 template
template: The ID of the associated template

Soft-Delete Behavior

Deleting a document marks it with a deletion timestamp rather than removing it from the database. Soft-deleted documents:

Are excluded from all list responses, regardless of the all parameter
Return a 404 on retrieve and update attempts
Cannot be restored through the public API

Pagination

Document lists are paginated with:

Default page size: 25 items
Maximum page size: 25 items
Results are ordered by creation date descending (most recent first)
Responses include pagination metadata: count, from_index, to_index, next, previous, and next_page. See the responses page for details.

Related Operations

List Notes: View notes associated with jobs that documents are linked to