HR & People API

Employee lifecycle management, leave tracking, attendance, shifts, holidays, reimbursements, and organizational structure.

All endpoints prefixed with /api/v1/hr

Employees

Core employee records with probation management and self-service.

POST /api/v1/hr/employees

Create a new employee record.

Auth: Bearer token · hr.create

Request Body
json 
{
  "firstName": "Jane",
  "lastName": "Smith",
  "email": "jane@company.com",
  "departmentId": 1,
  "designationId": 2,
  "dateOfJoining": "2026-01-15",
  "employmentType": "full_time"
}
GET /api/v1/hr/employees

List employees with pagination, filtering, and role-based visibility.

Auth: Bearer token · hr.view

Query Parameters
Parameter Type Description
page number Page number
limit number Items per page
search string Search by name or email
departmentId number Filter by department
status string Filter by status
GET /api/v1/hr/employees/stats

Get employee statistics (total, by department, by status).

Auth: Bearer token · hr.view

GET /api/v1/hr/employees/probation-ending-soon

Get employees whose probation ends within N days.

Auth: Bearer token · hr.view

GET /api/v1/hr/employees/me

Get the current user's own employee record.

Auth: Bearer token

PUT /api/v1/hr/employees/me

Self-service: update own personal information (restricted fields).

Auth: Bearer token

GET /api/v1/hr/employees/:id

Get employee by ID.

Auth: Bearer token · hr.view

PUT /api/v1/hr/employees/:id

Update an employee record.

Auth: Bearer token · hr.edit

GET /api/v1/hr/employees/:id/assignment-history

Get full assignment history for an employee.

Auth: Bearer token · hr.view

GET /api/v1/hr/employees/:id/assignment

Get assignment as-of a specific date.

Auth: Bearer token · hr.view

GET /api/v1/hr/employees/:id/direct-reports

Get direct reports for a manager.

Auth: Bearer token · hr.view

POST /api/v1/hr/employees/:id/confirm-probation

Confirm an employee's probation (promote to active).

Auth: Bearer token · hr.manage

POST /api/v1/hr/employees/:id/extend-probation

Extend an employee's probation period.

Auth: Bearer token · hr.manage

Emergency Contacts

Employee emergency contact sub-resources.

GET /api/v1/hr/employees/:employeeId/emergency-contacts

Get all emergency contacts for an employee.

Auth: Bearer token · hr.view

POST /api/v1/hr/employees/:employeeId/emergency-contacts

Create a new emergency contact.

Auth: Bearer token · hr.edit

PUT /api/v1/hr/employees/:employeeId/emergency-contacts/:contactId

Update an emergency contact.

Auth: Bearer token · hr.edit

DELETE /api/v1/hr/employees/:employeeId/emergency-contacts/:contactId

Delete an emergency contact.

Auth: Bearer token · hr.edit

Documents

Employee document management with verification workflow.

GET /api/v1/hr/employees/:employeeId/documents

List documents for an employee with optional filters.

Auth: Bearer token · hr.view

POST /api/v1/hr/employees/:employeeId/documents

Upload/create a new document for an employee.

Auth: Bearer token · hr.edit

PUT /api/v1/hr/employees/:employeeId/documents/:docId

Update a document.

Auth: Bearer token · hr.edit

DELETE /api/v1/hr/employees/:employeeId/documents/:docId

Delete a document.

Auth: Bearer token · hr.edit

POST /api/v1/hr/employees/:employeeId/documents/:docId/verify

Verify/approve a document.

Auth: Bearer token · hr.manage

Dependents

Employee dependent records.

GET /api/v1/hr/employees/:employeeId/dependents

Get all dependents for an employee.

Auth: Bearer token · hr.view

POST /api/v1/hr/employees/:employeeId/dependents

Create a new dependent.

Auth: Bearer token · hr.edit

PUT /api/v1/hr/employees/:employeeId/dependents/:dependentId

Update a dependent.

Auth: Bearer token · hr.edit

DELETE /api/v1/hr/employees/:employeeId/dependents/:dependentId

Delete a dependent.

Auth: Bearer token · hr.edit

Education

