API Reference: HRM Module

This document details the RESTful API endpoints for the HRM module.

---

1. Authentication

All requests MUST include a Platform JWT in the Authorization header.

Authorization: Bearer <JWT>

The JWT is issued by the Shell and contains the user's identity, organization, and roles.

---

2. Employee API

GET /employees

List all employees in the current organization.

Query Parameters:

• q: Search by name or email.
• departmentId: Filter by department ID.
• status: Filter by employee_status.

Response (200 OK):

{
  "data": [
    {
      "id": "uuid",
      "jobTitle": "Engineer",
      "status": "active",
      ...
    }
  ]
}

GET /employees/:id

Fetch detailed profile for a specific employee.

POST /employees

Create a new employee record. Requires HR_ADMIN or ADMIN role.

PUT /employees/:id

Update employee details. Employees can update their own phone and emergency contacts. Managers/HR Admins can update job titles and departments.

GET /org-chart

Fetch the hierarchical reporting structure for the organization.

---

3. Leave Management API

GET /leave-requests

List leave requests. Defaults to the current user's requests unless the user is a Manager or HR Admin.

POST /leave-requests

Submit a new leave request.

Request Body:

{
  "leaveType": "annual",
  "startDate": "2024-12-01",
  "endDate": "2024-12-05",
  "note": "Family vacation"
}

POST /leave-requests/:id/approve

Approve a pending request. Requires the requester to be the employee's manager.

POST /leave-requests/:id/reject

Reject a pending request with a mandatory reason.

DELETE /leave-requests/:id

Cancel a pending request. Only allowed for the owner of the request.

---

4. Onboarding API

GET /onboarding/checklists/:employeeId

Fetch the active checklist for a specific employee.

POST /onboarding/checklists/:employeeId/items/:itemId/complete

Mark a checklist task as complete.

GET /onboarding/templates

List all onboarding templates available for the organization.

POST /onboarding/templates

Create a new onboarding template with a set of tasks.

---

5. Standard Error Codes

Status Code	Description
400 Bad Request	Invalid input or business logic violation (e.g., insufficient leave balance).
401 Unauthorized	Missing or invalid JWT.
403 Forbidden	Insufficient RBAC permissions to perform the action.
404 Not Found	Resource (Employee, Request, etc.) does not exist.
500 Server Error	Unexpected internal failure.