---
title: "Working for Families entitlement after abatement"
method: POST
path: "/v1/working-for-families"
tags: ["Calculators"]
---

# Working for Families entitlement after abatement

`POST /v1/working-for-families`

## Request

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

A family's Working for Families entitlement for the year.

This is the endpoint the API exists for. A model can work out a percentage;
it cannot know that the In-Work Tax Credit is temporarily $7,670 until
31 March 2027, that it reverts to $5,070, or that the pool abates at
27.5 cents in the dollar above $44,900.

Family Tax Credit and In-Work Tax Credit abate TOGETHER against one
threshold. Best Start has its own: 21 cents in the dollar above $79,000,
and it is paid until a child's third birthday, not the first.

**Read `differences_from_website` before comparing this with the page.**
Two are deliberate. The website still asks whether the caregiver works 20
hours a week as a sole parent or 30 combined as a couple, and pays nothing
otherwise; IRD removed that test on 1 July 2020, so this applies the
current one, which is some income from paid work and no income-tested
benefit. And the website pays Best Start in full where this abates it.

`assumptions` returns every rate and threshold used, so a stored answer can
be audited later against the rules that applied on the day.

The Minimum Family Tax Credit is not calculated: it tops a low working
income up to a guaranteed net figure, which needs the family's tax position
rather than its gross income, and IRD works it out separately.

## Request body

- WorkingForFamiliesRequest
  - `children` integer, required: Dependent children in the caregiver's care.
  - `family_income` number, required: Combined gross annual family income from ALL sources: both partners' wages, business income, rental, taxable benefits.
  - `children_under_3` integer: How many of those children are under 3, for Best Start. IRD pays it until the third birthday, not the first.
  - `iwtc_eligible` boolean: Whether the In-Work Tax Credit applies. The test is some income from paid work each week and NOT receiving an income-tested benefit or student allowance. There has been NO hours test since 1 July 2020.
  - `best_start_children_first_year_exempt` integer: How many of the under-3s are in their first year AND were born before 1 April 2026. Those are exempt from the Best Start income test for that year.
  - `iwtc_after_march_2027` boolean: Model the reverted IWTC of $5,070 instead of the temporary $7,670.

## Response `200`

FTC, IWTC and Best Start, each abated by its own rule.

- WorkingForFamiliesResponse
  - `result` WorkingForFamiliesResult, required
    - `children` integer, required: Children as given.
    - `children_under_3` integer, required: Best Start eligible children.
    - `family_income` number, required: Family income as given.
    - `ftc_annual` number, required: Family Tax Credit before abatement.
    - `iwtc_annual` number, required: In-Work Tax Credit before abatement, per family.
    - `iwtc_eligible` boolean, required: Whether the IWTC was included.
    - `combined_ftc_iwtc_before_abatement` number, required: FTC and IWTC together, which is the pool that abates.
    - `abatement` number, required: 27.5 cents per dollar of family income above $44,900.
    - `ftc_iwtc_after_abatement` number, required: What is left of the pool.
    - `best_start_before_abatement` number, required: Best Start at the full rate.
    - `best_start_abatement` number, required: 21 cents per dollar above $79,000, per income-tested child. The website does not apply this and so overstates it.
    - `best_start_annual` number, required: Best Start after its own abatement.
    - `total_annual` number, required: Everything, for the year.
    - `total_weekly` number, required: The same, a week.
    - `total_fortnightly` number, required: The same, a fortnight.
    - `fully_abated` boolean, required: True when income has wiped out FTC and IWTC entirely.
    - `tax_year` string, required: Tax year the rates are for.
    - `assumptions` object, required: Every rate and threshold used, so a stored result can be audited later.
    - `differences_from_website` string[], required: Where this deliberately does not match the website page, and why. Empty since 29 August 2026, when the page was corrected: it held the abolished In-Work Tax Credit hours test, Best Start paid without its abatement, and Best Start asked for as babies under one rather than children under three.
    - `excludes` string[], required: What this does not calculate.
  - `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)