---
title: "Annual leave balance projected forward"
method: POST
path: "/v1/annual-leave"
tags: ["Calculators"]
---

# Annual leave balance projected forward

`POST /v1/annual-leave`

## Request

- Base URL: `https://api.calculate.co.nz`
- URL: `https://api.calculate.co.nz/v1/annual-leave`
- Auth: API key in header `X-API-Key`

Project an NZ annual leave balance forward.

Accrues at `holiday_rate_pct` of hours worked. The Holidays Act 2003 minimum
is four weeks a year, which is the 8% default.

The same balance comes back in hours, days and weeks, because which one is
meaningful depends on the roster: days assume `hours_per_workday` and weeks
assume `hours_per_workweek`, so a part-timer week of leave is not the same
number of hours as a full-timer one.

This projects an accrual. It does not calculate what leave is worth in
dollars, which under the Act depends on ordinary weekly pay versus average
weekly earnings and is a genuinely harder question.

## Request body

- AnnualLeaveRequest
  - `current_balance` number, required: Existing balance
  - `current_balance_unit` 'hours' | 'days': Unit that current_balance is expressed in.
  - `hours_per_workday` number: Hours in a normal working day, used to convert days to hours.
  - `holiday_rate_pct` number: Accrual rate as a percentage of hours worked. The Holidays Act 2003 minimum of four weeks a year is 8%.
  - `hours_per_workweek` number: Hours worked in a normal week.
  - `future_period` number: How far ahead to project, in future_period_unit.
  - `future_period_unit` 'weeks' | 'months' | 'years': Unit that future_period is expressed in.

## Response `200`

Projected balance in hours, days and weeks.

- AnnualLeaveResponse
  - `result` AnnualLeaveResult, required
    - `hours_accrued_per_week` number, required: Leave earned each week at this rate and workweek.
    - `projected_balance_hours` number, required: Balance at the end of the period, in hours.
    - `projected_balance_days` number, required: The same balance in days, at hours_per_workday.
    - `projected_balance_weeks` number, required: The same balance in weeks, at hours_per_workweek.
    - `inputs` object, required: The inputs used, echoed back with defaults filled in.
  - `disclaimer` string, required: Scope and limits of this calculation.

## Other responses

- `422`: Validation Error

---

[API](https://skmtc.dev/calculate/apis/calculate-co-nz-api.md) · [All operations](https://skmtc.dev/calculate/apis/calculate-co-nz-api/llms.txt) · [OpenAPI document](https://skmtc.dev/calculate/apis/calculate-co-nz-api/revisions/aa59a8e76614?raw)