API Overview

The HRMS backend exposes a RESTful JSON API built with Laravel 12. All endpoints follow consistent conventions for authentication, response format, and error handling.

Interactive API Documentation

The HRMS uses Scramble to auto-generate interactive API documentation from the codebase.

Accessing Scramble Docs

When the backend is running locally:

• API Docs UI: http://localhost:8000/docs/api
• OpenAPI JSON: http://localhost:8000/docs/api.json

Scramble reads the route definitions, FormRequest validation rules, and API Resource transformations to generate up-to-date documentation automatically.

note

Scramble docs are only available in non-production environments by default. Check config/scramble.php for configuration.

Base URL

http://localhost:8000/api

All API endpoints are prefixed with /api.

Authentication

The API uses Laravel Sanctum with cookie-based session authentication.

Login Flow

# 1. Get CSRF token
GET /sanctum/csrf-cookie

# 2. Sign in
POST /api/login
Content-Type: application/json

{
  "email": "admin@kingrevolution.com",
  "password": "password"
}

# 3. Subsequent requests include session cookie automatically
GET /api/employees

Key Headers

Header	Value	When
Accept	application/json	Always
Content-Type	application/json	POST/PUT requests
X-XSRF-TOKEN	From XSRF-TOKEN cookie	All mutating requests
Referer	Frontend URL	All requests

See Authentication for full details.

Response Format

All API responses follow a consistent envelope format:

Success Response

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

Paginated Response

{
  "data": [ ... ],
  "links": {
    "first": "http://localhost:8000/api/employees?page=1",
    "last": "http://localhost:8000/api/employees?page=5",
    "prev": null,
    "next": "http://localhost:8000/api/employees?page=2"
  },
  "meta": {
    "current_page": 1,
    "from": 1,
    "last_page": 5,
    "per_page": 15,
    "to": 15,
    "total": 73
  }
}

Error Response

{
  "message": "The given data was invalid.",
  "errors": {
    "email": ["The email field is required."],
    "employee_number": ["The employee number has already been taken."]
  }
}

HTTP Status Codes

Code	Meaning
200	OK — Successful GET, PUT
201	Created — Successful POST
204	No Content — Successful DELETE
401	Unauthorized — Not logged in
403	Forbidden — Insufficient permissions
404	Not Found — Resource doesn't exist
422	Validation Error — Invalid request data
429	Too Many Requests — Rate limited
500	Server Error — Unexpected failure

Pagination

List endpoints support pagination via query parameters:

Parameter	Default	Description
page	1	Page number
per_page	15	Items per page (max 100)

GET /api/employees?page=2&per_page=25

Search & Filtering

Search

GET /api/employees?search=john

Searches across relevant text fields (name, email, employee number).

Filtering

GET /api/employees?entity_id=1&department_id=3&activity_status=active

Ordering

GET /api/employees?sort_by=last_name&sort_direction=asc

Endpoint Groups

Group	Base Path	Description
Authentication	/api/login, /api/logout, /api/user	Session management
Entities	/api/entities	Company/entity management
Departments	/api/departments	Department CRUD + manager/lead assignment
Employees	/api/employees	Employee CRUD, import, export, attachments
KPI Templates	/api/kpi-templates	Template CRUD + import
KPI Cycles	/api/kpi-cycles	Cycle CRUD + publish + export
KPI Evaluations	/api/kpi-evaluations	Evaluation workflow endpoints
Probation Reviews	/api/probation-reviews	Probation review workflow
Notifications	/api/notifications	User notifications
Notification Settings	/api/notification-settings	Admin notification config
Roles & Permissions	/api/roles, /api/permissions	RBAC management
Actionable Items	/api/actionable-items	User task queue
Dashboard	/api/dashboard	Summary statistics
Profile	/api/profile	Current user profile management

See Endpoint Reference for the complete endpoint listing.