HR Tool - API Specification Document v3.1.2

Table of Contents

• HR Tool - API Specification Document v3.1.2
  • Table of Contents
  • 1. Overview
    • 1.1 Purpose
    • 1.2 Base URLs
    • 1.3 What's New in Phase 2
  • 2. Authentication (OAuth 2.0)
    • 2.1 OAuth 2.0 Flow Overview
    • 2.2 Obtaining Access Tokens
      • Request Headers
      • Request Parameters
      • Request Example
      • Response Example
      • Response Parameters
    • 2.3 Using Access Tokens
      • Request Example
    • 2.4 JWT Token Structure
    • 2.5 Mandatory Header for Client Credentials Grant
  • 3. Employee Management APIs
    • 3.1 Get Employee List
      • Request Parameters
      • Request Example
      • Response Example
    • 3.2 Create Employee
      • Request Parameters
      • Request Example
      • Response Example
    • 3.3 Get Employee Details
      • Path Parameters
      • Response Example
    • 3.4 Update Employee
      • Path Parameters
      • Request Parameters
      • Response Example
    • 3.5 Delete Employee
      • Path Parameters
      • Response Example
    • 3.6 Offboard Employee
      • Path Parameters
      • Query Parameters
      • Response Example
    • 3.7 Restore Employee
      • Path Parameters
      • Response Example
  • 4. Leave Type Management APIs
    • 4.1 Get Leave Type List
      • Request Parameters
      • Request Example
      • Response Example
    • 4.2 Create Leave Type
      • Request Parameters
      • Request Example
      • Response Example
    • 4.3 Get Leave Type Details
      • Path Parameters
      • Response Example
    • 4.4 Update Leave Type
      • Path Parameters
      • Request Parameters
      • Response Example
    • 4.5 Delete Leave Type
      • Path Parameters
      • Response Example
  • 5. Leave Request Management APIs
    • 5.1 Get Leave Request List
      • Request Parameters
      • Request Example
      • Response Example
    • 5.2 Create Leave Request
      • Request Parameters
      • Request Example
      • Response Example
    • 5.3 Get Leave Request Details
      • Path Parameters
      • Response Example
    • 5.4 Update Leave Request
      • Path Parameters
      • Request Parameters
      • Response Example
    • 5.5 Approve Leave Request
      • Path Parameters
      • Response Example
    • 5.6 Reject Leave Request
      • Path Parameters
      • Query Parameters
      • Response Example
    • 5.7 Delete Leave Request
      • Path Parameters
      • Response Example
  • 6. Position Management APIs
    • 6.1 Get Position List
      • Request Parameters
      • Response Example
    • 6.2 Create Position
      • Request Parameters
      • Request Example
      • Response Example
    • 6.3 Get Position Details
      • Path Parameters
      • Response Example
    • 6.4 Update Position
      • Path Parameters
      • Request Parameters
      • Response Example
    • 6.5 Delete Position
      • Path Parameters
      • Response Example
  • 7. Job Listings APIs
    • 7.1 Get Job Listings List
      • Request Parameters
      • Response Example
    • 7.2 Create Job Listing
      • Request Parameters
      • Request Example
      • Response Example
    • 7.3 Get Job Listing Details
      • Path Parameters
      • Response Example
    • 7.4 Update Job Listing
      • Path Parameters
      • Request Parameters
      • Response Example
    • 7.5 Delete Job Listing
      • Path Parameters
      • Response Example
  • 8. Holiday Entitlements APIs
    • 8.1 Get Holiday Entitlements List
      • Request Parameters
      • Response Example
    • 8.2 Create Holiday Entitlement
      • Request Parameters
      • Request Example
      • Response Example
    • 8.3 Get Holiday Entitlement Details
      • Path Parameters
      • Response Example
    • 8.4 Update Holiday Entitlement
      • Path Parameters
      • Request Parameters
      • Response Example
    • 8.5 Delete Holiday Entitlement
      • Path Parameters
      • Response Example
  • 9. Department Management APIs
    • 9.1 Get Department List
      • Request Parameters
      • Response Example
    • 9.2 Create Department
      • Request Parameters
      • Request Example
      • Response Example
    • 9.3 Get Department Details
      • Path Parameters
    • 9.4 Update Department
      • Path Parameters
      • Request Parameters
    • 9.5 Delete Department
      • Path Parameters
      • Response Example
  • 10. Role Management APIs
    • 10.1 Get Role List
      • Request Parameters
      • Response Example
    • 10.2 Create Role
      • Request Parameters
      • Request Example
      • Response Example
    • 10.3 Get Role Details
      • Path Parameters
    • 10.4 Update Role
      • Path Parameters
      • Request Parameters
    • 10.5 Delete Role
      • Path Parameters
      • Response Example
  • 11. Policy Management APIs
    • 11.1 Get Policy List
      • Request Parameters
    • 11.2 Create Policy
      • Request Parameters
      • Request Example
      • Response Example
    • 11.3 Get Policy Details
      • Path Parameters
    • 11.4 Update Policy
      • Path Parameters
      • Request Parameters
    • 11.5 Archive Policy
      • Path Parameters
      • Response Example
    • 11.6 Delete Policy
      • Path Parameters
      • Response Example
  • 12. Document Management APIs
    • 12.1 Get Document List
      • Request Parameters
    • 12.2 Create Document
      • Request Parameters
      • Request Example
    • 12.3 Get Document Details
      • Path Parameters
    • 12.4 Update Document
      • Path Parameters
      • Request Parameters
    • 12.5 Delete Document
      • Path Parameters
      • Response Example
  • 13. Employee Contract APIs
    • 13.1 Get Contract List
      • Request Parameters
    • 13.2 Get Expired Contracts
      • Request Parameters
    • 13.3 Create Contract
      • Request Parameters
      • Request Example
    • 13.4 Get Contract by ID
      • Path Parameters
    • 13.5 Update Contract
      • Path Parameters
      • Request Parameters
    • 13.6 Renew Contract
      • Path Parameters
      • Request Parameters
      • Request Example
    • 13.7 Delete Contract
      • Path Parameters
      • Response Example
  • 14. Contract Template APIs
    • 14.1 Get Template List
      • Request Parameters
    • 14.2 Create Template
      • Request Parameters
      • Request Example
    • 14.3 Get Template by ID
      • Path Parameters
    • 14.4 Update Template
      • Path Parameters
      • Request Parameters
    • 14.5 Delete Template
      • Path Parameters
      • Response Example
  • 15. Company Settings APIs
    • 15.1 Get Company Settings
      • Response Example
    • 15.2 Update Company Settings
      • Request Parameters
      • Request Example
      • Response Example
  • 16. File Upload API
    • 16.1 Upload File
      • Response Example
  • 17. Menu Management APIs
    • 17.1 Get Menu List
    • 17.2 Get Menu Tree
      • Response Example
    • 17.3 Get Menu by ID
      • Path Parameters
  • 18. Company Provision API
    • 18.1 Auto-Provision HR Company Instance
      • Request Parameters
      • Request Example
      • Response Example
      • Error Responses
  • 19. Emergency Contacts API
    • 19.1 Get Emergency Contacts Report
      • Request Parameters
      • Response Example
  • 20. Error Handling
    • 20.1 Standard Error Response
    • 20.2 HTTP Status Codes
    • 20.3 OAuth Error Codes
  • 21. Rate Limiting & Security
    • 21.1 Rate Limits
    • 21.2 Security Requirements
  • 22. Integration Checklist
    • 22.1 Pre-Integration
    • 22.2 Implementation Tasks
    • 22.3 Testing Requirements
    • 22.4 Production Readiness
  • Appendix A: Quick Reference
    • A.1 Key Endpoints Summary
    • A.2 Token Lifetimes

---

1. Overview

1.1 Purpose

This document outlines the REST API specifications for the HR Tool system. The Phase 2 implementation introduces OAuth 2.0 authentication, providing enterprise-grade security and enabling Single Sign-On (SSO) capabilities.

This API enables companies to integrate with the HR Tool for employee data synchronization, leave management, and user authentication. This also includes OAuth 2.0 implementation which allows HR Tool users to authenticate directly into their local platform using their HR Tool credentials.

1.2 Base URLs

Environment	Base URL
Testing	http://xz-ai.info:8197
Production	https://hr.shiftcare.com/api

1.3 What's New in Phase 2

• OAuth 2.0 Client Credentials Grant — Secure machine-to-machine authentication
• JWT Access Tokens — RS256 signed tokens with 15-minute expiry
• Enhanced Security — OWASP Top 10 compliance, rate limiting, audit logging
• Improved Performance — Caching layer for faster API responses

---

2. Authentication (OAuth 2.0)

IMPORTANT: All API endpoints require OAuth 2.0 authentication using Bearer tokens. Legacy authentication methods are to be deprecated.

2.1 OAuth 2.0 Flow Overview

HR Tool implements the OAuth 2.0 Client Credentials Grant flow, suitable for server-to-server authentication where Shiftcare acts as the client.

Authentication Flow (where Company is your entity):

1. Company → POST /oauth2/token with client credentials
2. HR Tool validates credentials and issues tokens
3. Company receives access_token (15 min)
4. Company uses access_token in Authorization header for API calls

2.2 Obtaining Access Tokens

Brief Description: Obtain an access token using client credentials

Request URL: /oauth2/token

Is Certification Required? No

Request Method: POST

Request Headers

Header	Value
Content-Type	application/x-www-form-urlencoded

Request Parameters

Parameter Name	Required	Type	Explanation
grant_type	Yes	String	Must be client_credentials
client_id	Yes	String	Your application's client ID (provided by HR Tool)
client_secret	Yes	String	Your application's client secret (provided by HR Tool)
scope	No	String	Space-delimited scopes (default: read write)

Request Example

curl -X POST https://hr.shiftcare.com/api/oauth2/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials" \
  -d "client_id=YOUR_CLIENT_ID" \
  -d "client_secret=YOUR_CLIENT_SECRET"

Response Example

{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "Bearer",
  "expires_in": 900,
  "scope": "read write"
}

Response Parameters

Parameter Name	Type	Explanation
access_token	String	JWT access token (valid for 15 minutes)
token_type	String	Always "Bearer" — use in Authorization header
expires_in	Integer	Token lifetime in seconds (900 = 15 minutes)
scope	String	Granted permissions (space-delimited)

