Create payroll run

POST/payroll/runs

Creates a new payroll run for the specified pay period. After creation, the run enters draft status while calculations are computed. Trigger the approval workflow once the run is verified and anomalies are resolved.

Request

Request body

Content type application/json (required).

Field	Type	Required	Description
name	string	Yes	Max length: 255
period_start	string (date)	Yes
period_end	string (date)	Yes
pay_date	string (date)	Yes
currency	string	No	Default: "GHS" · Max length: 3
notes	string	No

Example

{
  "name": "April 2026 Payroll",
  "period_start": "2026-04-01",
  "period_end": "2026-04-30",
  "pay_date": "2026-04-30",
  "currency": "GHS",
  "notes": "First run after Q1 salary review."
}

Responses

201 Payroll run created in draft status

Content type application/json, object · PayrollRunV1.

Field	Type	Required	Description
id	integer	No
name	string	No	Human-readable label for this run (e.g. "April 2026 Payroll").
period_start	string (date)	No
period_end	string (date)	No
pay_date	string (date)	No	Date on which employee payments are to be disbursed.
status	string	No	One of: "draft", "pending_approval", "approved", "paid", "cancelled"
employee_count	integer, nullable	No	Number of employees included in this run.
gross_total	number (float), nullable	No
net_total	number (float), nullable	No
currency	string	No	Max length: 3
notes	string, nullable	No
created_at	string (date-time)	No

422 Validation failed — check period dates or currency code

Example request

curl -X POST "https://{tenant}.faciotech.net/api/v1/payroll/runs" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"name": "April 2026 Payroll", "period_start": "2026-04-01", "period_end": "2026-04-30", "pay_date": "2026-04-30", "currency": "GHS", "notes": "First run after Q1 salary review."}'