Payroll Runs
Payroll runs represent individual payroll processing cycles. Each run covers a specific period and contains payroll lines for each employee. Payroll runs are a subtype of Documents with document_type set to PRRUN.
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 |
Response
{
"data": [
{
"id": 1,
"created_by_id": 7,
"created_at": "2024-03-15T10:00:00Z",
"client_account_id": 7,
"document_date": "2024-03-31",
"document_number": "3",
"period_start": "2024-03-01",
"period_end": "2024-03-31",
"uploaded_file_id": 456,
"is_draft": false,
"document_type": "PRRUN"
}
],
"meta": {
"page": 1,
"pages": 1,
"per_page": 25,
"records": 1
}
}
Create Payroll Run
POST /api/v2/payroll-runs
Creates a new payroll run. The run is created as a draft (is_draft: true).
Request Body
| Field | Type | Required | Description |
|---|---|---|---|
| client_account_id | integer | Yes | The client account ID |
| document_date | date | No | Date of the payroll run |
| document_number | string | No | Run number (e.g. “3” for the third run of the year) |
| period_start | date | No | Start date of the payroll period |
| period_end | date | No | End date of the payroll period |
Example Request
{
"client_account_id": 7,
"document_date": "2024-03-31",
"document_number": "3",
"period_start": "2024-03-01",
"period_end": "2024-03-31"
}
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
| Field | Type | Required | Description |
|---|---|---|---|
| document_date | date | No | Date of the payroll run |
| document_number | string | No | Run number |
| period_start | date | No | Start date of the payroll period |
| period_end | date | No | End date of the payroll period |
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 |
| document_date | date | Date of the payroll run |
| document_number | string | Run number within the year |
| period_start | date | Start date of the payroll period |
| period_end | date | End date of the payroll period |
| uploaded_file_id | integer | Associated voucher/file ID (read-only) |
| is_draft | boolean | Whether this is a draft run (read-only) |
| document_type | string | Always PRRUN (read-only) |
Relationships
The following related objects can be included using the with parameter:
payroll_lines- Employee payroll lines for this run
Payroll lines support nested relations using dot notation (e.g. with=payroll_lines.item_type):
payroll_lines.item_type- The payroll item type definitionpayroll_lines.business_partner- The employeepayroll_lines.contract- The employment contractpayroll_lines.tax_card- The employee’s tax card
Payroll Line Attributes
| Attribute | Type | Description |
|---|---|---|
| id | integer | Unique identifier (read-only) |
| document_id | integer | Parent payroll run ID (read-only) |
| business_partner_id | integer | Employee ID |
| item_type_id | integer | Payroll item type ID |
| contract_id | integer | Employment contract ID |
| tax_card_id | integer | Employee tax card ID |
| description | string | Line description |
| quantity | decimal | Quantity (e.g. hours worked) |
| rate | decimal | Rate (e.g. hourly rate) |
| amount | decimal | Calculated amount |
| sort_order | integer | Display order |
Error Responses
| Status Code | Description |
|---|---|
| 400 | Invalid request (missing required fields) |
| 403 | Forbidden (no access to client account) |
| 404 | Payroll run not found |