Employee education history.

GET /api/v1/hr/employees/:employeeId/education

Get all education records.

Auth: Bearer token · hr.view

POST /api/v1/hr/employees/:employeeId/education

Create a new education record.

Auth: Bearer token · hr.edit

PUT /api/v1/hr/employees/:employeeId/education/:educationId

Update an education record.

Auth: Bearer token · hr.edit

DELETE /api/v1/hr/employees/:employeeId/education/:educationId

Delete an education record.

Auth: Bearer token · hr.edit

Certifications

Employee certifications and professional credentials.

GET /api/v1/hr/employees/:employeeId/certifications

Get all certifications.

Auth: Bearer token · hr.view

POST /api/v1/hr/employees/:employeeId/certifications

Create a new certification.

Auth: Bearer token · hr.edit

PUT /api/v1/hr/employees/:employeeId/certifications/:certificationId

Update a certification.

Auth: Bearer token · hr.edit

DELETE /api/v1/hr/employees/:employeeId/certifications/:certificationId

Delete a certification.

Auth: Bearer token · hr.edit

Experience

Employee work experience history.

GET /api/v1/hr/employees/:employeeId/experience

Get all work experience records.

Auth: Bearer token · hr.view

POST /api/v1/hr/employees/:employeeId/experience

Create a new experience record.

Auth: Bearer token · hr.edit

PUT /api/v1/hr/employees/:employeeId/experience/:experienceId

Update an experience record.

Auth: Bearer token · hr.edit

DELETE /api/v1/hr/employees/:employeeId/experience/:experienceId

Delete an experience record.

Auth: Bearer token · hr.edit

Skills

Employee skills inventory.

GET /api/v1/hr/employees/:employeeId/skills

Get all skills for an employee.

Auth: Bearer token · hr.view

POST /api/v1/hr/employees/:employeeId/skills

Create a new skill.

Auth: Bearer token · hr.edit

PUT /api/v1/hr/employees/:employeeId/skills/:skillId

Update a skill.

Auth: Bearer token · hr.edit

DELETE /api/v1/hr/employees/:employeeId/skills/:skillId

Delete a skill.

Auth: Bearer token · hr.edit

Departments

Organizational departments with hierarchy.

POST /api/v1/hr/departments

Create a new department.

Auth: Bearer token · hr.manage

GET /api/v1/hr/departments

List departments with pagination.

Auth: Bearer token · hr.view

GET /api/v1/hr/departments/hierarchy

Get department hierarchy (tree structure).

Auth: Bearer token · hr.view

GET /api/v1/hr/departments/:id

Get department by ID.

Auth: Bearer token · hr.view

PUT /api/v1/hr/departments/:id

Update a department.

Auth: Bearer token · hr.manage

DELETE /api/v1/hr/departments/:id

Delete a department.

Auth: Bearer token · hr.manage

Designations

Job title and designation management.

POST /api/v1/hr/designations

Create a new designation.

Auth: Bearer token · hr.manage

GET /api/v1/hr/designations

List designations with pagination.

Auth: Bearer token · hr.view

GET /api/v1/hr/designations/:id

Get designation by ID.

Auth: Bearer token · hr.view

PUT /api/v1/hr/designations/:id

Update a designation.

Auth: Bearer token · hr.manage

DELETE /api/v1/hr/designations/:id

Delete a designation.

Auth: Bearer token · hr.manage

Leave Types

Configure leave type definitions (annual, sick, casual, etc.).

POST /api/v1/hr/leave-types

Create a new leave type.

Auth: Bearer token · hr.manage

Request Body
json 
{
  "name": "Annual Leave",
  "code": "AL",
  "maxDaysPerYear": 20,
  "carryForward": true,
  "maxCarryForward": 5
}
GET /api/v1/hr/leave-types

List leave types.

Auth: Bearer token · hr.view

GET /api/v1/hr/leave-types/:id

Get leave type by ID.

Auth: Bearer token · hr.view

PUT /api/v1/hr/leave-types/:id

Update a leave type.

Auth: Bearer token · hr.manage

DELETE /api/v1/hr/leave-types/:id

