---
title: "Current New Zealand statutory rates, dated and sourced"
method: GET
path: "/v1/rates"
tags: ["Reference data"]
---

# Current New Zealand statutory rates, dated and sourced

`GET /v1/rates`

## Request

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

Every New Zealand statutory rate this site maintains, with its provenance.

Tax brackets, the ACC earner levy and its cap, student loan rate and
threshold, KiwiSaver settings, benefit rates and more. Each carries the date
it took effect, where it was read from, and when it was last checked against
the issuing body.

**`verified_on` can be null, and that is deliberate.** A figure recorded but
not yet checked against its issuing body says so rather than looking the
same as one that was. Hiding the difference would make the whole dataset
worth less.

Filter with `q` over the id and label, or with `review_cycle` to get
everything that changes at the same time. `review_cycle=annual-1-april`
returns the figures that move on 1 April, which is the query a payroll or
compliance team actually has.

These are the same figures the calculators on calculate.co.nz consume, and
an automated harness drives those live pages in a browser and compares their
answers to this API. A wrong rate breaks a visible page rather than sitting
unnoticed in a data feed, which is not a claim most rate data can make.

## Query parameters

- `q` string, nullable
- `review_cycle` string, nullable

## Response `200`

The rates, each with its effective date, source and review cycle.

- RatesResponse
  - `dataset` string, required: Name of the dataset.
  - `publisher` string, required: Who maintains it.
  - `count` integer, required: Rates returned by this request.
  - `total` integer, required: Rates in the dataset overall.
  - `verified_count` integer, required: How many carry a verification date.
  - `register_updated` string, nullable: When the register was last touched.
  - `correctness_note` string, required: How these figures are checked.
  - `rates` RateRecord[], required: The rates themselves.
    - `id` string, required: Stable identifier. Safe to store and to key on.
    - `label` string, required: What the figure is, in words.
    - `value` string, required: The current value, as published. A string so 1.75 and 0.0175 are never confused by a float.
    - `effective_from` string, nullable: ISO date the value took effect, where the source states one.
    - `source` string, nullable: Where it was read from. A URL for anything verified against an issuing body.
    - `verified_on` string, nullable: ISO date this figure was last checked against the issuing body. NULL means recorded but not yet verified, and is deliberately visible rather than hidden.
    - `review_cycle` string, required: When it next changes: annual-1-april, budget-may, periodic, or on-legislative-change. This is the field to filter on if you want to know what to re-check and when.
    - `previous_values` string[], nullable: Prior values, most recent first. Undated for now.
    - `history_note` string, nullable: The limits of previous_values.
    - `note` string, nullable: Anything a consumer needs to know about this figure.

## 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)