ClickxPayHR API Reference

All systems operational

ClickxPayHR API

Complete HR and payroll platform built for Ghana. 290 endpoints across 12 modules covering employee management, payroll processing with GRA tax and SSNIT calculations, leave, insurance, staffing, and multi-tenant operations.

The API uses standard REST conventions, returns JSON, and authenticates via JWT bearer tokens.

Quick facts

Version	2.0
Protocol	HTTPS only
Format	JSON request and response
Auth	JWT Bearer token
Rate limit	100 req/min per token

Base URL

https://api.clickxpayhr.com/api

Health check

$ curl https://api.clickxpayhr.com/health

{
  "success": true,
  "service": "clickxpayhr-api",
  "version": "2.0.0",
  "database": "connected"
}

Authentication

All API requests require a valid JWT token obtained by logging in with user credentials. The response includes an access token (8h expiry) and a refresh token.

Include the access token in every request header:

Authorization: Bearer <token>

Token refresh

When the access token expires, POST the refresh token to /api/auth/refresh to receive a new pair without re-authenticating.

Two-factor auth

If 2FA is enabled, login returns requires2FA: true. Complete authentication by verifying the TOTP code via /api/auth/2fa/verify.

Login request

POST /api/auth/login

{
  "email": "admin@company.com",
  "password": "••••••••",
  "portalType": "staff"
}

Response

{
  "success": true,
  "data": {
    "user": {
      "id": 1,
      "email": "admin@company.com",
      "companyId": 1
    },
    "session": {
      "accessToken": "eyJhbG...",
      "refreshToken": "d69ef...",
      "tokenType": "Bearer"
    }
  }
}

Employees

Full employee lifecycle management — onboarding, profile updates, document storage, financial details, status tracking, and pool management for staffing operations.

GET/employees	List with pagination and filters
POST/employees	Create new employee
GET/employees/:id	Full employee profile
PUT/employees/:id	Update profile fields
GET/employees/:id/finance	Bank and salary details
PUT/employees/:id/finance	Update financial info
GET/employees/:id/documents	List documents
POST/employees/:id/documents	Upload document
PUT/employees/:id/status	Change employment status

+ 36 more endpoints

Example: Create employee

POST /api/employees { "firstName": "Kwame", "lastName": "Mensah", "email": "kwame@acme.com", "phone": "+233201234567", "dateOfBirth": "1990-03-15", "hireDate": "2026-02-01", "jobTitle": "Accountant", "departmentId": 3, "ssnitNumber": "C/0012345678", "tinNumber": "P0012345678" }

Payroll

Process payroll with automatic GRA income tax calculation (2024 brackets) and SSNIT tier 1, 2, 3 contributions. Supports salary structures, allowances, deductions, and payslip generation.

POST/payroll/process	Run payroll for a period
GET/payroll/periods	List pay periods
GET/payroll/periods/:id	Period breakdown
GET/payroll/payslips/:id	Individual payslip
POST/payroll/approve	Approve payroll run
GET/payroll/tax/gra	Current GRA brackets
GET/payroll/ssnit/tiers	SSNIT tier rates

+ 31 more endpoints

Example: Process payroll

POST /api/payroll/process { "periodId": 12, "payDate": "2026-02-28" } // Response includes per-employee: // - Basic salary // - Allowances & deductions // - SSNIT employee (5.5%) // - SSNIT employer (13%) // - GRA income tax // - Net pay

Clients

Manage client companies, contacts, departments, and service agreements. Track employee assignments and billing rates per client.

GET/clients	List client companies
POST/clients	Register new client
GET/clients/:id	Client profile
PUT/clients/:id	Update client
GET/clients/:id/employees	Assigned employees
GET/clients/:id/billing	Billing overview

+ 26 more endpoints

Example: List clients

GET /api/clients?page=1&limit=20 { "success": true, "data": [ { "id": 1, "name": "Accra Mining Ltd", "industry": "Mining", "employeeCount": 142, "status": "active" } ], "pagination": { "total": 8 } }

Leave

Leave types, policies, request/approval workflows, balance tracking, and accruals. Supports annual, sick, maternity, and custom leave types.

GET/leave/requests	All leave requests
POST/leave/request	Submit request
PUT/leave/approve/:id	Approve or deny
GET/leave/balances/:id	Employee balances
GET/leave/types	Available leave types

+ 25 more endpoints

Example: Submit leave

POST /api/leave/request { "leaveTypeId": 1, "startDate": "2026-03-10", "endDate": "2026-03-14", "reason": "Family vacation" }

Allocations

Assign employees to client sites. Track billing rates, time, and manage transfers between clients.

GET/allocations	All allocations
POST/allocations	Create allocation
PUT/allocations/:id	Update
DEL/allocations/:id	End allocation

+ 24 more endpoints

Example: Allocate employee

POST /api/allocations { "employeeId": 42, "clientId": 3, "startDate": "2026-03-01", "billingRate": 2500.00, "jobTitle": "Site Engineer" }

Insurance

Manage insurance policies, employee enrollment, dependents, and coverage tracking.

GET/insurance/policies	List policies
POST/insurance/enroll	Enroll employee
GET/insurance/coverage/:id	Coverage details

+ 21 more endpoints

Also available

Staffing — 20 endpoints Job requisitions, candidate pools, skill matching, placement tracking. Reports — 22 endpoints Payroll summaries, headcount, SSNIT reports, GRA tax, custom exports. Audit — 18 endpoints Activity logs, change trails, compliance exports. Consent — 16 endpoints GDPR consent records, grants, revocations, expiry tracking. Admin — 25 endpoints Users, roles, permissions, settings, white-label branding config.