Delete a leave type.

Auth: Bearer token · hr.manage

Leave Balances

Employee leave balance tracking and accrual.

POST /api/v1/hr/leave-balances

Create or get a leave balance.

Auth: Bearer token · hr.manage

GET /api/v1/hr/leave-balances

List leave balances.

Auth: Bearer token · hr.view

GET /api/v1/hr/leave-balances/employee/:employeeId

Get all balances for an employee for the current year.

Auth: Bearer token · hr.view

GET /api/v1/hr/leave-balances/:id

Get leave balance by ID.

Auth: Bearer token · hr.view

PUT /api/v1/hr/leave-balances/:id

Update a leave balance.

Auth: Bearer token · hr.manage

POST /api/v1/hr/leave-balances/employee/:employeeId/initialize

Initialize balances for an employee for a year (with carry forward).

Auth: Bearer token · hr.manage

POST /api/v1/hr/leave-balances/process-monthly-accrual

Process monthly accrual for all employees.

Auth: Bearer token · hr.manage

POST /api/v1/hr/leave-balances/convert-pending

Convert pending days to used days.

Auth: Bearer token · hr.manage

Leave Requests

Leave request workflow — submit, approve, reject, cancel.

POST /api/v1/hr/leave-requests

Create a new leave request.

Auth: Bearer token

Request Body
json 
{
  "leaveTypeId": 1,
  "startDate": "2026-07-01",
  "endDate": "2026-07-05",
  "reason": "Family vacation"
}
GET /api/v1/hr/leave-requests

List leave requests.

Auth: Bearer token · hr.view

GET /api/v1/hr/leave-requests/pending

Get pending requests for manager approval.

Auth: Bearer token · hr.manage

GET /api/v1/hr/leave-requests/calendar

Get team leave calendar.

Auth: Bearer token · hr.view

GET /api/v1/hr/leave-requests/:id

Get leave request by ID.

Auth: Bearer token · hr.view

PUT /api/v1/hr/leave-requests/:id

Update a leave request (draft only).

Auth: Bearer token

POST /api/v1/hr/leave-requests/:id/submit

Submit a leave request for approval.

Auth: Bearer token

POST /api/v1/hr/leave-requests/:id/approve

Approve a leave request.

Auth: Bearer token · hr.manage

POST /api/v1/hr/leave-requests/:id/reject

Reject a leave request.

Auth: Bearer token · hr.manage

POST /api/v1/hr/leave-requests/:id/cancel

Cancel a leave request.

Auth: Bearer token · hr.manage

POST /api/v1/hr/leave-requests/:id/withdraw

Withdraw a leave request (by the employee).

Auth: Bearer token

Attendance

Time tracking with check-in/check-out and regularization.

POST /api/v1/hr/attendance

Record attendance.

Auth: Bearer token · hr.manage

GET /api/v1/hr/attendance

List attendance records.

Auth: Bearer token · hr.view

POST /api/v1/hr/attendance/check-in

Check in an employee.

Auth: Bearer token

POST /api/v1/hr/attendance/check-out

Check out an employee.

Auth: Bearer token

GET /api/v1/hr/attendance/summary/:employeeId

Get monthly attendance summary.

Auth: Bearer token · hr.view

GET /api/v1/hr/attendance/:id

Get attendance record by ID.

Auth: Bearer token · hr.view

PUT /api/v1/hr/attendance/:id

Update an attendance record.

Auth: Bearer token · hr.manage

POST /api/v1/hr/attendance/:id/regularize

Regularize attendance (correct missed punches).

Auth: Bearer token

POST /api/v1/hr/attendance/bulk

Mark bulk attendance (e.g., for holidays).

Auth: Bearer token · hr.manage

Shifts

Work shift definitions and assignment.

POST /api/v1/hr/shifts

Create a new shift.

Auth: Bearer token · hr.manage

Request Body
json 
{
  "name": "Morning Shift",
  "startTime": "09:00",
  "endTime": "17:00",
  "breakDuration": 60
}
GET /api/v1/hr/shifts

List shifts.

Auth: Bearer token · hr.view

GET /api/v1/hr/shifts/:id

