Documents

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