---

2.3 Using Access Tokens

Include the access token in the Authorization header of all API requests:

Authorization: Bearer YOUR_ACCESS_TOKEN

Request Example

curl -X GET https://hr.shiftcare.com/api/hr/v1/employees \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..."

---

2.4 JWT Token Structure

Access tokens are JSON Web Tokens (JWT) signed with the RS256 algorithm.

Standard Claims:

Claim	Description
iss	Issuer (HR Tool)
sub	Subject (client_id)
aud	Audience (HR Tool API)
exp	Expiration time (Unix timestamp)
iat	Issued at (Unix timestamp)
jti	JWT ID (unique token identifier)

Token Verification:

Public keys for JWT verification are available at:

GET https://hr.shiftcare.com/api/oauth2/jwks

---

2.5 Mandatory Header for Client Credentials Grant

All business APIs accessed with a token obtained via the client_credentials grant MUST include the following header:

X-Enterprise-Id: {your-enterprise-id}

Field	Details
Location	Request Header
Required	YES
Description	Enterprise unique ID in the HR system (multi-tenant isolation)
Error	Missing or invalid value will return 400/403 Forbidden

Note: The Company Provision API (Section 18) does not require the X-Enterprise-Id header.

---

3. Employee Management APIs

Authentication Required: All endpoints require a valid OAuth 2.0 access token in the Authorization header.

3.1 Get Employee List

Brief Description: Retrieve a paginated list of employees with filtering options

Request URL: /hr/v1/employees

Is Certification Required? Yes

Request Method: GET

Scope: employee:read

Request Parameters

Parameter Name	Required	Type	Explanation
page	No	Integer	Page number (default: 1)
size	No	Integer	Page size (max: 100, default: 20)
status	No	Integer	0 = All, 1 = Active, 2 = Resigned, 3 = Offboarding

Request Example

GET /hr/v1/employees?page=1&size=20&status=1
Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...

Response Example

{
  "success": true,
  "statusCode": 200,
  "data": [
    {
      "employeeId": 1997903282458996738,
      "firstName": "John",
      "lastName": "Smith",
      "email": "john.smith@example.com",
      "phoneCode": "AU",
      "phone": "+61 412345678",
      "status": "1",
      "employmentType": "1",
      "createdDate": "2024-12-08T13:37:16",
      "updatedDate": "2024-12-15T09:20:30"
    }
  ],
  "pagination": {
    "currentPage": 1,
    "pageSize": 20,
    "totalItems": 1,
    "totalPages": 1,
    "hasNextPage": false,
    "hasPreviousPage": false
  }
}

---

3.2 Create Employee

Brief Description: Create a new employee record. Your company can call this endpoint to sync employee data from your platform to the HR Tool.

Request URL: /hr/v1/employees

Is Certification Required? Yes

Request Method: POST

Scope: employee:write

Request Parameters

Parameter Name	Required	Type	Explanation
firstName	Yes	String	Employee first name
lastName	Yes	String	Employee last name
email	Yes	String	Employee email address
phone	Yes	String	Employee phone number
phoneCode	Yes	String	Mobile phone country code (e.g. AU)
username	Yes	String	Login username
roleId	Yes	String	Role ID — obtain from the Role API (Section 10)
position	No	String	Job position/title
employmentType	No	String	1 = Full-Time, 2 = Part-Time, 3 = Internship
hiredOn	No	String	Hire date (YYYY-MM-DD)
workPhone	No	String	Work phone number
workPhoneCode	No	String	Work phone country code (e.g. AU)
country	No	String	Country
address1	No	String	Address line 1
address2	No	String	Address line 2
city	No	String	City
province	No	String	State / Province
postalCode	No	String	Postal code
externalId	No	String	External system identifier (e.g. ShiftCare staff ID)

Request Example

{
  "firstName": "Jane",
  "lastName": "Doe",
  "email": "jane.doe@example.com",
  "phoneCode": "AU",
  "phone": "+61 423456789",
  "position": "Support Worker",
  "employmentType": "1",
  "hiredOn": "2024-01-15",
  "username": "janedoe",
  "roleId": "134",
  "workPhoneCode": "AU",
  "workPhone": "+61 325432345",
  "country": "United States",
  "address1": "123 Main Street",
  "address2": "Apt 4B",
  "city": "New York",
  "province": "NY",
  "postalCode": "10001",
  "externalId": "shiftcare_staff_12345"
}

Response Example

{
  "success": true,
  "statusCode": 201,
  "data": {
    "employeeId": 2046765589981163521,
    "firstName": "Jane",
    "lastName": "Doe",
    "email": "jane.doe@example.com",
    "phoneCode": "AU",
    "phone": "+61 387654321",
    "position": "Support Worker",
    "status": "1",
    "hiredOn": "2026-03-26",
    "externalId": "shiftcare-312322",
    "workPhoneCode": "AU",
    "workPhone": "+61 325432345",
    "employmentType": "1",
    "country": "United States",
    "address1": "123 Main Street",
    "address2": "Apt 4B",
    "city": "New York",
    "province": "NY",
    "postalCode": "10001",
    "createdDate": "2026-04-22T01:38:37",
    "updatedDate": "2026-04-22T01:38:37"
  }
}

---

3.3 Get Employee Details

Brief Description: Retrieve detailed information for a specific employee

Request URL: /hr/v1/employees/{employeeId}

Is Certification Required? Yes

Request Method: GET

Scope: employee:read

Path Parameters

Parameter Name	Required	Type	Explanation
employeeId	Yes	Integer	Employee ID from HR Tool

Response Example

{
  "success": true,
  "statusCode": 200,
  "data": {
    "employeeId": 2046765589981163521,
    "firstName": "Jane",
    "lastName": "Doe",
    "email": "jane.doe@example.com",
    "phoneCode": "AU",
    "phone": "+61 387654321",
    "position": "Support Worker",
    "status": "1",
    "hiredOn": "2026-03-26",
    "externalId": "shiftcare-312322",
    "workPhoneCode": "AU",
    "workPhone": "+61 325432345",
    "employmentType": "1",
    "country": "United States",
    "address1": "123 Main Street",
    "address2": "Apt 4B",
    "city": "New York",
    "province": "NY",
    "postalCode": "10001",
    "createdDate": "2026-04-22T01:38:37",
    "updatedDate": "2026-04-22T01:38:37"
  }
}

---

3.4 Update Employee

Brief Description: Update existing employee information

Request URL: /hr/v1/employees/{employeeId}

Is Certification Required? Yes

Request Method: PUT

Scope: employee:write

Path Parameters

Parameter Name	Required	Type	Explanation
employeeId	Yes	Integer	Employee ID from HR Tool

Request Parameters

Same fields as Create Employee — include only the fields to update.

Response Example

{
  "success": true,
  "statusCode": 200,
  "data": {
    "employeeId": 2046765589981163521,
    "firstName": "Jane",
    "lastName": "Doe",
    "email": "jane.doe@example.com",
    "phoneCode": "AU",
    "phone": "+61 387654321",
    "position": "Support Worker",
    "status": "1",
    "hiredOn": "2026-03-26",
    "externalId": "shiftcare-312322",
    "workPhoneCode": "AU",
    "workPhone": "+61 325432345",
    "employmentType": "1",
    "country": "United States",
    "address1": "123 Main Street",
    "address2": "Apt 4B",
    "city": "New York",
    "province": "NY",
    "postalCode": "10001",
    "createdDate": "2026-04-22T01:38:37",
    "updatedDate": "2026-04-22T01:38:37"
  }
}

---

3.5 Delete Employee

Brief Description: Soft delete an employee (marks as inactive)

Request URL: /hr/v1/employees/{employeeId}

Is Certification Required? Yes

Request Method: DELETE

Scope: employee:admin

Path Parameters

Parameter Name	Required	Type	Explanation
employeeId	Yes	Integer	Employee ID from HR Tool

Response Example

{
  "success": true,
  "statusCode": 200
}

---

3.6 Offboard Employee

Brief Description: Mark an employee as resigned. The employee record is retained but status is changed to RESIGNED.

Request URL: /hr/v1/employees/{employeeId}/offboard

Is Certification Required? Yes

Request Method: PUT

Scope: employee:admin

Path Parameters

Parameter Name	Required	Type	Explanation
employeeId	Yes	Integer	Employee ID from HR Tool

Query Parameters

Parameter Name	Required	Type	Explanation
resignationDate	No	String	Resignation date (YYYY-MM-DD)
reason	No	String	Resignation reason (max 500 characters)

Response Example

{
  "success": true,
  "statusCode": 200,
  "data": {
    "employeeId": 2046765589981163521,
    "firstName": "Jane",
    "lastName": "Doe",
    "email": "jane.doe@example.com",
    "phoneCode": "AU",
    "phone": "+61 387654321",
    "position": "Support Worker",
    "status": "2",
    "hiredOn": "2026-03-26",
    "externalId": "shiftcare-312322",
    "createdDate": "2026-04-22T01:38:37",
    "updatedDate": "2026-04-22T01:38:37"
  }
}

---

3.7 Restore Employee

Brief Description: Reactivate a previously resigned employee. Changes status back to ACTIVE.

Request URL: /hr/v1/employees/{employeeId}/restore

Is Certification Required? Yes

Request Method: PUT

Scope: employee:admin

Path Parameters

Parameter Name	Required	Type	Explanation
employeeId	Yes	Integer	Employee ID from HR Tool

Response Example

{
  "success": true,
  "statusCode": 200,
  "data": {
    "employeeId": 2046765589981163521,
    "firstName": "Jane",
    "lastName": "Doe",
    "email": "jane.doe@example.com",
    "phoneCode": "AU",
    "phone": "+61 387654321",
    "position": "Support Worker",
    "status": "1",
    "hiredOn": "2026-03-26",
    "externalId": "shiftcare-312322",
    "createdDate": "2026-04-22T01:38:37",
    "updatedDate": "2026-04-22T01:38:37"
  }
}

---

4. Leave Type Management APIs

Authentication Required: All endpoints require a valid OAuth 2.0 access token in the Authorization header.

4.1 Get Leave Type List

Brief Description: Retrieve a paginated list of leave types

Request URL: /hr/v1/leave-types

