Last updated 9 October 2026View as Markdown

Quickstart

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

1. Get a key

Calculations need a key. Sign up, 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 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()

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 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"
}'

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

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.

5. Next steps

Need a salary from a take-home figure? Gross from net.
Costing a hire? Employer cost.
Running payroll? One pay period.
Handle failures: Errors.