Skip to main content

HR Tool - API Specification Document v3.0

Table of Contents​

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​

EnvironmentBase URL
Testinghttp://xz-ai.info:8197
Productionhttps://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​

HeaderValue
Content-Typeapplication/x-www-form-urlencoded

Request Parameters​

Parameter NameRequiredTypeExplanation
grant_typeYesStringMust be client_credentials
client_idYesStringYour application's client ID (provided by HR Tool)
client_secretYesStringYour application's client secret (provided by HR Tool)
scopeNoStringSpace-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 NameTypeExplanation
access_tokenStringJWT access token (valid for 15 minutes)
token_typeStringAlways "Bearer" — use in Authorization header
expires_inIntegerToken lifetime in seconds (900 = 15 minutes)
scopeStringGranted 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:

ClaimDescription
issIssuer (HR Tool)
subSubject (client_id)
audAudience (HR Tool API)
expExpiration time (Unix timestamp)
iatIssued at (Unix timestamp)
jtiJWT 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}
FieldDetails
LocationRequest Header
RequiredYES
DescriptionEnterprise unique ID in the HR system (multi-tenant isolation)
ErrorMissing or invalid value will return 400/403 Forbidden

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 NameRequiredTypeExplanation
pageNoIntegerPage number (default: 1)
sizeNoIntegerPage size (max: 100, default: 20)
statusNoInteger0 = 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 NameRequiredTypeExplanation
firstNameYesStringEmployee first name
lastNameYesStringEmployee last name
emailYesStringEmployee email address
phoneYesStringEmployee phone number
phoneCodeYesStringMobile phone country code (e.g. AU)
usernameYesStringLogin username
roleYesStringUser role — valid values: admin, hr, user
positionNoStringJob position/title
employmentTypeNoString1 = Full-Time, 2 = Part-Time, 3 = Internship
hiredOnNoStringHire date (YYYY-MM-DD)
externalIdNoStringExternal reference ID (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",
  "role": "admin",
  "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",
    "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 NameRequiredTypeExplanation
employeeIdYesIntegerEmployee 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"
  }
}

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 NameRequiredTypeExplanation
employeeIdYesIntegerEmployee 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",
    "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 NameRequiredTypeExplanation
employeeIdYesIntegerEmployee 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 NameRequiredTypeExplanation
employeeIdYesIntegerEmployee ID from HR Tool

Query Parameters​

Parameter NameRequiredTypeExplanation
resignationDateNoStringResignation date (YYYY-MM-DD)
reasonNoStringResignation 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 NameRequiredTypeExplanation
employeeIdYesIntegerEmployee 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. Additional API Scope​

The following modules and data fields are in scope for API integration. Each module requires corresponding ADD, EDIT, and DELETE API functions. Endpoint specifications for these modules will be published as development progresses.

4.1 Employees​

  • Employee full name
  • Login username
  • Phone number
  • Work phone number
  • Employment type
  • Address details
  • Email
  • Access level

4.2 Recruitment​

Job Listings:

  • Job listing title
  • Employment type
  • Job listing status
  • Content body
  • Content formatting
  • Experience
  • Location
  • Pay currency
  • Pay amount
  • Salary type
  • Pay type (Exact amount / Pay Range)
  • Screening questions

Departments:

  • Department name
  • Department head
  • Employee list
  • Description

4.3 Position Management​

  • Position code
  • Position name
  • Responsibilities
  • Minimum salary
  • Maximum salary
  • Currency
  • Additional remarks

4.4 Reports​

  • Details in HR Management
  • Emergency contacts

4.5 Settings​

Security Settings:

  • Password policy
  • Required numbers
  • Required uppercase letters

Authentication:

  • Enable two-factor authentication
  • Login session timeout
  • Max failed login attempts (per hour)

Working Hours:

  • Work start time
  • Work end time
  • Grace period (minutes)
  • Enable overtime
  • Maximum overtime

Menu Settings:

  • Horizontal toggle

4.6 Documents and Contracts​

  • Document file uploaded
  • Upload date
  • Shared status
  • Invitees assigned
  • Downloadable status

4.7 Policy Management​

  • Policy title
  • Uploaded policy document
  • Audience
  • Departments
  • Specific staff
  • Global flag
  • Effective date
  • Acknowledgement deadline
  • Mandatory acknowledgement flag
  • Reset acknowledgement flag

4.8 Labour Contract Management​

  • Template ID
  • Template name
  • Status (Normal / Deactivated)
  • Template content
  • Expired contract
  • Employee name
  • Position
  • Company name
  • Contract name
  • Expiration date
  • Sign type
  • Renewal
  • Actions

4.9 Roles and Permissions​

  • Role number
  • Role name
  • Status
  • Menu permissions

4.10 Holidays and Leave​

Leave Types:

  • Leave name
  • Entitlement (hours/year)
  • Accrual frequency
  • Reset date
  • Carry over policy
  • Carry over policy status
  • Paid leave status
  • Leave balance

Leave Requests:

  • Person who requested leave
  • From (date + hours)
  • To (date + hours)
  • Leave type
  • Leave request notes
  • Leaves requested
  • Approved leaves
  • Pending leaves
  • Rejected leaves

Leave Type Configuration:

  • Type of leave
  • Max days allowed
  • Paid leave status

Calendar / Holidays:

  • Holiday name
  • Holiday type
  • From date
  • To date

5. Error Handling​

5.1 Standard Error Response​

All error responses follow a consistent format:

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

5.2 HTTP Status Codes​

CodeStatusDescription
200OKRequest succeeded
201CreatedResource created successfully
400Bad RequestInvalid request format or missing required fields
401UnauthorizedMissing, invalid, or expired access token
403ForbiddenInsufficient permissions for requested operation
404Not FoundResource not found
429Too Many RequestsRate limit exceeded (100 req/min per client)
500Internal Server ErrorServer error — contact support if persists

5.3 OAuth Error Codes​

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

Error CodeDescription
invalid_requestMalformed request (missing parameters, etc.)
invalid_clientInvalid client_id or client_secret
invalid_grantInvalid or expired refresh_token
unauthorized_clientClient not authorized for this grant type
unsupported_grant_typeGrant type not supported

6. Rate Limiting & Security​

6.1 Rate Limits​

API requests are rate limited to ensure system stability:

Endpoint TypeLimit
OAuth Token Endpoint10 requests per minute per IP address
General API Endpoints100 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"
}

6.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

7. Integration Checklist​

7.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

7.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

7.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

7.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​

MethodEndpointDescription
POST/oauth2/tokenGet access token
GET/hr/v1/employeesList employees
POST/hr/v1/employeesCreate 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}/offboardOffboard employee
PUT/hr/v1/employees/{id}/restoreRestore employee

A.2 Token Lifetimes​

TokenLifetime
Access Token15 minutes