Is Certification Required? Yes

Request Method: GET

Scope: leaveType:read

Request Parameters

Parameter Name	Required	Type	Explanation
page	No	Integer	Page number (default: 1)
size	No	Integer	Page size (max: 100, default: 20)

Request Example

GET /hr/v1/leave-types?page=1&size=20
Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...

Response Example

{
  "success": true,
  "statusCode": 200,
  "data": [
    {
      "leaveTypeId": 1001,
      "leaveName": "Annual Leave",
      "leaveType": "1",
      "entitlement": 152.00,
      "accrualFrequency": "4",
      "resetDate": "1",
      "carryOverPolicy": 40,
      "carryOverStatus": "1",
      "paidLeaveStatus": "1",
      "maxDaysAllowed": 10,
      "createDate": "2026-04-01T10:30:00",
      "updatedDate": "2026-04-01T10:30:00"
    }
  ],
  "pagination": {
    "currentPage": 1,
    "pageSize": 20,
    "totalItems": 1,
    "totalPages": 1,
    "hasNextPage": false,
    "hasPreviousPage": false
  }
}

---

4.2 Create Leave Type

Brief Description: Create a new leave type in the system

Request URL: /hr/v1/leave-types

Is Certification Required? Yes

Request Method: POST

Scope: leaveType:write

Request Parameters

Field	Type	Required	Description
leaveName	String	Yes	Leave type name
leaveType	String	Yes	Leave type code: 1=Annual Leave, 2=Sick Leave, 3=Maternity Leave, 4=Long Service Leave, 5=Paid Leave, 6=Personal Leave, 7=Other Unpaid Leave, 8=Time off in lieu, 9=Maternity/Paternity Leave, 10=Bereavement Leave, 11=Birthday Leave, 12=Carer's Leave, 13=Floating Public Holiday
entitlement	Decimal	No	Entitlement (Hours/Year)
accrualFrequency	String	No	0=Weekly, 1=Monthly, 2=Quarterly, 3=Semi-Monthly, 4=Yearly
resetDate	String	No	1=Anniversary Date, 2=Calendar Year
carryOverPolicy	Long	No	Maximum hours allowed to carry over
carryOverStatus	String	No	1=Allow, 2=Reject
paidLeaveStatus	String	No	0=Unpaid, 1=Paid
maxDaysAllowed	Integer	No	Maximum days allowed

Request Example

{
  "leaveName": "Annual Leave",
  "leaveType": "1",
  "entitlement": 152.00,
  "accrualFrequency": "4",
  "resetDate": "1",
  "carryOverPolicy": 40,
  "carryOverStatus": "1",
  "paidLeaveStatus": "1",
  "maxDaysAllowed": 10
}

Response Example

{
  "success": true,
  "statusCode": 201,
  "data": {
    "leaveTypeId": 1001,
    "leaveName": "Annual Leave",
    "leaveType": "1",
    "entitlement": 152.00,
    "accrualFrequency": "4",
    "resetDate": "1",
    "carryOverPolicy": 40,
    "carryOverStatus": "1",
    "paidLeaveStatus": "1",
    "maxDaysAllowed": 10,
    "createDate": "2026-04-22T10:30:00",
    "updatedDate": "2026-04-22T10:30:00"
  }
}

---

4.3 Get Leave Type Details

Brief Description: Retrieve detailed information for a specific leave type

Request URL: /hr/v1/leave-types/{leaveTypeId}

Is Certification Required? Yes

Request Method: GET

Scope: leaveType:read

Path Parameters

Parameter Name	Required	Type	Explanation
leaveTypeId	Yes	Integer	Leave type unique identifier

Response Example

{
  "success": true,
  "statusCode": 200,
  "data": {
    "leaveTypeId": 1001,
    "leaveName": "Annual Leave",
    "leaveType": "1",
    "entitlement": 152.00,
    "accrualFrequency": "4",
    "resetDate": "1",
    "carryOverPolicy": 40,
    "carryOverStatus": "1",
    "paidLeaveStatus": "1",
    "maxDaysAllowed": 10,
    "createDate": "2026-04-01T10:30:00",
    "updatedDate": "2026-04-01T10:30:00"
  }
}

---

4.4 Update Leave Type

Brief Description: Update leave type information

Request URL: /hr/v1/leave-types/{leaveTypeId}

Is Certification Required? Yes

Request Method: PUT

Scope: leaveType:write

Path Parameters

Parameter Name	Required	Type	Explanation
leaveTypeId	Yes	Integer	Leave type unique identifier

Request Parameters

Same fields as Create Leave Type — include only the fields to update.

Response Example

{
  "success": true,
  "statusCode": 200,
  "data": {
    "leaveTypeId": 1001,
    "leaveName": "Annual Leave (Updated)",
    "leaveType": "1",
    "entitlement": 160.00,
    "accrualFrequency": "4",
    "resetDate": "1",
    "carryOverPolicy": 40,
    "carryOverStatus": "1",
    "paidLeaveStatus": "1",
    "maxDaysAllowed": 10,
    "createDate": "2026-04-01T10:30:00",
    "updatedDate": "2026-04-22T14:00:00"
  }
}

---

4.5 Delete Leave Type

Brief Description: Delete a leave type record

Request URL: /hr/v1/leave-types/{leaveTypeId}

Is Certification Required? Yes

Request Method: DELETE

Scope: leaveType:admin

Path Parameters

Parameter Name	Required	Type	Explanation
leaveTypeId	Yes	Integer	Leave type unique identifier

Response Example

{
  "success": true,
  "statusCode": 200
}

---

5. Leave Request Management APIs

Authentication Required: All endpoints require a valid OAuth 2.0 access token in the Authorization header.

5.1 Get Leave Request List

Brief Description: Retrieve a paginated list of leave requests

Request URL: /hr/v1/leave-requests

Is Certification Required? Yes

Request Method: GET

Scope: leaveRequest:read

Request Parameters

Parameter Name	Required	Type	Explanation
page	No	Integer	Page number (default: 1)
size	No	Integer	Page size (max: 100, default: 20)
status	No	String	Leave request status: 1=Approved, 3=Pending, 4=Rejected

Request Example

GET /hr/v1/leave-requests?page=1&size=20
Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...

Response Example

{
  "success": true,
  "statusCode": 200,
  "data": [
    {
      "leaveId": 2001,
      "employeeId": 2046765589981163521,
      "employeeName": "Jane Doe",
      "leaveType": "1",
      "fromDateTime": "2026-04-25 09:00",
      "toDateTime": "2026-04-27 18:00",
      "notes": "Family vacation",
      "totalDays": 3,
      "status": 1,
      "rejectReason": null,
      "approverId": null,
      "approverName": null,
      "createDate": "2026-04-22T10:00:00",
      "updatedDate": "2026-04-22T10:00:00"
    }
  ],
  "pagination": {
    "currentPage": 1,
    "pageSize": 20,
    "totalItems": 1,
    "totalPages": 1,
    "hasNextPage": false,
    "hasPreviousPage": false
  }
}

---

5.2 Create Leave Request

Brief Description: Create a new leave request in the system

Request URL: /hr/v1/leave-requests

Is Certification Required? Yes

Request Method: POST

Scope: leaveRequest:write

Request Parameters

Field	Type	Required	Description
employeeId	Long	Yes	Employee ID from HR Tool
leaveType	String	Yes	Leave type code (1–13, see Section 4 enum values)
fromDateTime	String	Yes	Start date and time (format: yyyy-MM-dd HH:mm)
toDateTime	String	Yes	End date and time (format: yyyy-MM-dd HH:mm)
notes	String	No	Leave request notes
totalDays	Decimal	No	Total leave days
externalId	String	No	External system identifier

Request Example

{
  "employeeId": 2046765589981163521,
  "leaveType": "1",
  "fromDateTime": "2026-04-25 09:00",
  "toDateTime": "2026-04-27 18:00",
  "notes": "Family vacation",
  "totalDays": 3,
  "externalId": "4234"
}

Response Example

{
  "success": true,
  "statusCode": 201,
  "data": {
    "leaveId": 2001,
    "employeeId": 2046765589981163521,
    "employeeName": "Jane Doe",
    "leaveType": "1",
    "fromDateTime": "2026-04-25 09:00",
    "toDateTime": "2026-04-27 18:00",
    "notes": "Family vacation",
    "totalDays": 3,
    "status": 1,
    "createDate": "2026-04-22T10:00:00",
    "updatedDate": "2026-04-22T10:00:00"
  }
}

---

5.3 Get Leave Request Details

Brief Description: Retrieve detailed information for a specific leave request

Request URL: /hr/v1/leave-requests/{leaveId}

Is Certification Required? Yes

Request Method: GET

Scope: leaveRequest:read

Path Parameters

Parameter Name	Required	Type	Explanation
leaveId	Yes	Integer	Leave request unique identifier

Response Example

{
  "success": true,
  "statusCode": 200,
  "data": {
    "leaveId": 2001,
    "employeeId": 2046765589981163521,
    "employeeName": "Jane Doe",
    "leaveType": "1",
    "fromDateTime": "2026-04-25 09:00",
    "toDateTime": "2026-04-27 18:00",
    "notes": "Family vacation",
    "totalDays": 3,
    "status": 1,
    "rejectReason": null,
    "approverId": null,
    "approverName": null,
    "createDate": "2026-04-22T10:00:00",
    "updatedDate": "2026-04-22T10:00:00"
  }
}

---

5.4 Update Leave Request

Brief Description: Update leave request information

Request URL: /hr/v1/leave-requests/{leaveId}

Is Certification Required? Yes

Request Method: PUT

Scope: leaveRequest:write

Path Parameters

Parameter Name	Required	Type	Explanation
leaveId	Yes	Integer	Leave request unique identifier

Request Parameters

Same fields as Create Leave Request (excluding employeeId) — include only the fields to update.

Response Example

{
  "success": true,
  "statusCode": 200,
  "data": {
    "leaveId": 2001,
    "employeeId": 2046765589981163521,
    "employeeName": "Jane Doe",
    "leaveType": "1",
    "fromDateTime": "2026-04-26 09:00",
    "toDateTime": "2026-04-28 18:00",
    "notes": "Family vacation",
    "totalDays": 3,
    "status": 1,
    "createDate": "2026-04-22T10:00:00",
    "updatedDate": "2026-04-22T14:00:00"
  }
}

