finov.ioDocumentationHome

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
    }
  ]
}