Last updated 9 October 2026View as Markdown

Minimum wage check

POST /v1/minimum-wage-check Needs a key

Whether pay for the hours worked meets the National Minimum Wage or National Living Wage for the age, and by how much it falls short.

Request

A JSON body. Fields not listed here are rejected.

Field	Type	Description
`age` required	integer	The minimum wage applies from school-leaving age. Allowed: 16 to 100.
`pay` required	number	Pay for the period. Allowed: 0 or more, under 100,000,000.
`hours` required	number	Hours worked in the period, to two decimal places. Allowed: 0.01 to 744.
`tax_year` optional	string	The tax year, such as 2026-27. The latest when not given. Default `"2026-27"`.
`apprentice` optional	boolean	An apprentice. Default `false`.
`apprentice_first_year` optional	boolean	In the first year of the apprenticeship. Default `false`.

Example

curl https://api.checktakehomepay.co.uk/v1/minimum-wage-check \
  -H "Authorization: Bearer $CHECKTAKEHOMEPAY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "age": 25,
  "pay": 1300,
  "hours": 100
}'

const response = await fetch('https://api.checktakehomepay.co.uk/v1/minimum-wage-check', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.CHECKTAKEHOMEPAY_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "age": 25,
    "pay": 1300,
    "hours": 100
  }),
});
const result = await response.json();

import os
import requests

response = requests.post(
    "https://api.checktakehomepay.co.uk/v1/minimum-wage-check",
    headers={"Authorization": f"Bearer {os.environ['CHECKTAKEHOMEPAY_API_KEY']}"},
    json={"age": 25, "pay": 1300, "hours": 100},
)
result = response.json()

Response

200, with the result and what produced it: tax_year, engine, hmrc_test_data, assumptions and sources. This is the example's real response. Every field's type is in the OpenAPI document.

200 OK

{
  "tax_year": "2026-27",
  "engine": "2026-27.1",
  "hmrc_test_data": "rest of UK and Welsh tax v1.0, Scottish tax v1.1, NI v1.0, directors NI v1.0, student loans v1.0",
  "band": "aged21AndOver",
  "rate": 12.71,
  "hourly_pay": 13,
  "meets_minimum": true,
  "shortfall": 0,
  "assumptions": [
    "The apprentice rate applies under 19 or in the first year of an apprenticeship; after that, the rate for the age.",
    "pay is what counts towards the minimum wage for the hours given: the caller leaves out what does not (tips, most premiums, some deductions)."
  ],
  "sources": [
    "https://www.gov.uk/national-minimum-wage-rates"
  ]
}

Errors

400 INVALID_INPUT: the message names each field that is wrong.
401 UNAUTHENTICATED (no key) or INVALID_KEY (a key we don’t know, or a revoked one).

Every code, and how to handle them: Errors.