> Statutory notice with the Check Take Home Pay API, POST /v1/notice-pay: every field, an example request in cURL, Node.js and Python, and the response.

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

# Statutory notice

`POST /v1/notice-pay` Needs a key

The least notice an employer must give, and the notice pay for it when a weekly pay is given.

## Request

A JSON body. Fields not listed here are rejected.

| Field | Type | Description |
| --- | --- | --- |
| `months_of_service` required | integer | Months of continuous employment. Allowed: 0 to 1,000. |
| `tax_year` optional | string | The tax year, such as 2026-27. The latest when not given. Default `"2026-27"`. |
| `weekly_pay` optional | number | A week's pay, for the notice pay. Allowed: 0 or more, under 100,000,000. |

## Example

cURL

```
curl https://api.checktakehomepay.co.uk/v1/notice-pay \
  -H "Authorization: Bearer $CHECKTAKEHOMEPAY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "months_of_service": 59,
  "weekly_pay": 512.5
}'
```

Node.js

```
const response = await fetch('https://api.checktakehomepay.co.uk/v1/notice-pay', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.CHECKTAKEHOMEPAY_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "months_of_service": 59,
    "weekly_pay": 512.5
  }),
});
const result = await response.json();
```

Python

```
import os
import requests

response = requests.post(
    "https://api.checktakehomepay.co.uk/v1/notice-pay",
    headers={"Authorization": f"Bearer {os.environ['CHECKTAKEHOMEPAY_API_KEY']}"},
    json={"months_of_service": 59, "weekly_pay": 512.5},
)
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",
  "notice_weeks": 4,
  "notice_pay": 2050,
  "assumptions": [
    "The least notice an employer must give: a week after a month of continuous employment, then a week for each full year from 2 years, up to 12 weeks.",
    "A contract can give more, and the employee gives at least a week after a month."
  ],
  "sources": [
    "https://www.legislation.gov.uk/ukpga/1996/18/section/86"
  ]
}
```

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