Get shift by ID.

Auth: Bearer token · hr.view

PUT /api/v1/hr/shifts/:id

Update a shift.

Auth: Bearer token · hr.manage

DELETE /api/v1/hr/shifts/:id

Delete a shift.

Auth: Bearer token · hr.manage

POST /api/v1/hr/shifts/assign

Assign a shift to an employee.

Auth: Bearer token · hr.manage

GET /api/v1/hr/shifts/employee/:employeeId/current

Get current shift for an employee.

Auth: Bearer token · hr.view

GET /api/v1/hr/shifts/employee/:employeeId/history

Get shift history for an employee.

Auth: Bearer token · hr.view

Holidays

Company holiday calendar management.

POST /api/v1/hr/holidays

Create a new holiday.

Auth: Bearer token · hr.manage

Request Body
json 
{
  "name": "Independence Day",
  "date": "2026-07-04",
  "type": "public"
}
GET /api/v1/hr/holidays

List holidays.

Auth: Bearer token · hr.view

GET /api/v1/hr/holidays/upcoming

Get upcoming holidays.

Auth: Bearer token · hr.view

GET /api/v1/hr/holidays/year/:year

Get holidays for a specific year.

Auth: Bearer token · hr.view

POST /api/v1/hr/holidays/copy-year

Copy holidays from one year to another.

Auth: Bearer token · hr.manage

GET /api/v1/hr/holidays/check

Check if a date is a holiday.

Auth: Bearer token · hr.view

GET /api/v1/hr/holidays/:id

Get holiday by ID.

Auth: Bearer token · hr.view

PUT /api/v1/hr/holidays/:id

Update a holiday.

Auth: Bearer token · hr.manage

DELETE /api/v1/hr/holidays/:id

Delete a holiday.

Auth: Bearer token · hr.manage

Reimbursements

Expense reimbursement with multi-level approval workflow.

POST /api/v1/hr/reimbursements/upload-receipt

Upload receipt image with AI-powered data extraction.

Auth: Bearer token

POST /api/v1/hr/reimbursements

Create a new reimbursement.

Auth: Bearer token

Request Body
json 
{
  "category": "travel",
  "amount": 150.00,
  "currency": "USD",
  "description": "Client meeting travel",
  "receiptUrl": "...",
  "date": "2026-06-15"
}
GET /api/v1/hr/reimbursements

List reimbursements with filters.

Auth: Bearer token · hr.view

GET /api/v1/hr/reimbursements/my

Get the employee's own reimbursements.

Auth: Bearer token

GET /api/v1/hr/reimbursements/pending-approval

Manager's pending queue (submitted from direct reports).

Auth: Bearer token · hr.manage

GET /api/v1/hr/reimbursements/finance-queue

Finance team's queue (manager-approved reimbursements).

Auth: Bearer token · finance.view

GET /api/v1/hr/reimbursements/:id

Get reimbursement by ID.

Auth: Bearer token · hr.view

PUT /api/v1/hr/reimbursements/:id

Update a draft reimbursement.

Auth: Bearer token

POST /api/v1/hr/reimbursements/:id/submit

Submit reimbursement for approval.

Auth: Bearer token

POST /api/v1/hr/reimbursements/:id/withdraw

Withdraw a submitted reimbursement.

Auth: Bearer token

POST /api/v1/hr/reimbursements/:id/manager-approve

Manager approves reimbursement.

Auth: Bearer token · hr.manage

POST /api/v1/hr/reimbursements/:id/manager-reject

Manager rejects reimbursement.

Auth: Bearer token · hr.manage

POST /api/v1/hr/reimbursements/:id/finance-approve

Finance approves reimbursement.

Auth: Bearer token · finance.approve

POST /api/v1/hr/reimbursements/:id/finance-reject

Finance rejects reimbursement.

Auth: Bearer token · finance.approve

POST /api/v1/hr/reimbursements/:id/mark-paid

Mark reimbursement as paid.

Auth: Bearer token · finance.approve

DELETE /api/v1/hr/reimbursements/:id

Delete a draft reimbursement.

Auth: Bearer token