> Call the Check Take Home Pay API in a few minutes: look up a tax code without a key, then work out take-home pay in cURL, Node.js or Python.

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

# Quickstart

From nothing to a take-home pay calculation in a few minutes.

## 1\. Get a key

Calculations need a key. [Sign up](https://checktakehomepay.co.uk/login), free, and make one on your dashboard’s Keys page. Put it in an environment variable, `CHECKTAKEHOMEPAY_API_KEY`, so it stays out of your code.

## 2\. Try it without a key

Reference data is open, so you can see the API answer before your key arrives:

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

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()
```

## 3\. Work out take-home pay

A £45,000 salary in England, paid monthly, with a Plan 2 student loan and 5% salary sacrifice into a pension on qualifying earnings:

`POST /v1/take-home`

cURL

```
curl https://api.checktakehomepay.co.uk/v1/take-home \
  -H "Authorization: Bearer $CHECKTAKEHOMEPAY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "gross": {
    "amount": 45000,
    "per": "year"
  },
  "region": "england",
  "student_loans": [
    "plan_2"
  ],
  "pension": {
    "method": "salary_sacrifice",
    "percent": 5,
    "basis": "qualifying_earnings"
  },
  "pay_frequency": "monthly"
}'
```

Node.js

```
const response = await fetch('https://api.checktakehomepay.co.uk/v1/take-home', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.CHECKTAKEHOMEPAY_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "gross": {
      "amount": 45000,
      "per": "year"
    },
    "region": "england",
    "student_loans": [
      "plan_2"
    ],
    "pension": {
      "method": "salary_sacrifice",
      "percent": 5,
      "basis": "qualifying_earnings"
    },
    "pay_frequency": "monthly"
  }),
});
const result = await response.json();
```

Python

```
import os
import requests

response = requests.post(
    "https://api.checktakehomepay.co.uk/v1/take-home",
    headers={"Authorization": f"Bearer {os.environ['CHECKTAKEHOMEPAY_API_KEY']}"},
    json={
        "gross": {"amount": 45000, "per": "year"},
        "region": "england",
        "student_loans": ["plan_2"],
        "pension": {
            "method": "salary_sacrifice",
            "percent": 5,
            "basis": "qualifying_earnings",
        },
        "pay_frequency": "monthly",
    },
)
result = response.json()
```

## 4\. Read the response

-   `periods.month.take_home` is the average month’s take-home; `periods.year` is the year. There are also four\_weeks, two\_weeks, week, day and hour.
-   `payslips` has each pay period as payroll runs it: the figures that land in the bank each month.
-   `tax_code` is the code used, and `tax_code_derived` says whether it was worked out for you.
-   `tax_bands` splits the tax by rate, and `rates` gives the effective and marginal rates.
-   `assumptions` and `sources` say what was taken as given and where the rules come from.

The full response is on the [take-home pay reference](https://checktakehomepay.co.uk/docs/api/take-home).

## 5\. Next steps

-   Need a salary from a take-home figure? [Gross from net](https://checktakehomepay.co.uk/docs/api/gross-from-net).
-   Costing a hire? [Employer cost](https://checktakehomepay.co.uk/docs/api/employer-cost).
-   Running payroll? [One pay period](https://checktakehomepay.co.uk/docs/api/payroll-period).
-   Handle failures: [Errors](https://checktakehomepay.co.uk/docs/errors).