---

5.5 Approve Leave Request

Brief Description: Approve a pending leave request

Request URL: /hr/v1/leave-requests/{leaveId}/approve

Is Certification Required? Yes

Request Method: POST

Scope: leaveRequest:write

Path Parameters

Parameter Name	Required	Type	Explanation
leaveId	Yes	Integer	Leave request unique identifier

Response Example

{
  "success": true,
  "statusCode": 200,
  "data": {
    "leaveId": 2001,
    "employeeId": 2046765589981163521,
    "employeeName": "Jane Doe",
    "leaveType": "1",
    "fromDateTime": "2026-04-25 09:00",
    "toDateTime": "2026-04-27 18:00",
    "notes": "Family vacation",
    "totalDays": 3,
    "status": 1,
    "approverId": 2046765589981163500,
    "approverName": "Admin User",
    "createDate": "2026-04-22T10:00:00",
    "updatedDate": "2026-04-22T15:00:00"
  }
}

---

5.6 Reject Leave Request

Brief Description: Reject a pending leave request

Request URL: /hr/v1/leave-requests/{leaveId}/reject

Is Certification Required? Yes

Request Method: POST

Scope: leaveRequest:write

Path Parameters

Parameter Name	Required	Type	Explanation
leaveId	Yes	Integer	Leave request unique identifier

Query Parameters

Parameter Name	Required	Type	Explanation
rejectReason	No	String	Reason for rejection

Response Example

{
  "success": true,
  "statusCode": 200,
  "data": {
    "leaveId": 2001,
    "employeeId": 2046765589981163521,
    "employeeName": "Jane Doe",
    "leaveType": "1",
    "fromDateTime": "2026-04-25 09:00",
    "toDateTime": "2026-04-27 18:00",
    "notes": "Family vacation",
    "totalDays": 3,
    "status": 4,
    "approverId": 2046765589981163500,
    "approverName": "Admin User",
    "createDate": "2026-04-22T10:00:00",
    "updatedDate": "2026-04-22T15:00:00"
  }
}

---

5.7 Delete Leave Request

Brief Description: Delete a leave request record

Request URL: /hr/v1/leave-requests/{leaveId}

Is Certification Required? Yes

Request Method: DELETE

Scope: leaveRequest:admin

Path Parameters

Parameter Name	Required	Type	Explanation
leaveId	Yes	Integer	Leave request unique identifier

Response Example

{
  "success": true,
  "statusCode": 200
}

---

6. Position Management APIs

Authentication Required: All endpoints require a valid OAuth 2.0 access token in the Authorization header.

6.1 Get Position List

Brief Description: Retrieve a paginated list of positions

Request URL: /hr/v1/positions

Is Certification Required? Yes

Request Method: GET

Scope: position:read

Request Parameters

Parameter Name	Required	Type	Explanation
page	No	Integer	Page number (default: 1)
size	No	Integer	Page size (max: 100, default: 20)

Response Example

{
  "success": true,
  "statusCode": 200,
  "data": [
    {
      "positionId": 1,
      "positionCode": "ENG-001",
      "positionName": "Software Engineer",
      "responsibilities": "Develop and maintain software systems",
      "minimumSalary": 50000.0,
      "maximumSalary": 100000.0,
      "currency": "AUD",
      "remarks": "Remote work available",
      "createdDate": "2026-01-01T10:00:00",
      "updatedDate": "2026-01-01T10:00:00"
    }
  ],
  "pagination": {
    "currentPage": 1,
    "pageSize": 20,
    "totalItems": 1,
    "totalPages": 1,
    "hasNextPage": false,
    "hasPreviousPage": false
  }
}

---

6.2 Create Position

Brief Description: Create a new position record in the system

Request URL: /hr/v1/positions

Is Certification Required? Yes

Request Method: POST

Scope: position:write

Request Parameters

Parameter Name	Type	Required	Explanation
positionCode	String	No	Position code (max 50 chars)
positionName	String	Yes	Position name (max 100 chars)
responsibilities	String	Yes	Job responsibilities (max 2000 chars)
minimumSalary	Decimal	No	Minimum salary (≥ 0)
maximumSalary	Decimal	No	Maximum salary (≥ 0)
currency	String	No	Currency code (e.g. AUD)
remarks	String	No	Additional remarks (max 500 chars)

Request Example

{
  "positionCode": "ENG-001",
  "positionName": "Software Engineer",
  "responsibilities": "Develop and maintain software systems",
  "minimumSalary": 50000.0,
  "maximumSalary": 100000.0,
  "currency": "AUD",
  "remarks": "Remote work available"
}

Response Example

{
  "success": true,
  "statusCode": 201,
  "data": {
    "positionId": 1,
    "positionCode": "ENG-001",
    "positionName": "Software Engineer",
    "responsibilities": "Develop and maintain software systems",
    "minimumSalary": 50000.0,
    "maximumSalary": 100000.0,
    "currency": "AUD",
    "remarks": "Remote work available",
    "createdDate": "2026-04-24T10:00:00",
    "updatedDate": "2026-04-24T10:00:00"
  }
}

---

6.3 Get Position Details

Brief Description: Retrieve detailed information for a specific position

Request URL: /hr/v1/positions/{positionId}

Is Certification Required? Yes

Request Method: GET

Scope: position:read

Path Parameters

Parameter Name	Required	Type	Explanation
positionId	Yes	Integer	Position unique identifier

Response Example

{
  "success": true,
  "statusCode": 200,
  "data": {
    "positionId": 1,
    "positionCode": "ENG-001",
    "positionName": "Software Engineer",
    "responsibilities": "Develop and maintain software systems",
    "minimumSalary": 50000.0,
    "maximumSalary": 100000.0,
    "currency": "AUD",
    "remarks": "Remote work available",
    "createdDate": "2026-01-01T10:00:00",
    "updatedDate": "2026-01-01T10:00:00"
  }
}

---

6.4 Update Position

Brief Description: Update position information. Returns the complete updated position record.

Request URL: /hr/v1/positions/{positionId}

Is Certification Required? Yes

Request Method: PUT

Scope: position:write

Path Parameters

Parameter Name	Required	Type	Explanation
positionId	Yes	Integer	Position unique identifier

Request Parameters

Same fields as Create Position — include only the fields to update.

Response Example

{
  "success": true,
  "statusCode": 200,
  "data": {
    "positionId": 1,
    "positionCode": "ENG-001",
    "positionName": "Senior Software Engineer",
    "responsibilities": "Lead development and code reviews",
    "minimumSalary": 70000.0,
    "maximumSalary": 120000.0,
    "currency": "AUD",
    "remarks": "Hybrid work model",
    "createdDate": "2026-01-01T10:00:00",
    "updatedDate": "2026-04-24T14:00:00"
  }
}

---

6.5 Delete Position

Brief Description: Delete a position record

Request URL: /hr/v1/positions/{positionId}

Is Certification Required? Yes

Request Method: DELETE

Scope: position:admin

Path Parameters

Parameter Name	Required	Type	Explanation
positionId	Yes	Integer	Position unique identifier

Response Example

{
  "success": true,
  "statusCode": 200
}

---

7. Job Listings APIs

Authentication Required: All endpoints require a valid OAuth 2.0 access token in the Authorization header.

7.1 Get Job Listings List

Brief Description: Retrieve a paginated list of job listings

Request URL: /hr/v1/job-listings

Is Certification Required? Yes

Request Method: GET

Scope: jobListings:read

Request Parameters

Parameter Name	Required	Type	Explanation
page	No	Integer	Page number (default: 1)
size	No	Integer	Page size (max: 100, default: 20)
status	No	Integer	0=Discontinued, 1=Published

Response Example

{
  "success": true,
  "statusCode": 200,
  "data": [
    {
      "id": "abc123",
      "title": "Senior Software Engineer",
      "employmentType": 3,
      "location": "Sydney, NSW",
      "currency": "AUD",
      "payMin": 80000,
      "payMax": 120000,
      "salaryType": 5,
      "payType": 2,
      "showPay": true,
      "status": 1
    }
  ],
  "pagination": {
    "currentPage": 1,
    "pageSize": 20,
    "totalItems": 1,
    "totalPages": 1,
    "hasNextPage": false,
    "hasPreviousPage": false
  }
}

---

7.2 Create Job Listing

Brief Description: Create a new job listing record in the system

Request URL: /hr/v1/job-listings

Is Certification Required? Yes

Request Method: POST

Scope: jobListings:write

Request Parameters

Parameter Name	Type	Required	Explanation
title	String	Yes	Job listing title (max 200 chars)
employmentType	Integer	Yes	1=Casual, 2=Part time, 3=Full time
contentBody	String	No	Job description content
contentFormatting	String	No	Content format: text or html
location	String	No	Job location (max 200 chars)
currency	String	No	Pay currency (max 10 chars)
payMin	Decimal	No	Minimum pay amount (≥ 0)
payMax	Decimal	No	Maximum pay amount (≥ 0)
salaryType	Integer	No	1=hourly, 2=daily, 3=weekly, 4=monthly, 5=annual
payType	Integer	No	1=Exact amount, 2=Pay range
showPay	Boolean	No	Whether to show pay on listing
showExperience	Integer	No	0=no requirement, other=years of experience
status	Integer	No	0=Discontinued, 1=Published
questions	Array	No	Screening questions (see Question Object below)

Question Object Fields:

Parameter Name	Type	Required	Explanation
questionMsg	String	Yes	Question text (max 500 chars)
questionType	Integer	Yes	1=Short answer, 2=Yes/No, 3=Single select
answerOptions	String	No	Comma-separated options (for Single select type)
isAnswerVideo	Boolean	No	Whether video answer is required
questionIndex	Integer	No	Question display order index

Request Example

{
  "title": "Senior Software Engineer",
  "employmentType": 3,
  "contentBody": "We are looking for...",
  "contentFormatting": "html",
  "location": "Sydney, NSW",
  "currency": "AUD",
  "payMin": 80000,
  "payMax": 120000,
  "salaryType": 5,
  "payType": 2,
  "showPay": true,
  "showExperience": 3,
  "status": 1,
  "questions": [
    {
      "questionMsg": "What is your expected salary?",
      "questionType": 1,
      "isAnswerVideo": false,
      "questionIndex": 1
    }
  ]
}

