> Decode a tax code with the Check Take Home Pay API, GET /v1/tax-codes/{code}: every field, an example request in cURL, Node.js and Python, and the response.

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

# 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

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

Node.js

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

Python

```
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](https://api.checktakehomepay.co.uk/openapi.json).

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](https://checktakehomepay.co.uk/docs/errors).