Last updated 9 October 2026View as Markdown

Take-home pay

POST /v1/take-home Needs a key

Gross pay to take-home over a tax year, each pay period run the way payroll runs it: income tax (Scottish and Welsh rates too), NI, student loans, pensions, salary sacrifice, childcare vouchers, benefits in kind, bonus, overtime, Marriage Allowance and the High Income Child Benefit Charge. Returns every period, each payslip, tax by band and the effective and marginal rates.

Request

A JSON body. Fields not listed here are rejected.

Field	Type	Description
`gross` required	object	Gross pay: { amount, per } with per as year, month, four_weeks, two_weeks, week, day or hour.
`gross.amount` required in gross	number	Pounds and pence. Allowed: 0 or more, under 100,000,000.
`gross.per` required in gross	string	The period the amount is for. One of `year`, `month`, `four_weeks`, `two_weeks`, `week`, `day`, `hour`.
`tax_year` optional	string	The tax year, such as 2026-27. The latest when not given. Default `"2026-27"`.
`region` optional	string	Where the employee lives: england, scotland, wales or northern_ireland. Needed unless tax_code is given (its S or C prefix sets the region). One of `england`, `scotland`, `wales`, `northern_ireland`.
`pay_frequency` optional	string	How often they are paid: monthly (when not given), four_weekly, two_weekly or weekly. Each period runs through payroll. One of `monthly`, `four_weekly`, `two_weekly`, `weekly`. Default `"monthly"`.
`working_pattern` optional	object	Days and hours a week and weeks a year, for amounts per day or hour: 5 days, 37.5 hours and 52 weeks when not given.
`working_pattern.days_per_week` optional	number	Days worked a week: 5 when not given. Allowed: more than 0, up to 7. Default `5`.
`working_pattern.hours_per_week` optional	number	Hours worked a week: 37.5 when not given. Allowed: more than 0, up to 168. Default `37.5`.
`working_pattern.weeks_per_year` optional	number	Weeks paid a year: 52 when not given. Allowed: 1 to 53. Default `52`.
`tax_code` optional	string	Their tax code, such as 1257L, S1257L, K475, BR, D0, NT or 0T, with W1 or M1 for the week 1/month 1 basis. Worked out from the income when not given.
`ni_category` optional	string	National Insurance category letter: A when not given, C over State Pension age. One of `A`, `B`, `C`, `D`, `E`, `F`, `H`, `I`, `J`, `K`, `L`, `M`, `N`, `S`, `V`, `Z`. Default `"A"`.
`student_loans` optional	array of string	Each loan they repay: plan_1, plan_2, plan_4, plan_5, postgraduate. One of `plan_1`, `plan_2`, `plan_4`, `plan_5`, `postgraduate`.
`pension` optional	object	Their pension contribution: method (relief_at_source, net_pay or salary_sacrifice) with a percent (of pay, or of qualifying_earnings as basis) or a fixed amount.
`pension.method` required in pension	string	How the contribution is taken: relief_at_source, net_pay or salary_sacrifice. One of `relief_at_source`, `net_pay`, `salary_sacrifice`.
`pension.percent` optional	number	A percentage of pensionable pay. Allowed: 0 to 100.
`pension.basis` optional	string	Pensionable pay: all of it (pay), or only automatic enrolment qualifying earnings. Pay when not given. One of `pay`, `qualifying_earnings`.
`pension.includes` optional	array of string	Pay besides salary that is pensionable: overtime, allowances, bonus. One of `overtime`, `allowances`, `bonus`.
`pension.amount` optional	object	A fixed contribution instead of a percent.
`pension.amount.amount` required in pension.amount	number	Pounds and pence. Allowed: 0 or more, under 100,000,000.
`pension.amount.per` required in pension.amount	string	The period the amount is for. One of `year`, `month`, `four_weeks`, `two_weeks`, `week`, `day`, `hour`.
`employer_pension` optional	string or object	The employer's contribution, on top of pay: auto_enrolment_minimum (3% of qualifying earnings), or a percent or amount.
`employer_pension.percent` optional	number	A percentage of pensionable pay. Allowed: 0 to 100.
`employer_pension.basis` optional	string	Pensionable pay: all of it (pay), or only automatic enrolment qualifying earnings. Pay when not given. One of `pay`, `qualifying_earnings`.
`employer_pension.includes` optional	array of string	Pay besides salary that is pensionable: overtime, allowances, bonus. One of `overtime`, `allowances`, `bonus`.
`employer_pension.amount` optional	object	A fixed contribution instead of a percent.
`employer_pension.amount.amount` required in employer_pension.amount	number	Pounds and pence. Allowed: 0 or more, under 100,000,000.
`employer_pension.amount.per` required in employer_pension.amount	string	The period the amount is for. One of `year`, `month`, `four_weeks`, `two_weeks`, `week`, `day`, `hour`.
`overtime` optional	array of object	Overtime: amounts per period, or hours at a multiple of the hourly rate per period.
`overtime[].amount` optional	number	Pounds and pence. Allowed: 0 or more, under 100,000,000.
`overtime[].per` required in overtime	string	The period the amount or hours are for. One of `year`, `month`, `four_weeks`, `two_weeks`, `week`, `day`, `hour`.
`overtime[].hours` optional	number	Overtime hours. Allowed: 0 to 168.
`overtime[].multiplier` optional	number	Times the salary's hourly rate: 1.5 for time and a half. Allowed: 0 to 10.
`allowances` optional	object	Cash allowances, taxed and NI'd like salary.
`allowances.amount` required in allowances	number	Pounds and pence. Allowed: 0 or more, under 100,000,000.
`allowances.per` required in allowances	string	The period the amount is for. One of `year`, `month`, `four_weeks`, `two_weeks`, `week`, `day`, `hour`.
`bonus` optional	object	A one-off bonus, paid in pay_period (the last pay period of the year when not given).
`bonus.amount` required in bonus	number	The bonus, in pounds and pence. Allowed: 0 or more, under 100,000,000.
`bonus.pay_period` optional	integer	The pay period it is paid in: 1 is the first of the tax year. Allowed: 1 to 52.
`salary_sacrifice` optional	object	Salary given up for something other than a pension: free of tax and NI.
`salary_sacrifice.amount` required in salary_sacrifice	number	Pounds and pence. Allowed: 0 or more, under 100,000,000.
`salary_sacrifice.per` required in salary_sacrifice	string	The period the amount is for. One of `year`, `month`, `four_weeks`, `two_weeks`, `week`, `day`, `hour`.
`benefits_in_kind` optional	object	Taxable benefits in kind, collected through the tax code.
`benefits_in_kind.amount` required in benefits_in_kind	number	Pounds and pence. Allowed: 0 or more, under 100,000,000.
`benefits_in_kind.per` required in benefits_in_kind	string	The period the amount is for. One of `year`, `month`, `four_weeks`, `two_weeks`, `week`, `day`, `hour`.
`childcare_vouchers` optional	object	Childcare vouchers taken from pay; joined_before_2011 gives the old scheme’s basic rate exempt amount.
`childcare_vouchers.amount` required in childcare_vouchers	number	Pounds and pence. Allowed: 0 or more, under 100,000,000.
`childcare_vouchers.per` required in childcare_vouchers	string	The period the amount is for. One of `year`, `month`, `four_weeks`, `two_weeks`, `week`, `day`, `hour`.
`childcare_vouchers.joined_before_2011` optional	boolean	Joined the scheme before 6 April 2011.
`pre_tax_deductions` optional	object	Deductions before tax but after NI, such as payroll giving.
`pre_tax_deductions.amount` required in pre_tax_deductions	number	Pounds and pence. Allowed: 0 or more, under 100,000,000.
`pre_tax_deductions.per` required in pre_tax_deductions	string	The period the amount is for. One of `year`, `month`, `four_weeks`, `two_weeks`, `week`, `day`, `hour`.
`post_tax_deductions` optional	object	Deductions from net pay.
`post_tax_deductions.amount` required in post_tax_deductions	number	Pounds and pence. Allowed: 0 or more, under 100,000,000.
`post_tax_deductions.per` required in post_tax_deductions	string	The period the amount is for. One of `year`, `month`, `four_weeks`, `two_weeks`, `week`, `day`, `hour`.
`blind` optional	boolean	Blind Person's Allowance.
`marriage_allowance` optional	string	Marriage Allowance: transferring or receiving. One of `transferring`, `receiving`.
`married_couples_allowance` optional	boolean	Claims Married Couple's Allowance (one of the couple born before 6 April 1935).
`child_benefit` optional	object	Child Benefit in the household, for the High Income Child Benefit Charge: the children, and the weeks of the year it is paid (all of them when not given).
`child_benefit.children` required in child_benefit	integer	Children Child Benefit is paid for. Allowed: 1 to 20.
`child_benefit.weeks` optional	integer	Weeks of the tax year it is paid for: all of them when not given. Allowed: 1 to 53.

