Payroll Runs
Payroll runs represent individual payroll processing cycles. Each run is linked to a specific period (year and run number) and can be associated with vouchers and payment documents for complete payroll tracking.
Endpoints
List Payroll Runs
GET /api/v2/payroll-runs
Retrieves a paginated list of payroll runs.
Query Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| client_account_id | integer | Yes | ID of the client account |
| payment_status | string | No | Filter by payment status (comma-separated for multiple values) |
Response
{
"data": [
{
"id": 1,
"created_by_id": 7,
"created_at": "2024-03-15T10:00:00Z",
"client_account_id": 7,
"run_date": "2024-03-31",
"year": 2024,
"run_number": 3,
"voucher_id": 456,
"payment_document_id": 789,
"payment_status": "PAID"
}
],
"meta": {
"page": 1,
"pages": 1,
"per_page": 25,
"records": 1
}
}
Create Payroll Run
POST /api/v2/payroll-runs
Creates a new payroll run.
Request Body
| Field | Type | Required | Description |
|---|---|---|---|
| client_account_id | integer | Yes | The client account ID |
| run_date | date | Yes | Date of the payroll run |
| year | integer | Yes | Payroll year |
| run_number | integer | Yes | Run number within the year |
| voucher_id | integer | No | Associated voucher ID |
| payment_document_id | integer | No | Associated payment document ID |
Example Request
{
"client_account_id": 7,
"run_date": "2024-03-31",
"year": 2024,
"run_number": 3,
"voucher_id": 456
}
Response
Returns the created payroll run with status 201 Created.
Update Payroll Run
PUT /api/v2/payroll-runs/{id}
Updates an existing payroll run.
Request Body
Same fields as Create Payroll Run. All fields are optional for updates.
Response
Returns the updated payroll run.
Attributes
| Attribute | Type | Description |
|---|---|---|
| id | integer | Unique identifier (read-only) |
| created_by_id | integer | ID of the creating user (read-only) |
| created_at | datetime | Creation timestamp (read-only) |
| client_account_id | integer | ID of the client account |
| run_date | date | Date of the payroll run |
| year | integer | Payroll year |
| run_number | integer | Run number within the year |
| voucher_id | integer | Associated voucher ID |
| payment_document_id | integer | Associated payment document ID |
| payment_status | string | Payment status (read-only) |
Error Responses
| Status Code | Description |
|---|---|
| 400 | Invalid request (missing required fields) |
| 403 | Forbidden (no access to client account) |
| 404 | Payroll run not found |