Response Example

{
  "code": 201,
  "msg": "Job listing created successfully",
  "data": {
    "id": "abc123",
    "title": "Senior Software Engineer",
    "employmentType": 3,
    "location": "Sydney, NSW",
    "currency": "AUD",
    "payMin": 80000,
    "payMax": 120000,
    "salaryType": 5,
    "payType": 2,
    "showPay": true,
    "status": 1,
    "questions": []
  }
}

---

7.3 Get Job Listing Details

Brief Description: Retrieve detailed information for a specific job listing

Request URL: /hr/v1/job-listings/{id}

Is Certification Required? Yes

Request Method: GET

Scope: jobListings:read

Path Parameters

Parameter Name	Required	Type	Explanation
id	Yes	String	Job listing unique identifier

Response Example

{
  "success": true,
  "statusCode": 200,
  "data": {
    "id": "abc123",
    "title": "Senior Software Engineer",
    "employmentType": 3,
    "contentBody": "We are looking for...",
    "contentFormatting": "html",
    "location": "Sydney, NSW",
    "currency": "AUD",
    "payMin": 80000,
    "payMax": 120000,
    "salaryType": 5,
    "payType": 2,
    "showPay": true,
    "showExperience": 3,
    "status": 1,
    "questions": []
  }
}

---

7.4 Update Job Listing

Brief Description: Update job listing information. Returns the complete updated job listing record.

Request URL: /hr/v1/job-listings/{id}

Is Certification Required? Yes

Request Method: PUT

Scope: jobListings:write

Path Parameters

Parameter Name	Required	Type	Explanation
id	Yes	String	Job listing unique identifier

Request Parameters

Same fields as Create Job Listing — include only the fields to update. Question objects require the id field (UUID) for updates.

Response Example

{
  "success": true,
  "statusCode": 200,
  "data": {
    "id": "abc123",
    "title": "Senior Software Engineer (Updated)",
    "employmentType": 3,
    "status": 1
  }
}

---

7.5 Delete Job Listing

Brief Description: Delete a job listing record

Request URL: /hr/v1/job-listings/{id}

Is Certification Required? Yes

Request Method: DELETE

Scope: jobListings:admin

Path Parameters

Parameter Name	Required	Type	Explanation
id	Yes	String	Job listing unique identifier

Response Example

{
  "success": true,
  "statusCode": 200
}

---

8. Holiday Entitlements APIs

Authentication Required: All endpoints require a valid OAuth 2.0 access token in the Authorization header.

8.1 Get Holiday Entitlements List

Brief Description: Retrieve a paginated list of holiday entitlements for an employee

Request URL: /hr/v1/holidays

Is Certification Required? Yes

Request Method: GET

Scope: holidays:read

Request Parameters

Parameter Name	Required	Type	Explanation
page	No	Integer	Page number (default: 1)
size	No	Integer	Page size (max: 100, default: 20)

Response Example

{
  "success": true,
  "statusCode": 200,
  "data": [
    {
      "empleHolidayId": 1,
      "employeeId": 123456789,
      "holidayName": "Annual Leave",
      "holidayType": "1",
      "fromDate": "2026-01-01",
      "toDate": "2026-12-31",
      "createdDate": "2026-04-27T10:00:00",
      "updatedDate": "2026-04-27T10:00:00"
    }
  ],
  "pagination": {
    "currentPage": 1,
    "pageSize": 20,
    "totalItems": 1,
    "totalPages": 1,
    "hasNextPage": false,
    "hasPreviousPage": false
  }
}

---

8.2 Create Holiday Entitlement

Brief Description: Create a new holiday entitlement record for an employee

Request URL: /hr/v1/holidays

Is Certification Required? Yes

Request Method: POST

Scope: holiday:write

Request Parameters

Parameter Name	Type	Required	Explanation
employeeId	Long	Yes	Employee ID from HR Tool
holidayName	String	Yes	Holiday entitlement name (max 100 chars)
holidayType	String	Yes	1=Public Holidays, 2=Private Holidays, 3=Company Holidays
fromDate	String	Yes	Start date (YYYY-MM-DD)
toDate	String	Yes	End date (YYYY-MM-DD)

Request Example

{
  "employeeId": 123456789,
  "holidayName": "Annual Leave",
  "holidayType": "1",
  "fromDate": "2026-01-01",
  "toDate": "2026-12-31"
}

Response Example

{
  "success": true,
  "statusCode": 201,
  "data": {
    "empleHolidayId": 1,
    "employeeId": 123456789,
    "holidayName": "Annual Leave",
    "holidayType": "1",
    "fromDate": "2026-01-01",
    "toDate": "2026-12-31",
    "createdDate": "2026-04-27T10:00:00",
    "updatedDate": "2026-04-27T10:00:00"
  }
}

---

8.3 Get Holiday Entitlement Details

Brief Description: Retrieve detailed information for a specific holiday entitlement

Request URL: /hr/v1/holidays/{id}

Is Certification Required? Yes

Request Method: GET

Scope: holiday:read

Path Parameters

Parameter Name	Required	Type	Explanation
id	Yes	Integer	Holiday entitlement unique identifier

Response Example

{
  "success": true,
  "statusCode": 200,
  "data": {
    "empleHolidayId": 1,
    "employeeId": 123456789,
    "holidayName": "Annual Leave",
    "holidayType": "1",
    "fromDate": "2026-01-01",
    "toDate": "2026-12-31",
    "createdDate": "2026-04-27T10:00:00",
    "updatedDate": "2026-04-27T10:00:00"
  }
}

---

8.4 Update Holiday Entitlement

Brief Description: Update holiday entitlement information. Returns the complete updated record.

Request URL: /hr/v1/holidays/{id}

Is Certification Required? Yes

Request Method: PUT

Scope: holiday:write

Path Parameters

Parameter Name	Required	Type	Explanation
id	Yes	Integer	Holiday entitlement unique identifier

Request Parameters

Same fields as Create Holiday Entitlement — include only the fields to update.

Response Example

{
  "success": true,
  "statusCode": 200,
  "data": {
    "empleHolidayId": 1,
    "employeeId": 123456789,
    "holidayName": "Annual Leave",
    "holidayType": "1",
    "fromDate": "2026-01-01",
    "toDate": "2026-12-31",
    "createdDate": "2026-04-27T10:00:00",
    "updatedDate": "2026-04-27T10:00:00"
  }
}

---

8.5 Delete Holiday Entitlement

Brief Description: Delete a holiday entitlement record

Request URL: /hr/v1/holidays/{id}

Is Certification Required? Yes

Request Method: DELETE

Scope: holiday:admin

Path Parameters

Parameter Name	Required	Type	Explanation
id	Yes	Integer	Holiday entitlement unique identifier

Response Example

{
  "success": true,
  "statusCode": 200
}

---

9. Department Management APIs

Authentication Required: All endpoints require a valid OAuth 2.0 access token in the Authorization header.

9.1 Get Department List

Brief Description: Retrieve a paginated list of departments

Request URL: /hr/v1/departments

Is Certification Required? Yes

Request Method: GET

Scope: department:read

Request Parameters

Parameter Name	Required	Type	Explanation
page	No	Integer	Page number (default: 1)
size	No	Integer	Page size (max: 100, default: 20)

Response Example

{
  "success": true,
  "statusCode": 200,
  "data": [
    {
      "deptId": 1,
      "deptName": "Engineering",
      "orderNum": 1,
      "leader": 1001,
      "leaderName": "John Smith",
      "status": "0",
      "empNum": 15
    }
  ],
  "pagination": {
    "currentPage": 1,
    "pageSize": 20,
    "totalItems": 5,
    "totalPages": 1,
    "hasNextPage": false,
    "hasPreviousPage": false
  }
}

---

9.2 Create Department

Brief Description: Create a new department in the system

Request URL: /hr/v1/departments

Is Certification Required? Yes

Request Method: POST

Scope: department:write

Request Parameters

Parameter Name	Required	Type	Explanation
deptName	Yes	String	Department name
leader	Yes	Integer	Employee ID of department leader
orderNum	No	Integer	Display order number
status	No	String	0=Active
description	No	String	Department description
employeeIds	No	Array	List of employee IDs to assign

Request Example

{
  "deptName": "Engineering",
  "leader": 1001,
  "orderNum": 1,
  "status": "0",
  "description": "Responsible for software development",
  "employeeIds": [1001, 1002, 1003]
}

Response Example

{
  "success": true,
  "statusCode": 201,
  "data": {
    "deptId": 1,
    "deptName": "Engineering",
    "leader": 1001,
    "status": "0"
  }
}

---

9.3 Get Department Details

Brief Description: Retrieve detailed information for a specific department

Request URL: /hr/v1/departments/{deptId}

Is Certification Required? Yes

Request Method: GET

Scope: department:read

Path Parameters

Parameter Name	Required	Type	Explanation
deptId	Yes	Integer	Department unique identifier

---

9.4 Update Department

Brief Description: Update department information

Request URL: /hr/v1/departments/{deptId}

Is Certification Required? Yes

Request Method: PUT

Scope: department:write

Path Parameters

Parameter Name	Required	Type	Explanation
deptId	Yes	Integer	Department unique identifier

Request Parameters

Fields: deptName, orderNum, leader, status, description, employeeIds (replaces existing employee list).

---

9.5 Delete Department

Brief Description: Delete a department record

Request URL: /hr/v1/departments/{deptId}

Is Certification Required? Yes

Request Method: DELETE

Scope: department:admin

Path Parameters

Parameter Name	Required	Type	Explanation
deptId	Yes	Integer	Department unique identifier

Response Example

{
  "success": true,
  "statusCode": 200
}

---

10. Role Management APIs

Authentication Required: All endpoints require a valid OAuth 2.0 access token in the Authorization header.

10.1 Get Role List

Brief Description: Retrieve a paginated list of roles

Request URL: /hr/v1/roles

Is Certification Required? Yes

Request Method: GET

Scope: role:read

Request Parameters

Parameter Name	Required	Type	Explanation
page	No	Integer	Page number (default: 1)
size	No	Integer	Page size (max: 100, default: 20)

Response Example