Example

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

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",
  "tax_code": "1257L",
  "tax_code_derived": true,
  "tax_region": "rest_of_uk",
  "pay_frequency": "monthly",
  "personal_allowance": 12570,
  "adjusted_net_income": 43062,
  "benefits_in_kind": 0,
  "married_couples_allowance": 0,
  "childcare_voucher_band": null,
  "child_benefit": null,
  "periods": {
    "year": {
      "gross": 45000,
      "salary_sacrifice": 0,
      "childcare_vouchers": 0,
      "pension": 1938,
      "pension_contribution": 1938,
      "employer_pension": 0,
      "pre_tax_deductions": 0,
      "niable_pay": 43062,
      "taxable_pay": 43062,
      "tax": 6096.4,
      "employee_ni": 2438.88,
      "employer_ni": 5708.64,
      "student_loans": {
        "plan_2": 1224
      },
      "post_tax_deductions": 0,
      "take_home": 33302.72
    },
    "month": {
      "gross": 3750,
      "salary_sacrifice": 0,
      "childcare_vouchers": 0,
      "pension": 161.5,
      "pension_contribution": 161.5,
      "employer_pension": 0,
      "pre_tax_deductions": 0,
      "niable_pay": 3588.5,
      "taxable_pay": 3588.5,
      "tax": 508.03,
      "employee_ni": 203.24,
      "employer_ni": 475.72,
      "student_loans": {
        "plan_2": 102
      },
      "post_tax_deductions": 0,
      "take_home": 2775.23
    },
    "four_weeks": {
      "gross": 3461.54,
      "salary_sacrifice": 0,
      "childcare_vouchers": 0,
      "pension": 149.08,
      "pension_contribution": 149.08,
      "employer_pension": 0,
      "pre_tax_deductions": 0,
      "niable_pay": 3312.46,
      "taxable_pay": 3312.46,
      "tax": 468.95,
      "employee_ni": 187.61,
      "employer_ni": 439.13,
      "student_loans": {
        "plan_2": 94.15
      },
      "post_tax_deductions": 0,
      "take_home": 2561.75
    },
    "two_weeks": {
      "gross": 1730.77,
      "salary_sacrifice": 0,
      "childcare_vouchers": 0,
      "pension": 74.54,
      "pension_contribution": 74.54,
      "employer_pension": 0,
      "pre_tax_deductions": 0,
      "niable_pay": 1656.23,
      "taxable_pay": 1656.23,
      "tax": 234.48,
      "employee_ni": 93.8,
      "employer_ni": 219.56,
      "student_loans": {
        "plan_2": 47.08
      },
      "post_tax_deductions": 0,
      "take_home": 1280.87
    },
    "week": {
      "gross": 865.38,
      "salary_sacrifice": 0,
      "childcare_vouchers": 0,
      "pension": 37.27,
      "pension_contribution": 37.27,
      "employer_pension": 0,
      "pre_tax_deductions": 0,
      "niable_pay": 828.12,
      "taxable_pay": 828.12,
      "tax": 117.24,
      "employee_ni": 46.9,
      "employer_ni": 109.78,
      "student_loans": {
        "plan_2": 23.54
      },
      "post_tax_deductions": 0,
      "take_home": 640.44
    },
    "day": {
      "gross": 173.08,
      "salary_sacrifice": 0,
      "childcare_vouchers": 0,
      "pension": 7.45,
      "pension_contribution": 7.45,
      "employer_pension": 0,
      "pre_tax_deductions": 0,
      "niable_pay": 165.62,
      "taxable_pay": 165.62,
      "tax": 23.45,
      "employee_ni": 9.38,
      "employer_ni": 21.96,
      "student_loans": {
        "plan_2": 4.71
      },
      "post_tax_deductions": 0,
      "take_home": 128.09
    },
    "hour": {
      "gross": 23.08,
      "salary_sacrifice": 0,
      "childcare_vouchers": 0,
      "pension": 0.99,
      "pension_contribution": 0.99,
      "employer_pension": 0,
      "pre_tax_deductions": 0,
      "niable_pay": 22.08,
      "taxable_pay": 22.08,
      "tax": 3.13,
      "employee_ni": 1.25,
      "employer_ni": 2.93,
      "student_loans": {
        "plan_2": 0.63
      },
      "post_tax_deductions": 0,
      "take_home": 17.08
    }
  },
  "payslips": [
    {
      "period": 1,
      "gross": 3750,
      "salary_sacrifice": 0,
      "childcare_vouchers": 0,
      "pension": 161.5,
      "pension_contribution": 161.5,
      "employer_pension": 0,
      "pre_tax_deductions": 0,
      "niable_pay": 3588.5,
      "taxable_pay": 3588.5,
      "tax": 508,
      "employee_ni": 203.24,
      "employer_ni": 475.72,
      "student_loans": {
        "plan_2": 102
      },
      "post_tax_deductions": 0,
      "take_home": 2775.26
    },
    {
      "period": 2,
      "gross": 3750,
      "salary_sacrifice": 0,
      "childcare_vouchers": 0,
      "pension": 161.5,
      "pension_contribution": 161.5,
      "employer_pension": 0,
      "pre_tax_deductions": 0,
      "niable_pay": 3588.5,
      "taxable_pay": 3588.5,
      "tax": 508,
      "employee_ni": 203.24,
      "employer_ni": 475.72,
      "student_loans": {
        "plan_2": 102
      },
      "post_tax_deductions": 0,
      "take_home": 2775.26
    },
    {
      "period": 3,
      "gross": 3750,
      "salary_sacrifice": 0,
      "childcare_vouchers": 0,
      "pension": 161.5,
      "pension_contribution": 161.5,
      "employer_pension": 0,
      "pre_tax_deductions": 0,
      "niable_pay": 3588.5,
      "taxable_pay": 3588.5,
      "tax": 508,
      "employee_ni": 203.24,
      "employer_ni": 475.72,
      "student_loans": {
        "plan_2": 102
      },
      "post_tax_deductions": 0,
      "take_home": 2775.26
    },
    {
      "period": 4,
      "gross": 3750,
      "salary_sacrifice": 0,
      "childcare_vouchers": 0,
      "pension": 161.5,
      "pension_contribution": 161.5,
      "employer_pension": 0,
      "pre_tax_deductions": 0,
      "niable_pay": 3588.5,
      "taxable_pay": 3588.5,
      "tax": 508,
      "employee_ni": 203.24,
      "employer_ni": 475.72,
      "student_loans": {
        "plan_2": 102
      },
      "post_tax_deductions": 0,
      "take_home": 2775.26
    },
    {
      "period": 5,
      "gross": 3750,
      "salary_sacrifice": 0,
      "childcare_vouchers": 0,
      "pension": 161.5,
      "pension_contribution": 161.5,
      "employer_pension": 0,
      "pre_tax_deductions": 0,
      "niable_pay": 3588.5,
      "taxable_pay": 3588.5,
      "tax": 508.2,
      "employee_ni": 203.24,
      "employer_ni": 475.72,
      "student_loans": {
        "plan_2": 102
      },
      "post_tax_deductions": 0,
      "take_home": 2775.06
    },
    {
      "period": 6,
      "gross": 3750,
      "salary_sacrifice": 0,
      "childcare_vouchers": 0,
      "pension": 161.5,
      "pension_contribution": 161.5,
      "employer_pension": 0,
      "pre_tax_deductions": 0,
      "niable_pay": 3588.5,
      "taxable_pay": 3588.5,
      "tax": 508,
      "employee_ni": 203.24,
      "employer_ni": 475.72,
      "student_loans": {
        "plan_2": 102
      },
      "post_tax_deductions": 0,
      "take_home": 2775.26
    },
    {
      "period": 7,
      "gross": 3750,
      "salary_sacrifice": 0,
      "childcare_vouchers": 0,
      "pension": 161.5,
      "pension_contribution": 161.5,
      "employer_pension": 0,
      "pre_tax_deductions": 0,
      "niable_pay": 3588.5,
      "taxable_pay": 3588.5,
      "tax": 508,
      "employee_ni": 203.24,
      "employer_ni": 475.72,
      "student_loans": {
        "plan_2": 102
      },
      "post_tax_deductions": 0,
      "take_home": 2775.26
    },
    {
      "period": 8,
      "gross": 3750,
      "salary_sacrifice": 0,
      "childcare_vouchers": 0,
      "pension": 161.5,
      "pension_contribution": 161.5,
      "employer_pension": 0,
      "pre_tax_deductions": 0,
      "niable_pay": 3588.5,
      "taxable_pay": 3588.5,
      "tax": 508,
      "employee_ni": 203.24,
      "employer_ni": 475.72,
      "student_loans": {
        "plan_2": 102
      },
      "post_tax_deductions": 0,
      "take_home": 2775.26
    },
    {
      "period": 9,
      "gross": 3750,
      "salary_sacrifice": 0,
      "childcare_vouchers": 0,
      "pension": 161.5,
      "pension_contribution": 161.5,
      "employer_pension": 0,
      "pre_tax_deductions": 0,
      "niable_pay": 3588.5,
      "taxable_pay": 3588.5,
      "tax": 508.2,
      "employee_ni": 203.24,
      "employer_ni": 475.72,
      "student_loans": {
        "plan_2": 102
      },
      "post_tax_deductions": 0,
      "take_home": 2775.06
    },
    {
      "period": 10,
      "gross": 3750,
      "salary_sacrifice": 0,
      "childcare_vouchers": 0,
      "pension": 161.5,
      "pension_contribution": 161.5,
      "employer_pension": 0,
      "pre_tax_deductions": 0,
      "niable_pay": 3588.5,
      "taxable_pay": 3588.5,
      "tax": 508,
      "employee_ni": 203.24,
      "employer_ni": 475.72,
      "student_loans": {
        "plan_2": 102
      },
      "post_tax_deductions": 0,
      "take_home": 2775.26
    },
    {
      "period": 11,
      "gross": 3750,
      "salary_sacrifice": 0,
      "childcare_vouchers": 0,
      "pension": 161.5,
      "pension_contribution": 161.5,
      "employer_pension": 0,
      "pre_tax_deductions": 0,
      "niable_pay": 3588.5,
      "taxable_pay": 3588.5,
      "tax": 508,
      "employee_ni": 203.24,
      "employer_ni": 475.72,
      "student_loans": {
        "plan_2": 102
      },
      "post_tax_deductions": 0,
      "take_home": 2775.26
    },
    {
      "period": 12,
      "gross": 3750,
      "salary_sacrifice": 0,
      "childcare_vouchers": 0,
      "pension": 161.5,
      "pension_contribution": 161.5,
      "employer_pension": 0,
      "pre_tax_deductions": 0,
      "niable_pay": 3588.5,
      "taxable_pay": 3588.5,
      "tax": 508,
      "employee_ni": 203.24,
      "employer_ni": 475.72,
      "student_loans": {
        "plan_2": 102
      },
      "post_tax_deductions": 0,
      "take_home": 2775.26
    }
  ],
  "tax_bands": [
    {
      "rate": 20,
      "taxable": 30482,
      "tax": 6096.4
    }
  ],
  "rates": {
    "effective": 21.69,
    "marginal": 35
  },
  "assumptions": [
    "Pay is the same in every pay period, apart from any bonus, and each period runs through payroll with a cumulative tax code unless the code says week 1/month 1.",
    "A bonus without a pay_period is paid in the last pay period of the year.",
    "periods other than the year are the year divided evenly, so they show an average period, not one payslip.",
    "rates.effective and rates.marginal count income tax, employee NI and student loans; rates.marginal is on the next £1,000 of salary.",
    "The tax code is the one HMRC would issue for this income from the start of the year: the personal allowance after its taper, less benefits in kind, plus any allowances asked for."
  ],
  "sources": [
    "https://www.gov.uk/government/publications/payroll-technical-specifications-income-tax",
    "https://www.gov.uk/government/publications/payroll-technical-specifications-national-insurance",
    "https://www.gov.uk/government/publications/payroll-technical-specifications-student-loans/collection-of-student-loans-from-6-april-2026",
    "https://www.gov.uk/income-tax-rates",
    "https://www.gov.uk/marriage-allowance",
    "https://www.litrg.org.uk/tax-and-nic/income-tax/tax-allowances/blind-persons-allowance",
    "https://www.gov.uk/government/publications/software-developers-payroll-test-data-2026-to-2027"
  ]
}

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.