⚙️API Documentation

HRPBloom AI-HRMS API Documentation

Overview

HRPBloom AI-HRMS provides both Next.js API routes and Express server endpoints for comprehensive HR management functionality.

Base URLs

Next.js API: http://localhost:3000/api
Express Server: http://localhost:3001/api/v1

Authentication

All protected endpoints require JWT authentication via the Authorization header:

Authorization: Bearer <your-jwt-token>

Express Server Endpoints

Health Check

GET /health

Returns server health status and service availability.

Response:

{
  "status": "healthy",
  "timestamp": "2024-01-01T00:00:00.000Z",
  "version": "1.0.1",
  "environment": "development",
  "services": {
    "database": "connected",
    "openai": "configured"
  },
  "uptime": 3600,
  "memory": {
    "rss": 50331648,
    "heapTotal": 20971520,
    "heapUsed": 15728640
  }
}

AI Agent Endpoints

Execute AI Agent Task

POST /api/v1/ai/agent/:type
Authorization: Bearer <token>

Parameters:

type: Agent type (HR_RECRUITER, PAYROLL_MANAGER, COMPLIANCE_OFFICER, TALENT_ADVISOR, CHAT_ASSISTANT)

Body:

{
  "action": "string",
  "data": {}
}

Get AI Tasks

GET /api/v1/ai/tasks?status=pending&agentType=HR_RECRUITER&limit=10&page=1
Authorization: Bearer <token>

Chat with AI Assistant

POST /api/v1/ai/chat
Authorization: Bearer <token>

Body:

{
  "query": "How do I calculate EPF contributions?",
  "employeeId": "emp_123",
  "language": "en"
}

Employee Management

Get All Employees

GET /api/v1/employees?department=IT&status=active&limit=20&page=1
Authorization: Bearer <token>

Get Employee by ID

GET /api/v1/employees/:id
Authorization: Bearer <token>

Create Employee

POST /api/v1/employees
Authorization: Bearer <token>

Body:

{
  "name": "John Doe",
  "email": "[email protected]",
  "icNumber": "123456-78-9012",
  "epfNumber": "12345678",
  "socsoNumber": "87654321",
  "department": "IT",
  "position": "Software Engineer",
  "salary": 5000.00
}

Update Employee

PUT /api/v1/employees/:id
Authorization: Bearer <token>

Delete Employee

DELETE /api/v1/employees/:id
Authorization: Bearer <token>

Payroll Management

Get Payroll Records

GET /api/v1/payroll?month=2024-01&employeeId=emp_123
Authorization: Bearer <token>

Calculate Payroll

POST /api/v1/payroll/calculate
Authorization: Bearer <token>

Body:

{
  "employeeId": "emp_123",
  "month": "2024-01",
  "basicSalary": 5000.00,
  "allowances": 500.00,
  "overtime": 200.00,
  "deductions": 100.00
}

Generate Payslip

POST /api/v1/payroll/payslip
Authorization: Bearer <token>

Compliance Management

Get Compliance Status

GET /api/v1/compliance/status
Authorization: Bearer <token>

Check PDPA Compliance

POST /api/v1/compliance/pdpa/check
Authorization: Bearer <token>

Get Statutory Deadlines

GET /api/v1/compliance/deadlines?upcoming=true
Authorization: Bearer <token>

Integration Endpoints

EPF Integration

POST /api/v1/integrations/epf/submit
Authorization: Bearer <token>

SOCSO Integration

POST /api/v1/integrations/socso/submit
Authorization: Bearer <token>

LHDN Tax Submission

POST /api/v1/integrations/lhdn/submit
Authorization: Bearer <token>

MyFutureJobs Integration

POST /api/v1/integrations/myfuturejobs/post-job
Authorization: Bearer <token>

Document Management

Upload Document

POST /api/v1/documents/upload
Authorization: Bearer <token>
Content-Type: multipart/form-data

Get Documents

GET /api/v1/documents?employeeId=emp_123&category=contract
Authorization: Bearer <token>

Download Document

GET /api/v1/documents/:id/download
Authorization: Bearer <token>

Reports

Generate Employee Report

POST /api/v1/reports/employees
Authorization: Bearer <token>

Generate Payroll Report

POST /api/v1/reports/payroll
Authorization: Bearer <token>

Generate Compliance Report

POST /api/v1/reports/compliance
Authorization: Bearer <token>

Next.js API Routes

Chat Assistant

POST /api/chat
Authorization: Bearer <clerk-token>

Body:

{
  "messages": [
    {
      "role": "user",
      "content": "How do I calculate Malaysian income tax?"
    }
  ],
  "model": "gpt-4",
  "temperature": 0.7,
  "maxTokens": 1500
}