{
  "success": true,
  "statusCode": 200,
  "data": [
    {
      "roleId": 1,
      "roleName": "HR Manager",
      "roleKey": "hr_manager",
      "status": "0",
      "menuIds": [1, 2, 3],
      "roleSort": 1,
      "createdDate": "2025-01-01T00:00:00",
      "updatedDate": "2025-06-01T00:00:00"
    }
  ],
  "pagination": {
    "currentPage": 1,
    "pageSize": 20,
    "totalItems": 1,
    "totalPages": 1,
    "hasNextPage": false,
    "hasPreviousPage": false
  }
}

---

10.2 Create Role

Brief Description: Create a new role record

Request URL: /hr/v1/roles

Is Certification Required? Yes

Request Method: POST

Scope: role:write

Request Parameters

Parameter Name	Required	Type	Explanation
roleName	Yes	String	Role name
roleKey	Yes	String	Role key identifier
status	No	String	0=Normal, 1=Disabled
menuIds	No	Array	List of menu permission IDs
remarks	No	String	Additional remarks

Request Example

{
  "roleName": "HR Manager",
  "roleKey": "hr_manager",
  "status": "0",
  "menuIds": [1, 2, 3],
  "remarks": "HR management role"
}

Response Example

{
  "success": true,
  "statusCode": 201,
  "data": {
    "roleId": 1,
    "roleName": "HR Manager",
    "roleKey": "hr_manager",
    "status": "0"
  }
}

---

10.3 Get Role Details

Brief Description: Retrieve detailed information for a specific role

Request URL: /hr/v1/roles/{roleId}

Is Certification Required? Yes

Request Method: GET

Scope: role:read

Path Parameters

Parameter Name	Required	Type	Explanation
roleId	Yes	Integer	Role unique identifier

---

10.4 Update Role

Brief Description: Update role information

Request URL: /hr/v1/roles/{roleId}

Is Certification Required? Yes

Request Method: PUT

Scope: role:write

Path Parameters

Parameter Name	Required	Type	Explanation
roleId	Yes	Integer	Role unique identifier

Request Parameters

Fields: roleName, roleKey, status (0=Normal, 1=Disabled), menuIds, remarks.

---

10.5 Delete Role

Brief Description: Delete a role record

Request URL: /hr/v1/roles/{roleId}

Is Certification Required? Yes

Request Method: DELETE

Scope: role:admin

Path Parameters

Parameter Name	Required	Type	Explanation
roleId	Yes	Integer	Role unique identifier

Response Example

{
  "success": true,
  "statusCode": 200
}

---

11. Policy Management APIs

Authentication Required: All endpoints require a valid OAuth 2.0 access token in the Authorization header.

11.1 Get Policy List

Brief Description: Retrieve a paginated list of policies

Request URL: /hr/v1/policies

Is Certification Required? Yes

Request Method: GET

Scope: policy:read

Request Parameters

Parameter Name	Required	Type	Explanation
page	No	Integer	Page number (default: 1)
size	No	Integer	Page size (max: 100, default: 20)

---

11.2 Create Policy

Brief Description: Create a new policy. Supports both JSON body and multipart/form-data (with file upload).

Request URL: /hr/v1/policies

Is Certification Required? Yes

Request Method: POST

Scope: policy:write

Request Parameters

Parameter Name	Required	Type	Explanation
title	Yes	String	Policy title
audience	No	String	1=Global, 2=Department, 3=Specific employees
deptIds	No	Array	Department IDs (when audience = 2)
employeeIds	No	Array	Employee IDs (when audience = 3)
attachmentUrl	No	String	URL to policy document
effectiveDate	No	String	Effective date (YYYY-MM-DD)
acknowledgementDeadline	No	String	Acknowledgement deadline (YYYY-MM-DD)
mandatoryAcknowledgement	No	Boolean	Whether acknowledgement is mandatory
resetAcknowledgement	No	Boolean	Whether to reset acknowledgement

Note: For multipart upload, pass the file as a form-data field and other fields as query parameters.

Request Example

{
  "title": "Code of Conduct Policy",
  "audience": "1",
  "deptIds": [1, 2, 3],
  "employeeIds": [100, 101, 102],
  "attachmentUrl": "https://minio.example.com/bucket/policy.pdf",
  "effectiveDate": "2026-01-01",
  "acknowledgementDeadline": "2026-12-31",
  "mandatoryAcknowledgement": true,
  "resetAcknowledgement": false
}

Response Example

{
  "success": true,
  "statusCode": 201,
  "data": {
    "policyId": 1,
    "title": "Code of Conduct Policy",
    "status": "DRAFT",
    "audience": "1",
    "audienceLabel": "Global",
    "mandatoryAcknowledgement": true
  }
}

---

11.3 Get Policy Details

Brief Description: Retrieve policy details by ID

Request URL: /hr/v1/policies/{policyId}

Is Certification Required? Yes

Request Method: GET

Scope: policy:read

Path Parameters

Parameter Name	Required	Type	Explanation
policyId	Yes	Integer	Policy unique identifier

---

11.4 Update Policy

Brief Description: Update policy via JSON body or multipart/form-data

Request URL: /hr/v1/policies/{policyId}

Is Certification Required? Yes

Request Method: PUT

Scope: policy:write

Path Parameters

Parameter Name	Required	Type	Explanation
policyId	Yes	Integer	Policy unique identifier

Request Parameters

Fields: title, audience, deptIds, employeeIds, attachmentUrl, effectiveDate, acknowledgementDeadline, mandatoryAcknowledgement, resetAcknowledgement, status (DRAFT/ACTIVE/ARCHIVED).

---

11.5 Archive Policy

Brief Description: Change policy status to ARCHIVED

Request URL: /hr/v1/policies/{policyId}/archived

Is Certification Required? Yes

Request Method: POST

Scope: policy:write

Path Parameters

Parameter Name	Required	Type	Explanation
policyId	Yes	Integer	Policy unique identifier

Response Example

{
  "success": true,
  "statusCode": 200
}

---

11.6 Delete Policy

Brief Description: Delete a policy and all its assignments

Request URL: /hr/v1/policies/{policyId}

Is Certification Required? Yes

Request Method: DELETE

Scope: policy:admin

Path Parameters

Parameter Name	Required	Type	Explanation
policyId	Yes	Integer	Policy unique identifier

Response Example

{
  "success": true,
  "statusCode": 200
}

---

12. Document Management APIs

Authentication Required: All endpoints require a valid OAuth 2.0 access token in the Authorization header.

12.1 Get Document List

Brief Description: Retrieve a paginated list of documents

Request URL: /hr/v1/documents

Is Certification Required? Yes

Request Method: GET

Scope: document:read

Request Parameters

Parameter Name	Required	Type	Explanation
page	No	Integer	Page number (default: 1)
size	No	Integer	Page size (max: 100, default: 20)

---

12.2 Create Document

Brief Description: Create a new document. Supports JSON body or multipart/form-data.

Request URL: /hr/v1/documents

Is Certification Required? Yes

Request Method: POST

Scope: document:write

Request Parameters

Parameter Name	Required	Type	Explanation
employeeId	Yes	Long	Employee ID from HR Tool
documentName	Yes	String	Document name
fileUrl	No	String	External temporary file URL — server will download and upload to MinIO. Takes priority over filePath.
description	No	String	Document description
status	No	String	0=Disabled, 1=Enabled
externalId	No	String	External system identifier
invitees	No	Array	Shared invitees — each object includes sharedToEmployeeId and permissionType (1=READ, 2=DOWNLOAD)

Request Example

{
  "employeeId": 1642343324555,
  "documentName": "Employment Contract",
  "fileUrl": "https://storage.example.com/contract.pdf",
  "description": "Annual employment contract",
  "status": "1",
  "externalId": "4234",
  "invitees": [
    { "sharedToEmployeeId": 123, "permissionType": "2" }
  ]
}

---

12.3 Get Document Details

Brief Description: Retrieve document with full invitee list

Request URL: /hr/v1/documents/{documentId}

Is Certification Required? Yes

Request Method: GET

Scope: document:read

Path Parameters

Parameter Name	Required	Type	Explanation
documentId	Yes	Long	Document unique identifier

---

12.4 Update Document

Brief Description: Update document information

Request URL: /hr/v1/documents/{documentId}

Is Certification Required? Yes

Request Method: PUT

Scope: document:write

Path Parameters

Parameter Name	Required	Type	Explanation
documentId	Yes	Long	Document unique identifier

Request Parameters

Fields: documentName, fileUrl, description, status, invitees.

---

12.5 Delete Document

Brief Description: Delete a document record and all its shares

Request URL: /hr/v1/documents/{documentId}

Is Certification Required? Yes

Request Method: DELETE

Scope: document:admin

Path Parameters

Parameter Name	Required	Type	Explanation
documentId	Yes	Long	Document unique identifier

Response Example

{
  "success": true,
  "statusCode": 200
}

---

13. Employee Contract APIs

Authentication Required: All endpoints require a valid OAuth 2.0 access token in the Authorization header.

13.1 Get Contract List

Brief Description: Retrieve a paginated list of employee contracts

Request URL: /hr/v1/contracts

Is Certification Required? Yes

Request Method: GET

Scope: contract:read

Request Parameters

Parameter Name	Required	Type	Explanation
page	No	Integer	Page number (default: 1)
size	No	Integer	Page size (max: 100, default: 20)

---

13.2 Get Expired Contracts

Brief Description: Retrieve a paginated list of expired contracts

Request URL: /hr/v1/contracts/expired

Is Certification Required? Yes

Request Method: GET

Scope: contract:read

Request Parameters

Parameter Name	Required	Type	Explanation
page	No	Integer	Page number (default: 1)
size	No	Integer	Page size (max: 100, default: 20)

---

13.3 Create Contract

Brief Description: Create a new employee contract

Request URL: /hr/v1/contracts

Is Certification Required? Yes

Request Method: POST

Scope: contract:write

Request Parameters

Parameter Name	Required	Type	Explanation
employeeId	Yes	Long	Employee ID from HR Tool
contractStartTime	Yes	String	Contract start date/time (yyyy-MM-ddTHH:mm:ss)
contractEndTime	Yes	String	Contract end date/time (yyyy-MM-ddTHH:mm:ss)
templateId	No	Integer	Contract template ID
position	No	String	Employee position/title
contractName	No	String	Contract name/reference
contractType	No	String	1=Paper, 2=Electronic
accessory	No	String	URL to attached contract document
isRenewal	No	String	1=No, 2=Yes

