Upload employee documents
Documents hang off a person's login, not their roster row, and live on the Documents tab of an employee record. An Admin or Manager picks a file, a document type and an optional expiry date; verifying it afterwards copies what the document says onto the roster's own compliance fields. Opening a file is a separate permission. Every upload, verification, archiving and opening is recorded in the audit trail.
What do I need before I start?
An Admin or Manager account. Uploading needs documents.upload, which is Admin and Manager. Verifying is documents.verify, also Admin and Manager, and archiving is documents.delete, again Admin and Manager. Seeing the list is documents.view.all, held by Admin and Manager. Control holds none of these by default, so for Control the tab has no list and no Upload, Verify or archive buttons, until an Admin grants them in Settings → Permissions. Opening a file is a separate permission again; see Who can open a document? below. An employee can always see and open their own documents.
A person with a login. Documents are keyed to the platform user account, not to the roster row, which is what lets internal staff who have no roster record hold documents too. The flip side is that a roster entry created without a linked user account has nowhere to put them: opening its Documents tab fails and raises a Failed to load documents message instead of that person's list.
At least one document type. The type dropdown is filled from the organisation-visible catalogue — the built-in system types plus any your organisation has added. If that list comes back empty, the Upload document button stays disabled and there is no way in.
Object storage, in production. The file itself goes to S3 before the metadata row is written. A production deployment with the storage bucket variables missing refuses the upload rather than writing to disk that will not survive a restart.
How do I upload one?
- Open the person from Employees and choose the Documents tab, labelled IDs, licences, contracts.
- Click Upload document. The dialog says JPG / PNG / WebP / PDF up to 25 MB. Verification happens after upload.
- Choose the File.
- Choose a Document type. The menu is grouped by category, and anything your organisation added itself is marked · custom.
- Set Expiry date (optional) if the document expires. This is the field that later drives expiry alerts, so a licence with no date here is a licence nothing will chase.
- If you picked SIA Licence, two extra boxes appear: SIA number and SIA type. Both are optional, and both are read later by the roster mirror.
- Add Notes (optional) if you want something recorded alongside it.
- Click Upload. The button stays disabled until both a file and a type are chosen. On success a Document uploaded toast appears and the list refreshes.

The document arrives unverified. Verification is a second, deliberate step.
What can I upload?
| Rule | Value |
|---|---|
| Formats | JPG, PNG, WebP, PDF |
| Maximum size | 25 MB |
| Content check | The first bytes of the file must match the type it claims to be |
| Filename | Anything outside letters, digits, dot, underscore and hyphen is replaced with _, and the name is cut to 120 characters |
Images and PDFs are both stored byte-for-byte. Nothing is resized or re-encoded, because the point of the file is that it is the exact document.
What does the list show?
Documents are grouped into sections by the category their type belongs to, in a fixed order: Identity, Right to Work, Address Verification, Licences, Employment History, Contracts & Handbook, References, Training & Certifications, then Other. A category the platform does not recognise is appended at the end rather than dropped.
Each row carries the filename, its size, a Verified or Pending badge, an expiry badge where an expiry date is set, and the upload date with the type label. On the right sit View, Verify and an archive button. View only appears for someone allowed to open the file, and Verify and the archive button only for an Admin or Manager.
The header line above the sections counts what is on file, and adds · N expiring soon when any document is inside 30 days of its expiry date or already past it.
Who can open a document?
Seeing that a document exists and opening the file are separate. Opening needs the permission documents.download.employee, shown in Settings → Permissions as Open employees' documents.
| Who | Sees the list | Opens the file |
|---|---|---|
| Admin, Manager | Yes | Yes — they hold documents.download.employee by default |
| Control | Yes | Only if an Admin grants them documents.download.employee |
| The employee themselves | Their own | Their own, always |
To let one Control user open files, an Admin opens Settings → Permissions, finds the person with Search users..., and presses Grant beside Open employees' documents. The row is then marked Override; Reset puts it back to the role default. The same screen can take the permission away from one Manager with Revoke. Only Admin, Manager and Control can ever hold it — the grant is refused for any other role.
View does not stream the file through the app. It records the opening in the audit trail first — under Employee document, with who opened it and when — and only then redirects the browser to a signed link that is valid for five minutes. If the opening cannot be recorded, the file is not released. A deployment with no object storage configured cannot open files at all.
An archived document cannot be opened, even by someone holding the permission and the old link.
What does verifying actually do?
It records who verified it and when — and then copies what the document says onto the roster record, so the older compliance fields stay correct without anyone typing them twice.
| Document type | Roster fields it fills |
|---|---|
| SIA Licence | Licence number and type from the two SIA boxes, expiry from the expiry date. This fills the employee's primary licence; any additional licences are kept on their HR tab |
| DBS Certificate | DBS check date — the recorded certificate date if there is one, otherwise the date you verified it |
| Visa, Work Permit | Right to work, but only if the document has not already expired |
| Passport, Driving Licence, Birth Certificate | Identity verified |
| Training Certificate | Training completed |
Every other type mirrors nothing. The platform also remembers which document filled each field, so un-verifying clears those fields again — but only when the document being un-verified is still the one on record. A newer document that has since taken over is left alone.
Pressing Unverify on a verified row reverses the whole thing. Editing the expiry date or the SIA details of an already-verified document re-copies the new values without changing which document is on record.
What happens when I archive one?
Archiving is a soft delete. The confirmation says so: Archive "…"? This hides the document but keeps it in the audit history. The row is stamped with who archived it and when, and it drops out of the list — the list only ever shows documents that have not been archived. The file itself is not deleted, but it can no longer be opened from the app.
Archiving also clears any roster field this document was the source for, so a compliance report cannot keep reading a licence number off a document nobody can see any more. Archiving needs documents.delete, not the upload or verify permission.
If it goes wrong
| What you see | What it means |
|---|---|
| Upload document is greyed out | Either you are viewing read-only, the tab is still loading, or the document-type catalogue came back empty. An empty catalogue is the common one, and it needs the type list seeded before anyone can upload. |
| Unsupported MIME type … | The file is not a JPG, PNG, WebP or PDF. |
| File exceeds 25MB limit | Split it or compress it; the cap is fixed. |
| File content doesn't match declared type (…) | The extension and the actual bytes disagree — usually a file renamed rather than converted. |
| Unknown document type for this organisation | The type was deactivated, or it belongs to another organisation. Pick another. |
| Upload failed with nothing else | The storage layer refused the file. In production that usually means object storage is not configured. |
| Verify returns a version conflict | Somebody else changed the same document while your page was open. Reload and try again. |
| Failed to load documents | The record you opened has no linked user account, so there is nowhere for documents to hang. |
| No View button on any row | You do not hold documents.download.employee. Ask an Admin to grant Open employees' documents to you. |
| Forbidden after following a document link from an email or another website | Opening is refused when the request comes from another site, so that a link elsewhere cannot record an opening in your name. Open it from the Documents tab instead. |
| Document not found from an old link | The document has been archived, or the link belongs to a different person's record. |
Related
Last updated 2026-11-17