Payroll
API Documentation / Resources
Get payroll home status
GET /v1/tenants/{tenant_id}/subsidiaries/{subsidiary_id}/payroll/home
Required OAuth scope: payroll:read
Returns payroll readiness and operational counts for the subsidiary.
Required payroll capability
| Capability | Data made available |
|---|---|
operations |
Setup completion, draft-run counts, employee setup counts, and leave awaiting approval. |
This read does not expose employee tax, bank, or payslip details.
Parameters
| Name | In | Required | Type | Description |
|---|---|---|---|---|
tenant_id |
path | Yes | string (uuid) | UUID of the authorized company group. |
subsidiary_id |
path | Yes | string (uuid) | UUID of the payroll subsidiary. |
Request
GET /v1/tenants/{tenant_id}/subsidiaries/{subsidiary_id}/payroll/home HTTP/1.1
Host: api.finov.io
Authorization: Bearer {access_token}
Responses
| Status | Description |
|---|---|
200 |
Payroll readiness and operational status. |
401 |
Access token is missing, expired, revoked, or invalid. |
403 |
Token lacks payroll scope, user capability, or subsidiary payroll availability. |
200 example
HTTP/1.1 200 OK
Content-Type: application/json
{
"enabled": true,
"ready": true,
"setup": [
{
"key": "general",
"label": "Payroll enabled",
"complete": true,
"screen": "settings-payroll-general"
}
],
"pay_runs": {
"draft_count": 1,
"active_calendar_count": 2
},
"employees": {
"active_count": 12,
"requiring_setup_count": 0
},
"leave": {
"awaiting_approval_count": 1
}
}
List payroll pay runs
GET /v1/tenants/{tenant_id}/subsidiaries/{subsidiary_id}/payroll/pay-runs
Required OAuth scope: payroll:read
Lists pay runs newest payment date first and returns active calendars for filtering.
Required payroll capability
| Capability | Data made available |
|---|---|
operations |
Pay-run periods, statuses, employee counts, and aggregate payroll totals. |
Filter by calendar UUID or lifecycle status. Monetary totals remain decimal strings from the native payroll service.
Parameters
| Name | In | Required | Type | Description |
|---|---|---|---|---|
tenant_id |
path | Yes | string (uuid) | UUID of the authorized company group. |
subsidiary_id |
path | Yes | string (uuid) | UUID of the payroll subsidiary. |
calendar |
query | No | string (uuid) | Exact pay-calendar UUID. |
status |
query | No | string: DRAFT, APPROVED, SUBMITTED | |
page |
query | No | integer | |
per_page |
query | No | integer: 10, 25, 50 |
Request
GET /v1/tenants/{tenant_id}/subsidiaries/{subsidiary_id}/payroll/pay-runs HTTP/1.1
Host: api.finov.io
Authorization: Bearer {access_token}
Responses
| Status | Description |
|---|---|
200 |
A page of payroll pay runs. |
401 |
Access token is missing, expired, revoked, or invalid. |
403 |
Token lacks payroll scope, user capability, or subsidiary payroll availability. |
422 |
Payroll filters, state, country, or file-generation requirements failed validation. |
200 example
HTTP/1.1 200 OK
Content-Type: application/json
{
"pay_runs": [
{
"identifier": "10000000-0000-4000-8000-000000000001",
"calendar_identifier": "20000000-0000-4000-8000-000000000001",
"calendar": "Fortnightly payroll",
"calendar_type": "FORTNIGHTLY",
"period_start_date": "2026-08-10",
"period_end_date": "2026-08-23",
"payment_date": "2026-08-28",
"pay_run_type": "REGULAR",
"status": "SUBMITTED",
"total_wages": "24500.00",
"total_deductions": "850.00",
"total_tax": "5210.00",
"total_super": "2695.00",
"total_reimbursements": "120.00",
"total_net_pay": "18560.00",
"posted_at": "2026-08-28T02:15:00Z",
"employee_count": 12
}
],
"total": 1,
"current_page": 1,
"per_page": 10,
"calendars": [
{
"identifier": "20000000-0000-4000-8000-000000000001",
"name": "Fortnightly payroll",
"period_start_date": "2026-08-10",
"payment_date": "2026-08-28",
"calendar_type": "FORTNIGHTLY"
}
]
}
Get a payroll pay run
GET /v1/tenants/{tenant_id}/subsidiaries/{subsidiary_id}/payroll/pay-runs/{pay_run_id}
Required OAuth scope: payroll:read
Returns a pay run workspace including employee totals, reimbursements, journal and payment previews, submission history, and payment state.
Required payroll capabilities
| Capability | Data made available |
|---|---|
operations |
Operational run, preview, reimbursement, and history data. |
sensitive_employee_data |
Employee-level payroll amounts and payslip associations. |
Draft previews are calculations, not posted journals or finalized payment instructions.
Parameters
| Name | In | Required | Type | Description |
|---|---|---|---|---|
tenant_id |
path | Yes | string (uuid) | |
subsidiary_id |
path | Yes | string (uuid) | |
pay_run_id |
path | Yes | string (uuid) | UUID of the pay run. |
Request
GET /v1/tenants/{tenant_id}/subsidiaries/{subsidiary_id}/payroll/pay-runs/{pay_run_id} HTTP/1.1
Host: api.finov.io
Authorization: Bearer {access_token}
Responses
| Status | Description |
|---|---|
200 |
Complete pay-run workspace. |
401 |
Access token is missing, expired, revoked, or invalid. |
403 |
Token lacks payroll scope, user capability, or subsidiary payroll availability. |
404 |
Payroll resource does not exist in the granted accounting context. |
200 example
HTTP/1.1 200 OK
Content-Type: application/json
{
"pay_run": {
"identifier": "10000000-0000-4000-8000-000000000001",
"calendar": "Fortnightly payroll",
"status": "SUBMITTED",
"payment_date": "2026-08-28",
"total_net_pay": "18560.00"
},
"payslips": [
{
"identifier": "30000000-0000-4000-8000-000000000001",
"employee_identifier": "40000000-0000-4000-8000-000000000001",
"first_name": "Aroha",
"last_name": "Ngata",
"gross_earnings": "2500.00",
"net_pay": "1880.00"
}
],
"reimbursements": [],
"reimbursement_types": [],
"journal_preview": {
"balanced": true,
"lines": []
},
"payment_preview": {
"total_amount": "18560.00",
"payments": []
},
"payment_batch": {
"identifier": "50000000-0000-4000-8000-000000000001",
"file_format": "PAIN_001",
"total_amount": "18560.00",
"total_records": 12
},
"posted_journal_identifier": "60000000-0000-4000-8000-000000000001",
"country_code": "NZL",
"payment_sent_scopes": [],
"payment_status": {
"employee": "READY"
},
"approval_required": false,
"can_remove_redo": true,
"history": []
}
Get a pay-run payslip
GET /v1/tenants/{tenant_id}/subsidiaries/{subsidiary_id}/payroll/pay-runs/{pay_run_id}/payslips/{payslip_id}
Required OAuth scope: payroll:read
Returns one payslip belonging to the selected pay run with calculated earnings, deductions, reimbursements, leave, retirement, and tax detail.
Required payroll capability
| Capability | Data made available |
|---|---|
operations |
The calculated payslip lines used to review the pay run. |
The response is JSON detail; use the employee payslip download operation for a rendered PDF envelope.
Parameters
| Name | In | Required | Type | Description |
|---|---|---|---|---|
tenant_id |
path | Yes | string (uuid) | |
subsidiary_id |
path | Yes | string (uuid) | |
pay_run_id |
path | Yes | string (uuid) | |
payslip_id |
path | Yes | string (uuid) |
Request
GET /v1/tenants/{tenant_id}/subsidiaries/{subsidiary_id}/payroll/pay-runs/{pay_run_id}/payslips/{payslip_id} HTTP/1.1
Host: api.finov.io
Authorization: Bearer {access_token}
Responses
| Status | Description |
|---|---|
200 |
Calculated payslip detail. |
401 |
Access token is missing, expired, revoked, or invalid. |
403 |
Token lacks payroll scope, user capability, or subsidiary payroll availability. |
404 |
Payroll resource does not exist in the granted accounting context. |
200 example
HTTP/1.1 200 OK
Content-Type: application/json
{
"payslip": {
"identifier": "30000000-0000-4000-8000-000000000001",
"employee_identifier": "40000000-0000-4000-8000-000000000001",
"employee_name": "Aroha Ngata",
"status": "DRAFT",
"gross_earnings": 2500,
"total_deductions": 120,
"total_reimbursements": 0,
"total_super": 75,
"total_employee_tax": 500,
"total_employer_tax": 0,
"net_pay": 1880
},
"editable": true,
"earnings": [
{
"display_name": "Ordinary hours",
"number_of_units": "80.00",
"rate_per_unit": "31.25",
"amount": "2500.00"
}
],
"deductions": [
{
"name": "Student loan deduction",
"amount": "120.00"
}
],
"reimbursements": [],
"leave_accruals": [],
"retirement": [
{
"contribution_type": "KiwiSaver employer contribution",
"amount": "75.00"
}
],
"taxes": [
{
"tax_type_name": "PAYE",
"payer": "EMPLOYEE",
"amount": "500.00"
}
]
}
Download a pay-run payment file
GET /v1/tenants/{tenant_id}/subsidiaries/{subsidiary_id}/payroll/pay-runs/{pay_run_id}/payment-file
Required OAuth scope: payroll:read
Generates the finalized regional bank file for a submitted pay run and returns it in a JSON base64 envelope.
Required payroll capabilities
| Capability | Data made available |
|---|---|
posting |
Finalized payment batch output for the submitted run. |
sensitive_employee_data |
Employee payment instructions embedded in the bank file. |
ABA content uses text/plain; PAIN_001 content uses application/xml. Downloading does not submit payments to a bank.
Parameters
| Name | In | Required | Type | Description |
|---|---|---|---|---|
tenant_id |
path | Yes | string (uuid) | |
subsidiary_id |
path | Yes | string (uuid) | |
pay_run_id |
path | Yes | string (uuid) | UUID of the pay run. |
Request
GET /v1/tenants/{tenant_id}/subsidiaries/{subsidiary_id}/payroll/pay-runs/{pay_run_id}/payment-file HTTP/1.1
Host: api.finov.io
Authorization: Bearer {access_token}
Responses
| Status | Description |
|---|---|
200 |
JSON envelope containing the base64-encoded payment file. |
401 |
Access token is missing, expired, revoked, or invalid. |
403 |
Token lacks payroll scope, user capability, or subsidiary payroll availability. |
404 |
Payroll resource does not exist in the granted accounting context. |
422 |
Payroll filters, state, country, or file-generation requirements failed validation. |
200 example
HTTP/1.1 200 OK
Content-Type: application/json
{
"file_format": "PAIN_001",
"filename": "payroll-2026-08-28.xml",
"mime_type": "application/xml",
"content_base64": "PD94bWwgdmVyc2lvbj0iMS4wIj8+"
}
List payroll employees
GET /v1/tenants/{tenant_id}/subsidiaries/{subsidiary_id}/payroll/employees
Required OAuth scope: payroll:read
Lists payroll employees with calendar, engagement, calculation, and assigned dimension summaries.
Required payroll capability
| Capability | Data made available |
|---|---|
operations |
Employee register fields and payroll setup classifications. |
Search matches name, email, or job title. Dimension filters use a map from dimension UUID to element UUID.
Parameters
| Name | In | Required | Type | Description |
|---|---|---|---|---|
tenant_id |
path | Yes | string (uuid) | UUID of the authorized company group. |
subsidiary_id |
path | Yes | string (uuid) | UUID of the payroll subsidiary. |
search |
query | No | string | |
status |
query | No | string: ACTIVE, INACTIVE | |
calendar |
query | No | string (uuid) | |
engagement |
query | No | string | |
dimensions |
query | No | object | Dimension UUID keys mapped to selected element UUID values. |
page |
query | No | integer | |
per_page |
query | No | integer: 10, 25, 50 |
Request
GET /v1/tenants/{tenant_id}/subsidiaries/{subsidiary_id}/payroll/employees HTTP/1.1
Host: api.finov.io
Authorization: Bearer {access_token}
Responses
| Status | Description |
|---|---|
200 |
A page of payroll employees and filter options. |
401 |
Access token is missing, expired, revoked, or invalid. |
403 |
Token lacks payroll scope, user capability, or subsidiary payroll availability. |
422 |
Payroll filters, state, country, or file-generation requirements failed validation. |
200 example
HTTP/1.1 200 OK
Content-Type: application/json
{
"employees": [
{
"identifier": "40000000-0000-4000-8000-000000000001",
"first_name": "Aroha",
"last_name": "Ngata",
"email": "[email protected]",
"job_title": "Operations manager",
"start_date": "2025-02-03",
"end_date": null,
"status": "ACTIVE",
"calendar_identifier": "20000000-0000-4000-8000-000000000001",
"calendar": "Fortnightly payroll",
"calendar_type": "FORTNIGHTLY",
"engagement_type": "FULL_TIME",
"engagement": "Full time",
"calculation_type": "ANNUAL_SALARY",
"dimensions": {}
}
],
"total": 1,
"current_page": 1,
"per_page": 10,
"calendars": [
{
"identifier": "20000000-0000-4000-8000-000000000001",
"name": "Fortnightly payroll"
}
],
"engagement_types": [
{
"code": "FULL_TIME",
"name": "Full time"
}
],
"dimensions": []
}
Get a payroll employee
GET /v1/tenants/{tenant_id}/subsidiaries/{subsidiary_id}/payroll/employees/{employee_id}
Required OAuth scope: payroll:read
Returns the employee payroll workspace including jurisdictional profile, pay setup, leave, retirement, bank-account, and payslip data.
Required payroll capability
| Capability | Data made available |
|---|---|
sensitive_employee_data |
Personal, tax, bank, retirement, leave, and historical payslip information. |
Jurisdiction-specific nested fields are returned only when applicable to the subsidiary country.
Parameters
| Name | In | Required | Type | Description |
|---|---|---|---|---|
tenant_id |
path | Yes | string (uuid) | |
subsidiary_id |
path | Yes | string (uuid) | |
employee_id |
path | Yes | string (uuid) | UUID of the payroll employee. |
Request
GET /v1/tenants/{tenant_id}/subsidiaries/{subsidiary_id}/payroll/employees/{employee_id} HTTP/1.1
Host: api.finov.io
Authorization: Bearer {access_token}
Responses
| Status | Description |
|---|---|
200 |
Complete employee payroll workspace. |
401 |
Access token is missing, expired, revoked, or invalid. |
403 |
Token lacks payroll scope, user capability, or subsidiary payroll availability. |
404 |
Payroll resource does not exist in the granted accounting context. |
200 example
HTTP/1.1 200 OK
Content-Type: application/json
{
"country": "NZL",
"employee": {
"identifier": "40000000-0000-4000-8000-000000000001",
"first_name": "Aroha",
"last_name": "Ngata",
"status": "ACTIVE"
},
"address": {},
"profile": {
"tax_classification": "M",
"ird_number": "123456789"
},
"dimensions": [],
"earnings": [
{
"name": "Annual salary",
"annual_salary": "65000.00",
"status": "ACTIVE"
}
],
"deductions": [],
"reimbursements": [],
"leave": [],
"leave_history": [],
"leave_balance_history": [],
"retirement": [],
"retirement_contributions": [],
"retirement_options": [],
"contribution_types": [],
"employee_options": {},
"profile_options": {},
"bank_accounts": [],
"payslips": [
{
"identifier": "30000000-0000-4000-8000-000000000001",
"payment_date": "2026-08-28",
"net_pay": "1880.00"
}
]
}
Download an employee payslip
GET /v1/tenants/{tenant_id}/subsidiaries/{subsidiary_id}/payroll/employees/{employee_id}/payslips/{payslip_id}/download
Required OAuth scope: payroll:read
Renders one employee payslip as PDF and returns the bytes in a JSON base64 envelope.
Required payroll capability
| Capability | Data made available |
|---|---|
sensitive_employee_data |
The employee's rendered earnings, tax, deductions, retirement, and net-pay statement. |
Decode content_base64 before saving the file named by filename; the HTTP response itself is not binary.
Parameters
| Name | In | Required | Type | Description |
|---|---|---|---|---|
tenant_id |
path | Yes | string (uuid) | |
subsidiary_id |
path | Yes | string (uuid) | |
employee_id |
path | Yes | string (uuid) | |
payslip_id |
path | Yes | string (uuid) |
Request
GET /v1/tenants/{tenant_id}/subsidiaries/{subsidiary_id}/payroll/employees/{employee_id}/payslips/{payslip_id}/download HTTP/1.1
Host: api.finov.io
Authorization: Bearer {access_token}
Responses
| Status | Description |
|---|---|
200 |
JSON envelope containing the base64-encoded PDF. |
401 |
Access token is missing, expired, revoked, or invalid. |
403 |
Token lacks payroll scope, user capability, or subsidiary payroll availability. |
404 |
Payroll resource does not exist in the granted accounting context. |
200 example
HTTP/1.1 200 OK
Content-Type: application/json
{
"filename": "payslip-aroha-ngata-2026-08-28.pdf",
"mime_type": "application/pdf",
"content_base64": "JVBERi0xLjQKJcTl8uXr"
}
List payroll leave
GET /v1/tenants/{tenant_id}/subsidiaries/{subsidiary_id}/payroll/leave
Required OAuth scope: payroll:read
Lists employee leave requests newest first with requested units and current balance context.
Required payroll capability
| Capability | Data made available |
|---|---|
operations |
Leave periods, workflow status, employee names, and leave balance context. |
Search matches employee or leave-type name; status is limited to the current request workflow.
Parameters
| Name | In | Required | Type | Description |
|---|---|---|---|---|
tenant_id |
path | Yes | string (uuid) | UUID of the authorized company group. |
subsidiary_id |
path | Yes | string (uuid) | UUID of the payroll subsidiary. |
search |
query | No | string | |
status |
query | No | string: REQUESTED, APPROVED, REJECTED | |
page |
query | No | integer | |
per_page |
query | No | integer: 10, 25, 50 |
Request
GET /v1/tenants/{tenant_id}/subsidiaries/{subsidiary_id}/payroll/leave HTTP/1.1
Host: api.finov.io
Authorization: Bearer {access_token}
Responses
| Status | Description |
|---|---|
200 |
A page of leave requests and eligible employee options. |
401 |
Access token is missing, expired, revoked, or invalid. |
403 |
Token lacks payroll scope, user capability, or subsidiary payroll availability. |
422 |
Payroll filters, state, country, or file-generation requirements failed validation. |
200 example
HTTP/1.1 200 OK
Content-Type: application/json
{
"leave": [
{
"identifier": "70000000-0000-4000-8000-000000000001",
"title": "Annual leave",
"start_date": "2026-09-07",
"end_date": "2026-09-08",
"status": "REQUESTED",
"employee_identifier": "40000000-0000-4000-8000-000000000001",
"first_name": "Aroha",
"last_name": "Ngata",
"leave_type": "Annual leave",
"unit_of_measure": "Hours",
"balance": "96.00",
"units": "16.00"
}
],
"total": 1,
"current_page": 1,
"per_page": 10,
"employees": [
{
"identifier": "40000000-0000-4000-8000-000000000001",
"first_name": "Aroha",
"last_name": "Ngata",
"leave_types": []
}
]
}
Get payroll account mappings
GET /v1/tenants/{tenant_id}/subsidiaries/{subsidiary_id}/payroll/account-mappings
Required OAuth scope: payroll:read
Returns payroll posting roles, engagement types, and configured ledger-account mappings.
Required payroll capability
| Capability | Data made available |
|---|---|
settings |
Default and engagement-specific payroll posting configuration. |
Specific pay-item overrides can take precedence over these mappings during journal calculation.
Parameters
| Name | In | Required | Type | Description |
|---|---|---|---|---|
tenant_id |
path | Yes | string (uuid) | UUID of the authorized company group. |
subsidiary_id |
path | Yes | string (uuid) | UUID of the payroll subsidiary. |
Request
GET /v1/tenants/{tenant_id}/subsidiaries/{subsidiary_id}/payroll/account-mappings HTTP/1.1
Host: api.finov.io
Authorization: Bearer {access_token}
Responses
| Status | Description |
|---|---|
200 |
Payroll account mapping configuration. |
401 |
Access token is missing, expired, revoked, or invalid. |
403 |
Token lacks payroll scope, user capability, or subsidiary payroll availability. |
200 example
HTTP/1.1 200 OK
Content-Type: application/json
{
"setting_types": [
{
"code": "WAGES_EXPENSE",
"name": "Wages expense",
"ledger": "PROFIT_AND_LOSS",
"hint": "Operating expenses"
}
],
"engagement_types": [
{
"code": "ANY",
"name": "All engagement types"
}
],
"mappings": [
{
"setting_type": "WAGES_EXPENSE",
"engagement_type": "ANY",
"account": "80000000-0000-4000-8000-000000000001"
}
]
}
List payroll calendars
GET /v1/tenants/{tenant_id}/subsidiaries/{subsidiary_id}/payroll/calendars
Required OAuth scope: payroll:read
Returns available calendar types and subsidiary-owned pay calendars.
Required payroll capability
| Capability | Data made available |
|---|---|
settings |
Period anchors, payment dates, posting granularity, and active state. |
Calendar anchors determine recurring periods; employees can be assigned to different active calendars.
Parameters
| Name | In | Required | Type | Description |
|---|---|---|---|---|
tenant_id |
path | Yes | string (uuid) | UUID of the authorized company group. |
subsidiary_id |
path | Yes | string (uuid) | UUID of the payroll subsidiary. |
Request
GET /v1/tenants/{tenant_id}/subsidiaries/{subsidiary_id}/payroll/calendars HTTP/1.1
Host: api.finov.io
Authorization: Bearer {access_token}
Responses
| Status | Description |
|---|---|
200 |
Payroll calendar configuration. |
401 |
Access token is missing, expired, revoked, or invalid. |
403 |
Token lacks payroll scope, user capability, or subsidiary payroll availability. |
200 example
HTTP/1.1 200 OK
Content-Type: application/json
{
"calendar_types": [
{
"code": "FORTNIGHTLY",
"name": "Fortnightly"
}
],
"calendars": [
{
"identifier": "20000000-0000-4000-8000-000000000001",
"name": "Fortnightly payroll",
"calendar_type": "FORTNIGHTLY",
"calendar_type_name": "Fortnightly",
"period_start_date": "2026-08-10",
"reference_date": null,
"payment_date": "2026-08-28",
"posting_granularity": "PER_EMPLOYEE",
"active": true
}
]
}
List payroll earnings rates
GET /v1/tenants/{tenant_id}/subsidiaries/{subsidiary_id}/payroll/earnings-rates
Required OAuth scope: payroll:read
Returns jurisdictional earnings categories, calculation bases, and configured subsidiary earnings rates.
Required payroll capability
| Capability | Data made available |
|---|---|
settings |
Tax, retirement, reporting, rate, unit, and expense-account treatment. |
Fixed amounts and unit rates are decimal values represented by the native payroll service without binary rounding assumptions.
Parameters
| Name | In | Required | Type | Description |
|---|---|---|---|---|
tenant_id |
path | Yes | string (uuid) | UUID of the authorized company group. |
subsidiary_id |
path | Yes | string (uuid) | UUID of the payroll subsidiary. |
Request
GET /v1/tenants/{tenant_id}/subsidiaries/{subsidiary_id}/payroll/earnings-rates HTTP/1.1
Host: api.finov.io
Authorization: Bearer {access_token}
Responses
| Status | Description |
|---|---|
200 |
Payroll earnings-rate configuration. |
401 |
Access token is missing, expired, revoked, or invalid. |
403 |
Token lacks payroll scope, user capability, or subsidiary payroll availability. |
200 example
HTTP/1.1 200 OK
Content-Type: application/json
{
"earnings_types": [
{
"code": "NZ_SALARY_WAGES",
"name": "Salary and wages",
"is_reportable_as_w1": false,
"bas_treatment": null
}
],
"rate_types": [
{
"code": "ANNUAL_SALARY",
"name": "Annual salary"
}
],
"earnings_rates": [
{
"identifier": "90000000-0000-4000-8000-000000000001",
"name": "Annual salary",
"earnings_type": "NZ_SALARY_WAGES",
"earnings_type_name": "Salary and wages",
"rate_type": "ANNUAL_SALARY",
"rate_type_name": "Annual salary",
"unit_of_measure": null,
"expense_account": null,
"fixed_amount": null,
"rate_per_unit": null,
"multiple_of_ordinary_rate": null,
"is_exempt_from_tax": false,
"is_exempt_from_super": false,
"is_reportable_as_w1": false,
"active": true
}
]
}
List payroll deductions
GET /v1/tenants/{tenant_id}/subsidiaries/{subsidiary_id}/payroll/deductions
Required OAuth scope: payroll:read
Returns jurisdictional deduction categories and subsidiary deduction definitions.
Required payroll capability
| Capability | Data made available |
|---|---|
settings |
Statutory, tax, retirement, reporting, liability-account, and active-state treatment. |
Category metadata is platform controlled while deduction definitions belong to the subsidiary.
Parameters
| Name | In | Required | Type | Description |
|---|---|---|---|---|
tenant_id |
path | Yes | string (uuid) | UUID of the authorized company group. |
subsidiary_id |
path | Yes | string (uuid) | UUID of the payroll subsidiary. |
Request
GET /v1/tenants/{tenant_id}/subsidiaries/{subsidiary_id}/payroll/deductions HTTP/1.1
Host: api.finov.io
Authorization: Bearer {access_token}
Responses
| Status | Description |
|---|---|
200 |
Payroll deduction configuration. |
401 |
Access token is missing, expired, revoked, or invalid. |
403 |
Token lacks payroll scope, user capability, or subsidiary payroll availability. |
200 example
HTTP/1.1 200 OK
Content-Type: application/json
{
"categories": [
{
"code": "NZ_STUDENT_LOAN",
"name": "Student loan",
"country": "NZL"
}
],
"deductions": [
{
"identifier": "a0000000-0000-4000-8000-000000000001",
"name": "Student loan deduction",
"deduction_category": "NZ_STUDENT_LOAN",
"deduction_category_name": "Student loan",
"account": null,
"is_statutory": true,
"reduces_tax": false,
"reduces_super": false,
"is_exempt_from_w1": false,
"active": true
}
]
}
List payroll leave types
GET /v1/tenants/{tenant_id}/subsidiaries/{subsidiary_id}/payroll/leave-types
Required OAuth scope: payroll:read
Returns jurisdictional leave categories and subsidiary leave definitions.
Required payroll capability
| Capability | Data made available |
|---|---|
settings |
Units, paid status, payslip visibility, retirement treatment, and active state. |
Leave definitions control availability; employee accrual rules and balances remain employee-specific nested data.
Parameters
| Name | In | Required | Type | Description |
|---|---|---|---|---|
tenant_id |
path | Yes | string (uuid) | UUID of the authorized company group. |
subsidiary_id |
path | Yes | string (uuid) | UUID of the payroll subsidiary. |
Request
GET /v1/tenants/{tenant_id}/subsidiaries/{subsidiary_id}/payroll/leave-types HTTP/1.1
Host: api.finov.io
Authorization: Bearer {access_token}
Responses
| Status | Description |
|---|---|
200 |
Payroll leave-type configuration. |
401 |
Access token is missing, expired, revoked, or invalid. |
403 |
Token lacks payroll scope, user capability, or subsidiary payroll availability. |
200 example
HTTP/1.1 200 OK
Content-Type: application/json
{
"categories": [
{
"code": "NZ_ANNUAL_LEAVE",
"name": "Annual leave"
}
],
"leave_types": [
{
"identifier": "b0000000-0000-4000-8000-000000000001",
"name": "Annual leave",
"unit_of_measure": "Hours",
"is_paid_leave": true,
"show_on_payslip": true,
"leave_category": "NZ_ANNUAL_LEAVE",
"leave_category_name": "Annual leave",
"sgc_exempt": false,
"active": true
}
]
}
List payroll reimbursements
GET /v1/tenants/{tenant_id}/subsidiaries/{subsidiary_id}/payroll/reimbursements
Required OAuth scope: payroll:read
Returns subsidiary reimbursement definitions and optional expense-account overrides.
Required payroll capability
| Capability | Data made available |
|---|---|
settings |
Standard amounts, posting overrides, and active state. |
A null standard amount means operators supply the amount when the reimbursement is used.
Parameters
| Name | In | Required | Type | Description |
|---|---|---|---|---|
tenant_id |
path | Yes | string (uuid) | UUID of the authorized company group. |
subsidiary_id |
path | Yes | string (uuid) | UUID of the payroll subsidiary. |
Request
GET /v1/tenants/{tenant_id}/subsidiaries/{subsidiary_id}/payroll/reimbursements HTTP/1.1
Host: api.finov.io
Authorization: Bearer {access_token}
Responses
| Status | Description |
|---|---|
200 |
Payroll reimbursement configuration. |
401 |
Access token is missing, expired, revoked, or invalid. |
403 |
Token lacks payroll scope, user capability, or subsidiary payroll availability. |
200 example
HTTP/1.1 200 OK
Content-Type: application/json
{
"reimbursements": [
{
"identifier": "c0000000-0000-4000-8000-000000000001",
"name": "General reimbursement",
"account": null,
"account_code": null,
"account_name": null,
"standard_amount": null,
"active": true
}
]
}
List payroll retirement settings
GET /v1/tenants/{tenant_id}/subsidiaries/{subsidiary_id}/payroll/retirement
Required OAuth scope: payroll:read
Returns Australian superannuation funds or New Zealand KiwiSaver benefits for the subsidiary country.
Required payroll capability
| Capability | Data made available |
|---|---|
settings |
Country-specific fund or benefit identifiers, calculation settings, payment details, and active state. |
Consumers must branch on country; item fields intentionally differ between Australian and New Zealand payroll.
Parameters
| Name | In | Required | Type | Description |
|---|---|---|---|---|
tenant_id |
path | Yes | string (uuid) | UUID of the authorized company group. |
subsidiary_id |
path | Yes | string (uuid) | UUID of the payroll subsidiary. |
Request
GET /v1/tenants/{tenant_id}/subsidiaries/{subsidiary_id}/payroll/retirement HTTP/1.1
Host: api.finov.io
Authorization: Bearer {access_token}
Responses
| Status | Description |
|---|---|
200 |
Country-specific retirement configuration. |
401 |
Access token is missing, expired, revoked, or invalid. |
403 |
Token lacks payroll scope, user capability, or subsidiary payroll availability. |
422 |
Payroll filters, state, country, or file-generation requirements failed validation. |
200 example
HTTP/1.1 200 OK
Content-Type: application/json
{
"country": "AUS",
"items": [
{
"identifier": "d0000000-0000-4000-8000-000000000001",
"name": "Example Industry Super",
"fund_type": "APRA",
"abn": "12345678901",
"usi": "12345678901001",
"esa": "example.super",
"bsb": "062000",
"account_number": "12345678",
"active": true
}
]
}