API Conventions

All HRMS API endpoints follow consistent conventions for responses, errors, pagination, and search.

Response Envelope

Success Response

{
  "data": { },
  "message": "Operation successful",
  "meta": { }
}

• data — The requested resource or collection.
• message — Human-readable success message.
• meta — Optional metadata (pagination info, counts, etc.).

Validation Error (422)

{
  "message": "The given data was invalid.",
  "errors": {
    "field_name": ["Error message 1", "Error message 2"]
  }
}

Error Response

{
  "message": "Error description"
}

HTTP Status Codes

Code	Meaning	When Used
200	Success	Successful read, update, or action
201	Created	Resource successfully created
204	No Content	CSRF cookie response
401	Unauthenticated	No valid session
403	Forbidden	User lacks required permission
404	Not Found	Resource does not exist
422	Validation Error	Invalid input or business rule violation

Pagination

Most list endpoints support opt-in pagination:

Parameter	Type	Default	Description
paginate	boolean	false	Enable pagination
per_page	integer	15	Items per page (max: 100)
page	integer	1	Page number

When pagination is enabled, the response includes meta:

{
  "data": [...],
  "meta": {
    "current_page": 1,
    "last_page": 5,
    "per_page": 15,
    "total": 73
  }
}

note

Endpoints remain backward-compatible — without paginate=true, they return all records. The UI sends paginate=true by default.

Search

All list endpoints support text search via the q parameter:

GET /api/employees?q=sarah

Search is case-insensitive (uses PostgreSQL ILIKE) and matches partial strings. The searchable fields vary by endpoint:

Endpoint	Searchable Fields
Entities	Name
Departments	Department name, entity name
Employees	First name, last name, email, employee number, display name
KPI Templates	Template name, designation
KPI Cycles	Cycle name
Roles	Role name

Ordering

All list endpoints default to latest-first ordering:

ORDER BY updated_at DESC, id DESC

Recently created or updated records appear at the top.

Filtering

Endpoints support module-specific filter parameters:

Endpoint	Available Filters
Departments	entity_id
Employees	entity_id, department_id, status, employment_lifecycle
KPI Templates	entity_id, department_id, status
KPI Cycles	status
KPI Evaluations	scope, status, kpi_cycle_id, entity_id, department_id
Probation Evaluations	status, manager_id
Actionable Items	status (pending/completed/all)

File Downloads

Protected file downloads (employee attachments, KPI evidence, probation signatures) require an authenticated session. They are not public URLs.

The frontend uses an authenticated fetch → blob → download flow. Direct browser navigation to the URL works only when the user has an active session cookie.