Request Example

{
  "employeeId": 1001,
  "templateId": 5,
  "position": "Engineer",
  "contractName": "EMP-2026-001",
  "contractType": "2",
  "contractStartTime": "2026-01-01T00:00:00",
  "contractEndTime": "2027-01-01T00:00:00",
  "accessory": "https://storage.example.com/contract.pdf",
  "isRenewal": "1"
}

---

13.4 Get Contract by ID

Brief Description: Retrieve a specific employee contract

Request URL: /hr/v1/contracts/{id}

Is Certification Required? Yes

Request Method: GET

Scope: contract:read

Path Parameters

Parameter Name	Required	Type	Explanation
id	Yes	Long	Contract unique identifier

---

13.5 Update Contract

Brief Description: Update an employee contract

Request URL: /hr/v1/contracts/{id}

Is Certification Required? Yes

Request Method: PUT

Scope: contract:write

Path Parameters

Parameter Name	Required	Type	Explanation
id	Yes	Long	Contract unique identifier

Request Parameters

Fields: templateId, position, contractName, contractType, contractStartTime, contractEndTime, signStatus (1=Pending, 2=Signed), isMaturity (0=No, 1=Yes), accessory, signDate.

---

13.6 Renew Contract

Brief Description: Creates a new contract as a renewal of the specified contract

Request URL: /hr/v1/contracts/{id}/renew

Is Certification Required? Yes

Request Method: POST

Scope: contract:write

Path Parameters

Parameter Name	Required	Type	Explanation
id	Yes	Long	Contract unique identifier

Request Parameters

Parameter Name	Required	Type	Explanation
templateId	Yes	Integer	Contract template ID
contractStartTime	Yes	String	New contract start date/time
contractEndTime	Yes	String	New contract end date/time
contractType	No	String	1=Paper, 2=Electronic
accessory	No	String	URL to renewed contract document
isRenewal	No	String	1=No, 2=Yes

Request Example

{
  "templateId": 5,
  "contractType": "2",
  "contractStartTime": "2027-01-01T00:00:00",
  "contractEndTime": "2028-01-01T00:00:00",
  "accessory": "https://storage.example.com/renewed-contract.pdf",
  "isRenewal": "2"
}

---

13.7 Delete Contract

Brief Description: Delete an employee contract record

Request URL: /hr/v1/contracts/{id}

Is Certification Required? Yes

Request Method: DELETE

Scope: contract:admin

Path Parameters

Parameter Name	Required	Type	Explanation
id	Yes	Long	Contract unique identifier

Response Example

{
  "success": true,
  "statusCode": 200
}

---

14. Contract Template APIs

Authentication Required: All endpoints require a valid OAuth 2.0 access token in the Authorization header.

14.1 Get Template List

Brief Description: Retrieve a paginated list of contract templates

Request URL: /hr/v1/contracts/templates

Is Certification Required? Yes

Request Method: GET

Scope: contractTemplate:read

Request Parameters

Parameter Name	Required	Type	Explanation
page	No	Integer	Page number (default: 1)
size	No	Integer	Page size (max: 100, default: 20)

---

14.2 Create Template

Brief Description: Create a new contract template

Request URL: /hr/v1/contracts/templates

Is Certification Required? Yes

Request Method: POST

Scope: contractTemplate:write

Request Parameters

Parameter Name	Required	Type	Explanation
templateName	Yes	String	Template name
templateContent	No	String	Template content (HTML string)
status	No	String	0=Normal, 1=Deactivated

Request Example

{
  "templateName": "Standard Employment Contract",
  "templateContent": "<p>This agreement...</p>",
  "status": "0"
}

---

14.3 Get Template by ID

Brief Description: Retrieve a specific contract template

Request URL: /hr/v1/contracts/templates/{templateId}

Is Certification Required? Yes

Request Method: GET

Scope: contractTemplate:read

Path Parameters

Parameter Name	Required	Type	Explanation
templateId	Yes	Integer	Template unique identifier

---

14.4 Update Template

Brief Description: Update a contract template

Request URL: /hr/v1/contracts/templates/{templateId}

Is Certification Required? Yes

Request Method: PUT

Scope: contractTemplate:write

Path Parameters

Parameter Name	Required	Type	Explanation
templateId	Yes	Integer	Template unique identifier

Request Parameters

Fields: templateName (required), templateContent (HTML string), status (0=Normal, 1=Deactivated).

---

14.5 Delete Template

Brief Description: Delete a contract template record

Request URL: /hr/v1/contracts/templates/{templateId}

Is Certification Required? Yes

Request Method: DELETE

Scope: contractTemplate:admin

Path Parameters

Parameter Name	Required	Type	Explanation
templateId	Yes	Integer	Template unique identifier

Response Example

{
  "success": true,
  "statusCode": 200
}

---

15. Company Settings APIs

Authentication Required: All endpoints require a valid OAuth 2.0 access token in the Authorization header.

15.1 Get Company Settings

Brief Description: Retrieve company settings including security and working hours

Request URL: /hr/v1/company-settings

Is Certification Required? Yes

Request Method: GET

Scope: companySettings:read

Response Example

{
  "success": true,
  "statusCode": 200,
  "data": {
    "enterpriseId": "ent_xxx",
    "securitySettings": {
      "minPasswordLength": 8,
      "requireNumbers": true,
      "requireUppercase": true,
      "requireSpecialChars": true,
      "enable2fa": false,
      "sessionTimeoutMinutes": 30,
      "maxFailedAttempts": 5
    },
    "workingHours": {
      "defaultStartTime": "09:00:00",
      "defaultEndTime": "18:00:00",
      "gracePeriod": 15,
      "enableOvertime": "1",
      "maximumOvertime": 120
    }
  }
}

---

15.2 Update Company Settings

Brief Description: Update company settings including security and working hours

Request URL: /hr/v1/company-settings

Is Certification Required? Yes

Request Method: PUT

Scope: companySettings:write

Request Parameters

Field	Type	Explanation
securitySettings.minPasswordLength	Integer	Minimum password length
securitySettings.requireNumbers	Boolean	Require numeric characters
securitySettings.requireUppercase	Boolean	Require uppercase characters
securitySettings.requireSpecialChars	Boolean	Require special characters
securitySettings.enable2fa	Boolean	Enable two-factor authentication
securitySettings.sessionTimeoutMinutes	Integer	Session timeout in minutes (5–480)
securitySettings.maxFailedAttempts	Integer	Max failed login attempts per hour
workingHours.defaultStartTime	String	Work start time (HH:mm:ss)
workingHours.defaultEndTime	String	Work end time (HH:mm:ss)
workingHours.gracePeriod	Integer	Grace period in minutes (0–60)
workingHours.enableOvertime	String	1=Yes, 2=No
workingHours.maximumOvertime	Integer	Maximum overtime in minutes

Request Example

{
  "securitySettings": {
    "minPasswordLength": 8,
    "requireNumbers": true,
    "requireUppercase": true,
    "requireSpecialChars": true,
    "enable2fa": false,
    "sessionTimeoutMinutes": 30,
    "maxFailedAttempts": 5
  },
  "workingHours": {
    "defaultStartTime": "09:00:00",
    "defaultEndTime": "18:00:00",
    "gracePeriod": 15,
    "enableOvertime": "1",
    "maximumOvertime": 120
  }
}

Response Example

{
  "success": true,
  "statusCode": 200
}

---

16. File Upload API

16.1 Upload File

Brief Description: Upload a file to MinIO storage. Returns file URL and metadata.

Request URL: /hr/v1/files

Is Certification Required? Yes

Request Method: POST

Scope: file:write

Content Type: multipart/form-data — pass the file in the file field (max size: 50MB)

Response Example

{
  "success": true,
  "statusCode": 200,
  "data": {
    "fileName": "document.pdf",
    "fileUrl": "https://minio.example.com/bucket/path/document.pdf",
    "fileSize": 102400,
    "fileType": "application/pdf"
  }
}

The returned fileUrl can be used as attachmentUrl when creating policies or as fileUrl when creating documents.

---

17. Menu Management APIs

Authentication Required: All endpoints require a valid OAuth 2.0 access token in the Authorization header.

17.1 Get Menu List

Brief Description: Retrieve a list of all menus

Request URL: /hr/v1/menus

Is Certification Required? Yes

Request Method: GET

Scope: role:read

---

17.2 Get Menu Tree

Brief Description: Retrieve the hierarchical menu tree structure

Request URL: /hr/v1/menus/tree

Is Certification Required? Yes

Request Method: GET

Scope: role:read

Response Example

{
  "success": true,
  "statusCode": 200,
  "data": [
    {
      "menuId": 1,
      "menuName": "Dashboard",
      "parentId": 0,
      "orderNum": 1,
      "path": "/dashboard",
      "menuType": "C",
      "visible": "0",
      "status": "0",
      "perms": "dashboard:list",
      "children": []
    }
  ]
}

Field	Values
menuType	M=Directory, C=Menu, F=Button
visible	0=Show, 1=Hide
status	0=Normal, 1=Disabled

---

17.3 Get Menu by ID

Brief Description: Retrieve a specific menu item

Request URL: /hr/v1/menus/{menuId}

Is Certification Required? Yes

Request Method: GET

Scope: role:read

Path Parameters

Parameter Name	Required	Type	Explanation
menuId	Yes	Integer	Menu unique identifier

---

18. Company Provision API

Note: This is an internal API for ShiftCare to auto-provision new HR company instances. It requires a client_credentials M2M token with company:admin scope. This API does not require the X-Enterprise-Id header.

18.1 Auto-Provision HR Company Instance

Brief Description: Creates a new HR company, initialises system roles, creates the initial admin account, and binds the ShiftCare credentials. Triggered by ShiftCare on trial creation or plan purchase with HR add-on.

Request URL: /hr/v1/companies/provision

Is Certification Required? Yes

Request Method: POST

Scope: company:admin (client_credentials M2M token only)

Request Parameters

