---
title: "Total hours from a timesheet, and what they pay"
method: POST
path: "/v1/work-hours"
tags: ["Calculators"]
---

# Total hours from a timesheet, and what they pay

`POST /v1/work-hours`

## Request

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

Add up a timesheet and turn it into gross pay.

Each day takes a start, a finish and an unpaid break in minutes. Leave days
off out of the list rather than sending zeros.

An overnight shift is handled, not rejected: a finish at or before the start
is treated as the next day, so 22:00 to 06:00 is eight hours. A break longer
than the shift floors the day at zero rather than going negative.

Pay is GROSS. For what is left after PAYE, ACC, KiwiSaver and a student loan,
send the hourly rate and hours to /v1/hourly-to-salary.

Does not apply overtime or penal rates, public holiday entitlements, or a
minimum wage check.

## Request body

- WorkHoursRequest
  - `days` WorkDayInput[], required: One entry per day worked. Leave days off out entirely.
    - `start` string, required: Start time as "HH:MM", 24 hour.
    - `finish` string, required: Finish time as "HH:MM". If it is at or before the start it is treated as an overnight shift, so 22:00 to 06:00 is eight hours.
    - `break_minutes` integer: Unpaid break in minutes.
    - `label` string, nullable: Optional name for the day.
  - `hourly_rate` number: Gross pay per hour. Zero for hours only.

## Response `200`

Hours per day, the total, and gross pay at each frequency.

- WorkHoursResponse
  - `result` WorkHoursResult, required
    - `total_hours` number, required: Paid hours across all days.
    - `days_worked` integer, required: Days with more than zero hours.
    - `hourly_rate` number, required: Rate applied.
    - `weekly_pay` number, required: Gross pay for these hours.
    - `fortnightly_pay` number, required: Twice the weekly figure.
    - `monthly_pay` number, required: A twelfth of the annual figure, not weekly x 4.33.
    - `annual_pay` number, required: Weekly pay over 52 weeks, if every week matched.
    - `days` WorkDayResult[], required: Each day, so the total can be checked.
      - `label` string, required: The day's name, or its position.
      - `start` string, required: Start time as given.
      - `finish` string, required: Finish time as given.
      - `break_minutes` integer, required: Unpaid break deducted.
      - `hours` number, required: Paid hours for the day, after the break.
      - `overnight` boolean, required: True when the shift crossed midnight.
  - `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)