> ## Documentation Index
> Fetch the complete documentation index at: https://docs.hitaji360.com/llms.txt
> Use this file to discover all available pages before exploring further.

# HR Documents

> HR documents are the files you keep against an employee — signed contracts, national IDs and passports, academic and professional certificates, CVs, and…

HR documents are the files you keep against an employee — signed contracts, national IDs and passports, academic and professional certificates, CVs, and anything else you need on record. Keeping them in Hitaji 360 rather than a shared drive means every file sits next to the person it belongs to, the right people (and only the right people) can see it, and the system can warn you before something like a work permit or a certification lapses.

This page covers what the documents area shows, how to upload and categorise a file, how expiry warnings work, and how to view, download or remove a document. The same documents also surface on each person's profile, under their **Documents** tab.

**You'll find this at:** `/hr/documents`

> 📷 *Screenshot: HR Documents list with the stat cards, the All / Contracts / IDs / Certificates / Expiring tabs, and the "Add Document" button — to be added.*

> Hitaji 360 is **multi-business**. HR documents follow the employee, and an employee belongs to whichever business their employment contract is under. Make sure the correct business is selected in the switcher before you upload or browse — see *Multi-business scoping* below for exactly how this is enforced.

***

## What you see on the page

At the top are four summary cards:

| Card                | What it counts                                                                                                     |
| ------------------- | ------------------------------------------------------------------------------------------------------------------ |
| **Total Documents** | All documents in the current view (or, when you filter by an employee, that person's documents).                   |
| **ID Documents**    | Documents of type **ID** in the current view.                                                                      |
| **Certificates**    | Documents of type **Certificate** in the current view.                                                             |
| **Expiring Soon**   | Documents expiring within the next 60 days, with a red **N expired** subtext when any are already past their date. |

Below the cards are five tabs:

* **All** — every document, newest grouping first, paged 20 at a time.
* **Contracts**, **IDs**, **Certificates** — the same list filtered to that single type.
* **Expiring** — a dedicated panel listing documents expiring within the next 60 days (or already expired), each with the employee's name and how many days are left. The tab carries a count badge.

You can also search by document title, number or employee name, and filter the main list to a single employee using the **All employees** picker in the toolbar.

***

## Document types

Every document is filed under exactly one **type**. The type drives the icon, the tab it appears under, and the summary counts.

| Type            | Use it for                                                |
| --------------- | --------------------------------------------------------- |
| **Contract**    | Employment contracts and signed agreements.               |
| **ID**          | National ID, passport, driving permit, work permit.       |
| **Certificate** | Academic and professional certificates, training records. |
| **CV**          | The employee's CV / résumé.                               |
| **Other**       | Anything that does not fit the above.                     |

These five values are fixed by the system (`CONTRACT`, `ID`, `CERTIFICATE`, `CV`, `OTHER`) — you cannot add your own type. The picker offers them as **Contract**, **ID Document**, **Certificate**, **CV/Resume** and **Other**.

***

## Adding a document

Choose **Add Document** (top right) to open the upload dialog. The button only appears if your role can create documents.

> 📷 *Screenshot: Add Document dialog showing the employee picker, type, title, number, expiry date and the drag-and-drop upload area — to be added.*

The dialog uploads the file first, then saves the document record once the upload succeeds.

### Fields

| Field               | Required | Notes                                                                                                                                                                                                              |
| ------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **Employee**        | Yes      | The person the document belongs to. (On the per-employee profile tab this is already fixed to that employee.)                                                                                                      |
| **Document Type**   | Yes      | One of the five types above.                                                                                                                                                                                       |
| **Document Title**  | No       | A friendly name, e.g. *Employment Contract 2026*. If you leave it blank the list simply shows the type. A title that is only spaces is treated as empty.                                                           |
| **Document Number** | No       | A reference number — contract no., ID no., certificate no. Up to 100 characters.                                                                                                                                   |
| **Issued**          | No       | The date the document was issued. (Available on the profile **Documents** tab upload form.)                                                                                                                        |
| **Expiry Date**     | No       | When the document lapses. Drives the expiry warnings. **Must be on or after the issued date** — the system rejects an expiry that predates issuance with *"Document expiry date cannot be before its issue date"*. |
| **Upload File**     | Yes      | One file. **PDF, DOC, DOCX, JPG or PNG, up to 10 MB.** Other file types and oversized files are refused before upload.                                                                                             |

Drag a file onto the drop zone or click to browse. You'll see an upload progress bar, then a green **Uploaded** tick. Only once the file has uploaded and you've chosen an employee and a type does **Add Document** become available.

> File storage is handled by the Hitaji ERP service (the same backend behind the rest of HR and accounting), not stored in the browser. The file is uploaded straight to secure storage and the document record just holds a reference to it.

***

## Expiry dates and warnings

If you set an **expiry date**, Hitaji 360 watches it for you so a lapsing ID or certificate doesn't slip past unnoticed.

* In the list, the **Expires** column shows a small badge: **Expired** (in red) once the date has passed, or **N days left** when it is within 30 days. Documents with more than 30 days remaining show no badge.
* The **Expiring Soon** stat card and the **Expiring** tab look 60 days ahead, so you get a longer runway than the per-row badge. The Expiring tab lists each document with the employee, the document name and the days remaining (or "Expired").
* On the employee profile **Documents** tab, each card highlights an expiring (≤ 30 days) or expired document in amber/red with a warning icon, and the tab header shows an **N expiring** badge.

> These are **on-screen indicators only** — opening the page or the profile tab is what surfaces them. There is no automated email or push reminder for an expiring HR document today; treat the Expiring tab as a list to review periodically. (Contrast this with overdue-invoice reminders in accounting, which do run a nightly digest.)

***

## Viewing, downloading and deleting

Each row (and each card on the profile tab) has three actions:

* **View** (eye icon) — opens the file in an in-app viewer without leaving the page. Clicking anywhere on a row in the main list also opens the viewer.
* **Download** (arrow icon) — saves the file to your device under its title or type/number.
* **Delete** (bin icon) — removes the document after a confirmation. The delete button only shows if your role can delete documents.

Deleting asks you to confirm and warns that it cannot be undone. Behind the scenes the document is **soft-deleted** (kept in the database but hidden), so it disappears from every list but isn't physically purged.

***

## On the employee profile

The same documents appear on each person's profile under the **Documents** tab, grouped by type with a count per group (e.g. *Contract · 2*). From there you can **Upload** a document for that one employee (the employee is pre-selected), view, download or delete, and the tab header flags how many of their documents are expiring. It is the natural place to manage one person's paperwork; the `/hr/documents` page is the place to see everything across the business at once.

See [The employee profile & its tabs](/hr/user/employees/employee-profile) for the rest of the profile.

***

## Multi-business scoping

HR documents don't carry a business of their own — their business is **inherited from the employee's employment contract(s)**. With a business selected in the switcher, the system fails closed:

* A document whose employee is **not** contracted with the selected business is treated as **not found** — it can't be read, edited or deleted from another business. This keeps one business's staff files invisible to another.
* An employee who has **no contract anywhere** (a freshly created record, not yet contracted) is tenant-shared, so their documents stay visible to whoever is setting them up.

The practical effect: if a document you expect to see is missing, first check you have the right business selected.

***

## Permissions

| Action                                        | Permission |
| --------------------------------------------- | ---------- |
| View / list / search documents, view expiring | `hr:read`  |
| Add a document, edit document details         | `hr:write` |
| Delete a document                             | `hr:admin` |

> ⚠️ **Current state:** The document **API** authorises on the coarse `hr:read` / `hr:write` / `hr:admin` slugs above, but the web page decides whether to show the **Add Document** and **Delete** buttons based on finer `hr-documents:create` / `hr-documents:delete` slugs. For most roles the two line up, but they are not the same gate — a role granted `hr-documents:create` without `hr:write` would see the Add button yet have the save rejected by the API (and vice versa, a role with `hr:write` but not `hr-documents:create` wouldn't see the button at all). This mismatch is flagged for the team to reconcile.

***

## Related

* [The employee profile & its tabs](/hr/user/employees/employee-profile) — the per-employee **Documents** tab
* [Employees (the people directory)](/hr/user/employees/employees) — find the person first
* [Employment records & contracts](/hr/user/employees/employment-and-contracts) — the contract that ties a document's employee to a business
* [Org chart](/hr/user/employees/org-chart) — the per-business reporting hierarchy
* [HR settings](/hr/user/settings/hr-settings) — HR module configuration