---
title: "Sick leave entitlement and balance under the Holidays Act"
method: POST
path: "/v1/sick-leave"
tags: ["Calculators"]
---

# Sick leave entitlement and balance under the Holidays Act

`POST /v1/sick-leave`

## Request

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

Work out a sick leave entitlement and what is left of it.

Three rules, and two of them are caps that people forget until they collide.

  - Entitlement starts after SIX MONTHS of continuous employment, then ten
    days on each anniversary. Nothing accrues day by day before that, so an
    employee at five months has no statutory entitlement at all.
  - Carry-over is capped at TEN days. An employee who took none last year
    carries ten, not the full ten they were owed plus anything older.
  - The total is capped at TWENTY days. Ten current plus ten carried is the
    statutory maximum, and a contractual entitlement above ten does not lift
    that cap on the statutory part.

`capped_by_carry_over_limit` and `capped_by_total_limit` say which cap, if
either, bound the answer, because "why is my balance not what I counted" is
almost always one of those two.

Give `daily_pay` to value the balance. Note that relevant daily pay is what
the employee would have earned on the day taken, which is not necessarily
salary divided by 260.

## Request body

- SickLeaveRequest
  - `start_date` string, required: Employment start date, ISO format YYYY-MM-DD.
  - `as_at` string, nullable: Date to calculate at, ISO format. Defaults to today.
  - `days_taken` number: Days taken in the current entitlement year.
  - `carry_over_days` number: Unused days from last year. No more than ten can carry.
  - `extra_contractual_days` integer: Days above the statutory ten that the employment agreement provides.
  - `daily_pay` number, nullable: Relevant daily pay, used to value the balance. Optional.

## Response `200`

Entitlement, carry-over after the cap, and the days remaining.

- SickLeaveResponse
  - `result` SickLeaveResult, required
    - `months_employed` integer, required: Completed months of continuous employment.
    - `entitled` boolean, required: Entitlement begins after six months.
    - `annual_entitlement_days` integer, required: Days for the current entitlement year.
    - `carry_over_applied_days` integer, required: Days actually carried, after the ten day cap.
    - `carry_over_requested_days` integer, required: Days offered as carry-over before the cap.
    - `total_available_days` number, required: Entitlement plus carry-over, after both caps.
    - `days_taken` number, required: Days taken so far.
    - `balance_days` number, required: Days remaining.
    - `balance_value` number, nullable: Balance valued at relevant daily pay, if given.
    - `capped_by_total_limit` boolean, required: Whether the twenty day ceiling bound the total.
    - `capped_by_carry_over_limit` boolean, required: Whether the ten day carry-over cap bound it.
    - `governing_law` string, required: Which Act applies, and until when.
    - `inputs` object, required: The inputs used, 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)