Docs
Last updated 9 October 2026View as Markdown

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, 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:

FieldWhat it is
tax_yearThe tax year the rates are from.
engineThe engine revision. It changes when a result changes for the same request, so you can tell a fix from a bug.
hmrc_test_dataThe HMRC payroll test data this engine passes, case for case.
assumptionsWhat the calculation took as given, in plain English.
sourcesThe gov.uk pages and HMRC documents the rules come from.

Errors are { "error": { "code", "message" } }: see Errors.

Endpoints

Employee pay

Payroll

Statutory pay

Entitlements

Contractors

Reference data

Next