Last updated 9 October 2026View as Markdown

Decode a tax code

GET /v1/tax-codes/{code} No key

What a tax code means: its allowance (or K code addition), region (S, C), basis (cumulative or week 1/month 1), and flat rate for BR, D0, D1 and the like. No key needed.

Request

Parameters in the path and query string.

Field	Type	Description
`code` required, in the path	string	The tax code, such as 1257L, S1257L, K475 M1, BR or NT.
`tax_year` optional, in the query	string	The tax year, such as 2026-27. The latest when not given.

Example

curl https://api.checktakehomepay.co.uk/v1/tax-codes/1257L

const response = await fetch('https://api.checktakehomepay.co.uk/v1/tax-codes/1257L');
const result = await response.json();

import requests

response = requests.get("https://api.checktakehomepay.co.uk/v1/tax-codes/1257L")
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",
  "code": "1257L",
  "kind": "allowance",
  "region": "rest_of_uk",
  "basis": "cumulative",
  "allowance": 12579,
  "description": "£12,579 a year of pay is free of tax, then England and Northern Ireland's rates apply.",
  "assumptions": [
    "An allowance or K code's figure is its number × 10 plus 9 (0T has none): a code drops the last digit of the allowance, so 9 is added back, and 1257L stands for £12,579 against the £12,570 personal allowance. Payroll spreads it across the pay periods, so a year of weekly or monthly pay frees a few pence more."
  ],
  "sources": [
    "https://www.gov.uk/government/publications/payroll-technical-specifications-income-tax"
  ]
}

Errors

400 INVALID_INPUT: the message names each field that is wrong.

Every code, and how to handle them: Errors.