31 · Employees & org chart
The Employees module is the platform's record of who works for the organisation: contract details, compensation, who reports to whom. Each user gets their own self-service view of just their record; admins manage the full tree.
Where to find it
- Sidebar → HR → Employees (
/employees) — your own record. /employees/tree— admin-only org-chart editor.
Requires the people feature.
What's in a record
Each employee row has:
| Field | Who can read | Who can write |
|---|---|---|
| Name, email, phone, job title | everyone in the tree | admin |
| Employment type | everyone in the tree | admin |
| Department | everyone in the tree | admin |
| Manager (reports-to) | everyone in the tree | admin |
| Start / end date, contract ref | self + admin | admin |
| Salary, currency, pay frequency, hours/week | self only + admin | admin |
| Status (ACTIVE / ON_LEAVE / TERMINATED) | self + admin | admin |
| Self notes (emergency contact, address tweaks) | self + admin | self |
| Executive flag | everyone in the tree | admin |
⚠️ Compensation is the privacy boundary. Salary, currency, pay frequency and hours-per-week are stripped server-side from any row that isn't your own when a non-admin asks for the tree. Even a manager querying their team's tree never sees their reports' salaries.
Employment types
The dropdown supports six types:
- 🟢 Full-time — default. Permanent salaried staff.
- 🔵 Part-time — permanent, reduced hours.
- 🟦 Contract — fixed-term direct employee.
- 🟣 Contractor — external IR35-style subcontractor.
- 🟣 Vendor — supplier providing services.
- 🟡 Intern — temporary trainee.
Contractors and vendors fit into the same tree alongside permanent staff — useful when a programme manager needs to see all the people delivering a project regardless of contract status.
The tree
+-- 👑 Acme CEO (Executive)
| +-- Director — Operations
| | +-- Helpdesk Manager
| | | +-- Pat Support
| | | +-- Alex Agent
| | | +-- 🟣 Cabling Subbie (Contractor)
| | +-- RMM Lead
| +-- Director — Sales
| +-- AE — Mid-market
+-- 👑 Acme COO (Executive)
+-- Finance manager
+-- 🟣 External bookkeeper (Vendor)
📷 Screenshot placeholder: screenshots/employees-tree.png
The tree is built from managerId self-references. Roots are people
with managerId = null (typically CEO / Directors flagged as
Executive, which pins them to the top of the layer).
Building the tree
/employees/tree (admin only):
- + New employee — start with your CEO / executives. Tick Executive so they pin to the top.
- Click + Report on any row to add someone reporting to that person. The form pre-selects them as the manager.
- Edit to update compensation / contract / manager.
- ✕ to remove. Their reports become root-level until reassigned.
⚠️ Cycle protection. The API rejects attempts to set a descendant as a manager (would create a cycle). The error tells you which.
Linking to portal users
The form has a Linked user account field (paste a User UUID).
When set, the employee record:
- Shows up on
/employeesfor that user - Lets them edit their own self-notes
- Scopes what that user sees in
/api/employees/tree
Leave it blank for staff who don't have portal access (e.g.
contractors paid hourly without a login). The contractor / vendor
portal's requireVendor() check authorises purely on the JWT's
VENDOR role — it does not consult the employee linkage.
Self-service view
Open /employees:
- Your name, job title, employment type and department at the top
- A Reports to card showing your manager (if any)
- A Direct reports list if you have any
- Compensation card — only visible to you (and admins)
- A Your notes field you can edit
📷 Screenshot placeholder: screenshots/employees-self.png
If you don't have an HR record yet, the page shows a friendly "Ask your administrator to create one" hint and falls back to the basic profile data from your User account.
Permissions summary
| Endpoint | Who can call it |
|---|---|
GET /api/employees/me |
any authenticated user |
PATCH /api/employees/me |
self (only selfNotes) |
GET /api/employees/tree |
admin = full tree; others = subtree + peers, compensation stripped |
GET /api/employees |
admin only |
POST/PATCH/DELETE /api/employees/[id] |
admin only |
See also
- People — the existing HR module (departments, leave, payroll, reviews)
- Contractors / Vendors — vendor portal that uses the same tree linkages
- Users & access — login accounts that link to employee records