> How the Check Take Home Pay API works: the base URL, keys, requests in pounds and pence, what every response carries, and every endpoint.

Web version: https://checktakehomepay.co.uk/docs · Last updated: 2026-10-09

# Check Take Home Pay API

UK pay and employment calculations over HTTP: take-home pay, gross from net, employer cost, payroll periods, statutory pay, entitlements and contractor tax, worked out the way payroll software does. The income tax, National Insurance and student loan rules pass every case in HMRC’s own payroll test data.

## Base URL and keys

Every endpoint is under `https://api.checktakehomepay.co.uk`.

-   Calculations need a key, sent as `Authorization: Bearer <key>`.
-   Reference data needs none: `GET /v1/tax-years`, `GET /v1/rates` and `GET /v1/tax-codes/{code}`.
-   [Sign up](https://checktakehomepay.co.uk/login), free, and make one on your dashboard’s Keys page. Keep it on your server: never in a web page or an app.

## Requests

-   Bodies are JSON with snake\_case fields.
-   Money is pounds and pence: a number with at most two decimal places, such as `45000` or `2083.33`.
-   Pay that recurs is `{ "amount": 3000, "per": "month" }`, with `per` as year, month, four\_weeks, two\_weeks, week, day or hour. Days and hours use the working pattern: 5 days and 37.5 hours a week, 52 weeks a year, unless you send `working_pattern`.
-   `tax_year` is the latest (2026-27) when not given.
-   A field the endpoint doesn’t know is an error, not ignored, so a typo can’t quietly change an answer.

## Responses

Money comes back in pounds and pence. Besides the result, every response says what produced it:

| Field | What it is |
| --- | --- |
| `tax_year` | The tax year the rates are from. |
| `engine` | The engine revision. It changes when a result changes for the same request, so you can tell a fix from a bug. |
| `hmrc_test_data` | The HMRC payroll test data this engine passes, case for case. |
| `assumptions` | What the calculation took as given, in plain English. |
| `sources` | The gov.uk pages and HMRC documents the rules come from. |

Errors are `{ "error": { "code", "message" } }`: see [Errors](https://checktakehomepay.co.uk/docs/errors).

## Endpoints

### Employee pay

-   [`POST /v1/take-home`](https://checktakehomepay.co.uk/docs/api/take-home): Take-home pay
-   [`POST /v1/gross-from-net`](https://checktakehomepay.co.uk/docs/api/gross-from-net): Gross from net
-   [`POST /v1/employer-cost`](https://checktakehomepay.co.uk/docs/api/employer-cost): Employer cost

### Payroll

-   [`POST /v1/payroll/period`](https://checktakehomepay.co.uk/docs/api/payroll-period): One pay period

### Statutory pay

-   [`POST /v1/statutory/sick-pay`](https://checktakehomepay.co.uk/docs/api/statutory-sick-pay): Statutory Sick Pay
-   [`POST /v1/statutory/maternity-pay`](https://checktakehomepay.co.uk/docs/api/statutory-maternity-pay): Statutory Maternity Pay
-   [`POST /v1/statutory/adoption-pay`](https://checktakehomepay.co.uk/docs/api/statutory-adoption-pay): Statutory Adoption Pay
-   [`POST /v1/statutory/paternity-pay`](https://checktakehomepay.co.uk/docs/api/statutory-paternity-pay): Statutory Paternity Pay
-   [`POST /v1/statutory/shared-parental-pay`](https://checktakehomepay.co.uk/docs/api/statutory-shared-parental-pay): Statutory Shared Parental Pay
-   [`POST /v1/statutory/parental-bereavement-pay`](https://checktakehomepay.co.uk/docs/api/statutory-parental-bereavement-pay): Statutory Parental Bereavement Pay
-   [`POST /v1/statutory/neonatal-care-pay`](https://checktakehomepay.co.uk/docs/api/statutory-neonatal-care-pay): Statutory Neonatal Care Pay

### Entitlements

-   [`POST /v1/redundancy-pay`](https://checktakehomepay.co.uk/docs/api/redundancy-pay): Statutory redundancy pay
-   [`POST /v1/notice-pay`](https://checktakehomepay.co.uk/docs/api/notice-pay): Statutory notice
-   [`POST /v1/holiday-entitlement`](https://checktakehomepay.co.uk/docs/api/holiday-entitlement): Holiday entitlement
-   [`POST /v1/minimum-wage-check`](https://checktakehomepay.co.uk/docs/api/minimum-wage-check): Minimum wage check

### Contractors

-   [`POST /v1/self-employed`](https://checktakehomepay.co.uk/docs/api/self-employed): Self-employed take-home
-   [`POST /v1/director-pay`](https://checktakehomepay.co.uk/docs/api/director-pay): Director salary and dividends
-   [`POST /v1/umbrella-pay`](https://checktakehomepay.co.uk/docs/api/umbrella-pay): Umbrella company pay
-   [`POST /v1/ir35-compare`](https://checktakehomepay.co.uk/docs/api/ir35-compare): Inside against outside IR35

### Reference data

-   [`GET /v1/tax-years`](https://checktakehomepay.co.uk/docs/api/tax-years): Tax years (no key)
-   [`GET /v1/rates`](https://checktakehomepay.co.uk/docs/api/rates): Rates and thresholds (no key)
-   [`GET /v1/tax-codes/{code}`](https://checktakehomepay.co.uk/docs/api/tax-codes): Decode a tax code (no key)

## Next

-   [Quickstart: A first calculation in cURL, Node.js or Python.](https://checktakehomepay.co.uk/docs/quickstart)
-   [Errors: Every error code, and how to handle them.](https://checktakehomepay.co.uk/docs/errors)
-   [Build with an agent: What to give an AI assistant so it can use the API.](https://checktakehomepay.co.uk/docs/agents)