Employee Management

GET /api/employees
POST /api/employees
PUT /api/employees
DELETE /api/employees

File Upload

POST /api/upload
Content-Type: multipart/form-data

Health Check

GET /api/health

Error Responses

All endpoints return consistent error responses:

{
  "error": {
    "message": "Error description",
    "status": 400,
    "code": "VALIDATION_ERROR",
    "details": {}
  }
}

Common HTTP Status Codes

200 - Success
201 - Created
400 - Bad Request
401 - Unauthorized
403 - Forbidden
404 - Not Found
429 - Too Many Requests
500 - Internal Server Error
503 - Service Unavailable

Rate Limiting

Default: 100 requests per 15 minutes per IP
Chat API: 20 requests per minute per user
File Upload: 10 requests per minute per user

Malaysian Government API Integrations

EPF/KWSP

Contribution calculations
Monthly submissions
Employee registration

SOCSO/Perkeso

Social security contributions
Claim submissions
Employee coverage

LHDN

Income tax calculations
PCB submissions
Tax clearance

HRDF

Training levy management
Grant applications
Training records

JTK

Safety compliance
Health regulations
Incident reporting

MyFutureJobs

Job posting synchronization
Application management
Candidate tracking

Environment Variables

# Server Configuration
SERVER_PORT=3001
NODE_ENV=development
RATE_LIMIT_MAX=100

# Database
DATABASE_URL="postgresql://..."
DATABASE_AUTHENTICATED_URL="postgresql://..."

# Authentication
JWT_SECRET="your-jwt-secret"
CLERK_SECRET_KEY="your-clerk-secret"

# AI Services
OPENAI_API_KEY="your-openai-key"
OPENAI_ORG_ID="your-org-id"

# Malaysian Government APIs
EPF_API_KEY="your-epf-key"
SOCSO_API_KEY="your-socso-key"
LHDN_API_KEY="your-lhdn-key"
HRDF_API_KEY="your-hrdf-key"
JTK_API_KEY="your-jtk-key"
MY_FUTURE_JOBS_API_KEY="your-myfuturejobs-key"

# Security
ALLOWED_ORIGINS="http://localhost:3000,http://localhost:5173"
ENCRYPTION_KEY="your-encryption-key"

Development

Start Development Servers

# Start both Next.js and Express servers
npm run dev:all

# Start only Express server
npm run dev:server

# Start only Next.js
npm run dev

Build for Production

# Build both applications
npm run build:all

# Build only Express server
npm run build:server

Testing API Endpoints

Use tools like Postman, Insomnia, or curl to test the endpoints:

# Health check
curl http://localhost:3001/health

# Chat with AI (requires authentication)
curl -X POST http://localhost:3001/api/v1/ai/chat \
  -H "Authorization: Bearer your-jwt-token" \
  -H "Content-Type: application/json" \
  -d '{"query": "How to calculate EPF?", "employeeId": "emp_123"}'

PreviousDirectory Analysis Report NextAPI Route Consolidation

Last updated 5 months ago

Was this helpful?

Good afternoon

hashtagOverview

hashtagBase URLs

hashtagAuthentication

hashtagExpress Server Endpoints

hashtagHealth Check

hashtagAI Agent Endpoints

hashtagEmployee Management

hashtagPayroll Management

hashtagCompliance Management

hashtagIntegration Endpoints

hashtagDocument Management

hashtagReports

hashtagNext.js API Routes

hashtagChat Assistant

hashtagEmployee Management

hashtagFile Upload

hashtagHealth Check

hashtagError Responses

hashtagCommon HTTP Status Codes

hashtagRate Limiting

hashtagMalaysian Government API Integrations

hashtagEPF/KWSP

hashtagSOCSO/Perkeso

hashtagLHDN

hashtagHRDF

hashtagJTK

hashtagMyFutureJobs

hashtagEnvironment Variables

hashtagDevelopment

hashtagStart Development Servers

hashtagBuild for Production

hashtagTesting API Endpoints

Overview

Base URLs

Authentication

Express Server Endpoints

Health Check

AI Agent Endpoints

Employee Management

Payroll Management

Compliance Management

Integration Endpoints

Document Management

Reports

Next.js API Routes

Chat Assistant

Employee Management

File Upload

Health Check

Error Responses

Common HTTP Status Codes

Rate Limiting

Malaysian Government API Integrations

EPF/KWSP

SOCSO/Perkeso

LHDN

HRDF

JTK

MyFutureJobs

Environment Variables

Development

Start Development Servers

Build for Production

Testing API Endpoints