Parameter Name	Required	Type	Explanation
companyName	Yes	String	Company name
contactEmail	Yes	String	Company contact email
adminFullName	Yes	String	Initial admin's full name
adminEmail	Yes	String	Initial admin's email
adminUsername	Yes	String	Initial admin's login username
industryType	No	String	Industry type (e.g. healthcare)
country	No	String	Country code (e.g. AU)
timeZone	No	String	Timezone (e.g. Australia/Sydney)
currency	No	String	Currency code (e.g. AUD)
phone	No	String	Company phone number
phoneCode	No	String	Phone country code (e.g. +61)
logoUrl	No	String	URL to company logo
planId	No	String	Plan identifier (e.g. trial)
encryptedApiCredentials	No	Object	Encrypted API credentials — includes iv and ciphertext

Request Example

{
  "companyName": "Acme Corp",
  "industryType": "healthcare",
  "country": "AU",
  "timeZone": "Australia/Sydney",
  "contactEmail": "admin@acme.com",
  "currency": "AUD",
  "phone": "0400000000",
  "phoneCode": "+61",
  "logoUrl": "https://cdn.shiftcare.com/logos/acme.png",
  "planId": "trial",
  "adminFullName": "John Smith",
  "adminEmail": "john@acme.com",
  "adminUsername": "john.smith",
  "encryptedApiCredentials": {
    "iv": "MXc3JZLahWmB+FSO",
    "ciphertext": "0KQlNzQ3Ufj+1cVSiZZ50C4IYbCdGOPTBOpCGBUFopR3fJ2ioouOz9mHHmLY27qc09Jk4MmP..."
  }
}

Response Example

{
  "enterpriseId": "1234567890123456789",
  "companyName": "Acme Corp",
  "createdFrom": "Shiftcare",
  "adminUsername": "john.smith",
  "adminEmail": "john@acme.com",
  "status": "provisioned",
  "createdAt": "2026-04-27T10:00:00Z"
}

Error Responses

HTTP Code	Description
400	Invalid request — validation errors
401	Unauthorized — invalid or expired token
403	Forbidden — insufficient scope or user JWT not allowed
409	Conflict — company with same email already exists
500	Internal server error

---

19. Emergency Contacts API

19.1 Get Emergency Contacts Report

Brief Description: Retrieve a paginated list of employee emergency contacts

Request URL: /hr/v1/reports/emergency-contacts

Is Certification Required? Yes

Request Method: GET

Scope: employee:read

Request Parameters

Parameter Name	Required	Type	Explanation
page	No	Integer	Page number (default: 1)
size	No	Integer	Page size (max: 100, default: 20)

Response Example

{
  "success": true,
  "statusCode": 200,
  "data": [
    {
      "employeeId": 2046765589981163521,
      "employeeName": "Jane Doe",
      "emergencyContactName": "John Doe",
      "emergencyContactPhone": "+61 412345678",
      "relationship": "Spouse"
    }
  ],
  "pagination": {
    "currentPage": 1,
    "pageSize": 20,
    "totalItems": 1,
    "totalPages": 1,
    "hasNextPage": false,
    "hasPreviousPage": false
  }
}

---

20. Error Handling

20.1 Standard Error Response

All error responses follow a consistent format:

{
  "success": false,
  "statusCode": 400,
  "errorMessage": "Missing required field: email"
}

20.2 HTTP Status Codes

Code	Status	Description
200	OK	Request succeeded
201	Created	Resource created successfully
400	Bad Request	Invalid request format or missing required fields
401	Unauthorized	Missing, invalid, or expired access token
403	Forbidden	Insufficient permissions for requested operation
404	Not Found	Resource not found
429	Too Many Requests	Rate limit exceeded (100 req/min per client)
500	Internal Server Error	Server error — contact support if persists

20.3 OAuth Error Codes

OAuth 2.0 token endpoint returns specific error codes per RFC 6749:

Error Code	Description
invalid_request	Malformed request (missing parameters, etc.)
invalid_client	Invalid client_id or client_secret
invalid_grant	Invalid or expired refresh_token
unauthorized_client	Client not authorized for this grant type
unsupported_grant_type	Grant type not supported

---

21. Rate Limiting & Security

21.1 Rate Limits

API requests are rate limited to ensure system stability:

Endpoint Type	Limit
OAuth Token Endpoint	10 requests per minute per IP address
General API Endpoints	100 requests per minute per client_id

Rate Limit Headers:

Response headers include rate limit information:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1702387200

When the rate limit is exceeded:

HTTP/1.1 429 Too Many Requests
Retry-After: 60

{
  "success": false,
  "statusCode": 429,
  "errorMessage": "API rate limit exceeded"
}

21.2 Security Requirements

• HTTPS Required: All API calls must use HTTPS (TLS 1.2 minimum)
• Token Storage: Store client_secret securely — never expose in client-side code
• Token Transmission: Only send tokens in the Authorization header, never in URL parameters
• Error Handling: Do not log sensitive information (tokens, secrets) in error messages

---

22. Integration Checklist

22.1 Pre-Integration

• Obtain OAuth 2.0 credentials (client_id and client_secret) from HR Tool
• Confirm external_id mapping strategy for employees
• Set up testing environment access

22.2 Implementation Tasks

• Implement OAuth 2.0 client credentials flow
• Implement token refresh logic with proper rotation
• Implement JWT signature verification using public keys
• Build employee sync logic (create, update, delete)
• Implement error handling and retry logic
• Handle rate limiting with exponential backoff

22.3 Testing Requirements

• Test OAuth token acquisition in testing environment
• Test token refresh and rotation
• Test employee CRUD operations
• Test error scenarios (invalid tokens, rate limits, etc.)
• Load testing to verify rate limits

22.4 Production Readiness

• Complete security review
• Set up monitoring and alerting
• Configure production credentials
• Document integration for internal teams
• Plan rollout and migration strategy

---

Appendix A: Quick Reference

A.1 Key Endpoints Summary

Method	Endpoint	Description
POST	/oauth2/token	Get access token
GET	/hr/v1/employees	List employees
POST	/hr/v1/employees	Create employee
GET	/hr/v1/employees/{id}	Get employee details
PUT	/hr/v1/employees/{id}	Update employee
DELETE	/hr/v1/employees/{id}	Delete employee
PUT	/hr/v1/employees/{id}/offboard	Offboard employee
PUT	/hr/v1/employees/{id}/restore	Restore employee
GET	/hr/v1/leave-types	List leave types
POST	/hr/v1/leave-types	Create leave type
GET	/hr/v1/leave-types/{id}	Get leave type details
PUT	/hr/v1/leave-types/{id}	Update leave type
DELETE	/hr/v1/leave-types/{id}	Delete leave type
GET	/hr/v1/leave-requests	List leave requests
POST	/hr/v1/leave-requests	Create leave request
GET	/hr/v1/leave-requests/{id}	Get leave request details
PUT	/hr/v1/leave-requests/{id}	Update leave request
POST	/hr/v1/leave-requests/{id}/approve	Approve leave request
POST	/hr/v1/leave-requests/{id}/reject	Reject leave request
DELETE	/hr/v1/leave-requests/{id}	Delete leave request
GET	/hr/v1/positions	List positions
POST	/hr/v1/positions	Create position
GET	/hr/v1/positions/{id}	Get position details
PUT	/hr/v1/positions/{id}	Update position
DELETE	/hr/v1/positions/{id}	Delete position
GET	/hr/v1/job-listings	List job listings
POST	/hr/v1/job-listings	Create job listing
GET	/hr/v1/job-listings/{id}	Get job listing details
PUT	/hr/v1/job-listings/{id}	Update job listing
DELETE	/hr/v1/job-listings/{id}	Delete job listing
GET	/hr/v1/holidays	List holiday entitlements
POST	/hr/v1/holidays	Create holiday entitlement
GET	/hr/v1/holidays/{id}	Get holiday entitlement details
PUT	/hr/v1/holidays/{id}	Update holiday entitlement
DELETE	/hr/v1/holidays/{id}	Delete holiday entitlement
GET	/hr/v1/departments	List departments
POST	/hr/v1/departments	Create department
GET	/hr/v1/departments/{deptId}	Get department details
PUT	/hr/v1/departments/{deptId}	Update department
DELETE	/hr/v1/departments/{deptId}	Delete department
GET	/hr/v1/roles	List roles
POST	/hr/v1/roles	Create role
GET	/hr/v1/roles/{roleId}	Get role details
PUT	/hr/v1/roles/{roleId}	Update role
DELETE	/hr/v1/roles/{roleId}	Delete role
GET	/hr/v1/policies	List policies
POST	/hr/v1/policies	Create policy
GET	/hr/v1/policies/{policyId}	Get policy details
PUT	/hr/v1/policies/{policyId}	Update policy
POST	/hr/v1/policies/{policyId}/archived	Archive policy
DELETE	/hr/v1/policies/{policyId}	Delete policy
GET	/hr/v1/documents	List documents
POST	/hr/v1/documents	Create document
GET	/hr/v1/documents/{documentId}	Get document details
PUT	/hr/v1/documents/{documentId}	Update document
DELETE	/hr/v1/documents/{documentId}	Delete document
GET	/hr/v1/contracts	List employee contracts
POST	/hr/v1/contracts	Create employee contract
GET	/hr/v1/contracts/expired	Get expired contracts
GET	/hr/v1/contracts/{id}	Get contract by ID
PUT	/hr/v1/contracts/{id}	Update contract
POST	/hr/v1/contracts/{id}/renew	Renew contract
DELETE	/hr/v1/contracts/{id}	Delete contract
GET	/hr/v1/contracts/templates	List contract templates
POST	/hr/v1/contracts/templates	Create contract template
GET	/hr/v1/contracts/templates/{templateId}	Get template by ID
PUT	/hr/v1/contracts/templates/{templateId}	Update template
DELETE	/hr/v1/contracts/templates/{templateId}	Delete template
GET	/hr/v1/company-settings	Get company settings
PUT	/hr/v1/company-settings	Update company settings
POST	/hr/v1/files	Upload file
GET	/hr/v1/menus	List menus
GET	/hr/v1/menus/tree	Get menu tree
GET	/hr/v1/menus/{menuId}	Get menu by ID
POST	/hr/v1/companies/provision	Auto-provision company instance
GET	/hr/v1/reports/emergency-contacts	Get emergency contacts report

A.2 Token Lifetimes

Token	Lifetime
Access Token	15 minutes