---
title: "The gross salary needed to take home a given amount"
method: POST
path: "/v1/net-to-gross"
tags: ["Calculators"]
---

# The gross salary needed to take home a given amount

`POST /v1/net-to-gross`

## Request

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

Work backwards from a take-home figure to the salary that produces it.

This is the question behind "I need $1,200 a week in the hand, what do I
ask for", and it cannot be answered by scaling: tax is progressive and the
ACC levy is capped, so the gap between gross and net widens as income
rises. Doubling the target does not double the gross.

`deductions_included` is the field to read first. Take-home means different
things to different people, and the same target produces a different gross
depending on whether KiwiSaver and a student loan sit inside it. By default
only income tax and the ACC levy do, which is what the website page assumes.

The Independent Earner Tax Credit is not applied. It would lower the gross
needed, and eligibility turns on facts this endpoint does not ask for.

## Request body

- NetToGrossRequest
  - `target_net` number, required: The take-home wanted, in the period given by `period`.
  - `period` string: annual, monthly, fortnightly or weekly. The target is read in this period and the gross is reported in it too.
  - `kiwisaver_rate` number: Employee contribution as a DECIMAL, 0.035 for 3.5%. Zero by default, which matches the website page. Setting it means the target take-home is AFTER KiwiSaver, so the gross returned is higher.
  - `has_student_loan` boolean: Whether repayments come out before the target is reached.

## Response `200`

The gross salary, and every deduction between it and the target.

- NetToGrossResponse
  - `result` NetToGrossResult, required
    - `target_net_annual` number, required: The target, annualised.
    - `gross_annual` number, required: Gross salary needed, a year.
    - `income_tax` number, required: PAYE income tax at that gross.
    - `acc_levy` number, required: ACC earner levy, capped at the liable earnings maximum.
    - `kiwisaver_employee` number, required: Employee KiwiSaver, zero unless a rate was given.
    - `student_loan` number, required: Student loan repayment, zero unless requested.
    - `net_annual` number, required: Take-home at that gross. Equals the target, to the cent.
    - `period` string, required: The period the per-period figures are in.
    - `gross_per_period` number, required: Gross in the requested period.
    - `net_per_period` number, required: Net in the requested period.
    - `effective_deduction_rate` number, required: Everything deducted as a percentage of gross.
    - `deductions_included` string[], required: Exactly which deductions stand between the gross and the target. The answer is meaningless without this, because 'take-home' means different things to different people.
    - `tax_year` string, required: Tax year the rates are for.
  - `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)