{"openapi":"3.1.0","info":{"title":"Check Take Home Pay API","version":"1.0.0","description":"UK pay and employment calculations: take-home pay, gross from net, employer cost, payroll periods, statutory pay, entitlements and contractors. Money is pounds with two decimals, worked out in pence the way payroll does; every response says which tax year, engine and HMRC test data produced it."},"servers":[{"url":"https://api.checktakehomepay.co.uk"}],"security":[{"bearer":[]}],"tags":[{"name":"Employee pay"},{"name":"Payroll"},{"name":"Statutory pay"},{"name":"Entitlements"},{"name":"Contractors"},{"name":"Reference data"}],"paths":{"/v1/take-home":{"post":{"operationId":"takeHome","tags":["Employee pay"],"summary":"Take-home pay","description":"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.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"tax_year":{"type":"string","default":"2026-27","description":"The tax year, such as 2026-27. The latest when not given."},"region":{"type":"string","enum":["england","scotland","wales","northern_ireland"],"description":"Where the employee lives: england, scotland, wales or northern_ireland. Needed unless tax_code is given (its S or C prefix sets the region)."},"pay_frequency":{"type":"string","enum":["monthly","four_weekly","two_weekly","weekly"],"default":"monthly","description":"How often they are paid: monthly (when not given), four_weekly, two_weekly or weekly. Each period runs through payroll."},"working_pattern":{"type":"object","properties":{"days_per_week":{"type":"number","exclusiveMinimum":0,"maximum":7,"default":5,"description":"Days worked a week: 5 when not given."},"hours_per_week":{"type":"number","exclusiveMinimum":0,"maximum":168,"default":37.5,"description":"Hours worked a week: 37.5 when not given."},"weeks_per_year":{"type":"number","minimum":1,"maximum":53,"default":52,"description":"Weeks paid a year: 52 when not given."}},"additionalProperties":false,"description":"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."},"tax_code":{"type":"string","maxLength":20,"description":"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":{"type":"string","enum":["A","B","C","D","E","F","H","I","J","K","L","M","N","S","V","Z"],"default":"A","description":"National Insurance category letter: A when not given, C over State Pension age."},"student_loans":{"type":"array","items":{"type":"string","enum":["plan_1","plan_2","plan_4","plan_5","postgraduate"]},"description":"Each loan they repay: plan_1, plan_2, plan_4, plan_5, postgraduate."},"pension":{"type":"object","properties":{"method":{"type":"string","enum":["relief_at_source","net_pay","salary_sacrifice"],"description":"How the contribution is taken: relief_at_source, net_pay or salary_sacrifice."},"percent":{"type":"number","minimum":0,"maximum":100,"description":"A percentage of pensionable pay."},"basis":{"type":"string","enum":["pay","qualifying_earnings"],"description":"Pensionable pay: all of it (pay), or only automatic enrolment qualifying earnings. Pay when not given."},"includes":{"type":"array","items":{"type":"string","enum":["overtime","allowances","bonus"]},"description":"Pay besides salary that is pensionable: overtime, allowances, bonus."},"amount":{"type":"object","properties":{"amount":{"type":"number","minimum":0,"exclusiveMaximum":100000000,"description":"Pounds and pence."},"per":{"type":"string","enum":["year","month","four_weeks","two_weeks","week","day","hour"],"description":"The period the amount is for."}},"required":["amount","per"],"additionalProperties":false,"description":"A fixed contribution instead of a percent."}},"required":["method"],"additionalProperties":false,"description":"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."},"employer_pension":{"anyOf":[{"type":"string","const":"auto_enrolment_minimum"},{"type":"object","properties":{"percent":{"type":"number","minimum":0,"maximum":100,"description":"A percentage of pensionable pay."},"basis":{"type":"string","enum":["pay","qualifying_earnings"],"description":"Pensionable pay: all of it (pay), or only automatic enrolment qualifying earnings. Pay when not given."},"includes":{"type":"array","items":{"type":"string","enum":["overtime","allowances","bonus"]},"description":"Pay besides salary that is pensionable: overtime, allowances, bonus."},"amount":{"type":"object","properties":{"amount":{"type":"number","minimum":0,"exclusiveMaximum":100000000,"description":"Pounds and pence."},"per":{"type":"string","enum":["year","month","four_weeks","two_weeks","week","day","hour"],"description":"The period the amount is for."}},"required":["amount","per"],"additionalProperties":false,"description":"A fixed contribution instead of a percent."}},"additionalProperties":false}],"description":"The employer's contribution, on top of pay: auto_enrolment_minimum (3% of qualifying earnings), or a percent or amount."},"overtime":{"type":"array","items":{"anyOf":[{"type":"object","properties":{"amount":{"type":"number","minimum":0,"exclusiveMaximum":100000000,"description":"Pounds and pence."},"per":{"type":"string","enum":["year","month","four_weeks","two_weeks","week","day","hour"],"description":"The period the amount is for."}},"required":["amount","per"],"additionalProperties":false},{"type":"object","properties":{"hours":{"type":"number","minimum":0,"maximum":168,"description":"Overtime hours."},"multiplier":{"type":"number","minimum":0,"maximum":10,"description":"Times the salary's hourly rate: 1.5 for time and a half."},"per":{"type":"string","enum":["year","month","four_weeks","two_weeks","week","day","hour"],"description":"The period the amount or hours are for."}},"required":["hours","multiplier","per"],"additionalProperties":false}]},"maxItems":20,"description":"Overtime: amounts per period, or hours at a multiple of the hourly rate per period."},"allowances":{"type":"object","properties":{"amount":{"type":"number","minimum":0,"exclusiveMaximum":100000000,"description":"Pounds and pence."},"per":{"type":"string","enum":["year","month","four_weeks","two_weeks","week","day","hour"],"description":"The period the amount is for."}},"required":["amount","per"],"additionalProperties":false,"description":"Cash allowances, taxed and NI'd like salary."},"bonus":{"type":"object","properties":{"amount":{"type":"number","minimum":0,"exclusiveMaximum":100000000,"description":"The bonus, in pounds and pence."},"pay_period":{"type":"integer","minimum":1,"maximum":52,"description":"The pay period it is paid in: 1 is the first of the tax year."}},"required":["amount"],"additionalProperties":false,"description":"A one-off bonus, paid in pay_period (the last pay period of the year when not given)."},"salary_sacrifice":{"type":"object","properties":{"amount":{"type":"number","minimum":0,"exclusiveMaximum":100000000,"description":"Pounds and pence."},"per":{"type":"string","enum":["year","month","four_weeks","two_weeks","week","day","hour"],"description":"The period the amount is for."}},"required":["amount","per"],"additionalProperties":false,"description":"Salary given up for something other than a pension: free of tax and NI."},"benefits_in_kind":{"type":"object","properties":{"amount":{"type":"number","minimum":0,"exclusiveMaximum":100000000,"description":"Pounds and pence."},"per":{"type":"string","enum":["year","month","four_weeks","two_weeks","week","day","hour"],"description":"The period the amount is for."}},"required":["amount","per"],"additionalProperties":false,"description":"Taxable benefits in kind, collected through the tax code."},"childcare_vouchers":{"type":"object","properties":{"amount":{"type":"number","minimum":0,"exclusiveMaximum":100000000,"description":"Pounds and pence."},"per":{"type":"string","enum":["year","month","four_weeks","two_weeks","week","day","hour"],"description":"The period the amount is for."},"joined_before_2011":{"type":"boolean","description":"Joined the scheme before 6 April 2011."}},"required":["amount","per"],"additionalProperties":false,"description":"Childcare vouchers taken from pay; joined_before_2011 gives the old scheme’s basic rate exempt amount."},"pre_tax_deductions":{"type":"object","properties":{"amount":{"type":"number","minimum":0,"exclusiveMaximum":100000000,"description":"Pounds and pence."},"per":{"type":"string","enum":["year","month","four_weeks","two_weeks","week","day","hour"],"description":"The period the amount is for."}},"required":["amount","per"],"additionalProperties":false,"description":"Deductions before tax but after NI, such as payroll giving."},"post_tax_deductions":{"type":"object","properties":{"amount":{"type":"number","minimum":0,"exclusiveMaximum":100000000,"description":"Pounds and pence."},"per":{"type":"string","enum":["year","month","four_weeks","two_weeks","week","day","hour"],"description":"The period the amount is for."}},"required":["amount","per"],"additionalProperties":false,"description":"Deductions from net pay."},"blind":{"type":"boolean","description":"Blind Person's Allowance."},"marriage_allowance":{"type":"string","enum":["transferring","receiving"],"description":"Marriage Allowance: transferring or receiving."},"married_couples_allowance":{"type":"boolean","description":"Claims Married Couple's Allowance (one of the couple born before 6 April 1935)."},"child_benefit":{"type":"object","properties":{"children":{"type":"integer","minimum":1,"maximum":20,"description":"Children Child Benefit is paid for."},"weeks":{"type":"integer","minimum":1,"maximum":53,"description":"Weeks of the tax year it is paid for: all of them when not given."}},"required":["children"],"additionalProperties":false,"description":"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)."},"gross":{"type":"object","properties":{"amount":{"type":"number","minimum":0,"exclusiveMaximum":100000000,"description":"Pounds and pence."},"per":{"type":"string","enum":["year","month","four_weeks","two_weeks","week","day","hour"],"description":"The period the amount is for."}},"required":["amount","per"],"additionalProperties":false,"description":"Gross pay: { amount, per } with per as year, month, four_weeks, two_weeks, week, day or hour."}},"required":["gross"],"additionalProperties":false},"example":{"gross":{"amount":45000,"per":"year"},"region":"england","student_loans":["plan_2"],"pension":{"method":"salary_sacrifice","percent":5,"basis":"qualifying_earnings"},"pay_frequency":"monthly"}}}},"responses":{"200":{"description":"The result, with what produced it, the assumptions and the sources.","content":{"application/json":{"schema":{"type":"object","properties":{"tax_year":{"type":"string"},"engine":{"type":"string"},"hmrc_test_data":{"type":"string"},"tax_code":{"type":"string"},"tax_code_derived":{"type":"boolean"},"tax_region":{"type":"string"},"pay_frequency":{"type":"string"},"personal_allowance":{"type":"number"},"adjusted_net_income":{"type":"number"},"benefits_in_kind":{"type":"number"},"married_couples_allowance":{"type":"number"},"childcare_voucher_band":{"type":["string","null"]},"child_benefit":{"type":["object","null"],"properties":{"amount":{"type":"number"},"high_income_charge":{"type":"number"}}},"periods":{"type":"object","properties":{"year":{"type":"object","properties":{"gross":{"type":"number"},"salary_sacrifice":{"type":"number"},"childcare_vouchers":{"type":"number"},"pension":{"type":"number"},"pension_contribution":{"type":"number"},"employer_pension":{"type":"number"},"pre_tax_deductions":{"type":"number"},"niable_pay":{"type":"number"},"taxable_pay":{"type":"number"},"tax":{"type":"number"},"employee_ni":{"type":"number"},"employer_ni":{"type":"number"},"student_loans":{"type":"object","properties":{"plan_2":{"type":"number"}}},"post_tax_deductions":{"type":"number"},"take_home":{"type":"number"}}},"month":{"type":"object","properties":{"gross":{"type":"number"},"salary_sacrifice":{"type":"number"},"childcare_vouchers":{"type":"number"},"pension":{"type":"number"},"pension_contribution":{"type":"number"},"employer_pension":{"type":"number"},"pre_tax_deductions":{"type":"number"},"niable_pay":{"type":"number"},"taxable_pay":{"type":"number"},"tax":{"type":"number"},"employee_ni":{"type":"number"},"employer_ni":{"type":"number"},"student_loans":{"type":"object","properties":{"plan_2":{"type":"number"}}},"post_tax_deductions":{"type":"number"},"take_home":{"type":"number"}}},"four_weeks":{"type":"object","properties":{"gross":{"type":"number"},"salary_sacrifice":{"type":"number"},"childcare_vouchers":{"type":"number"},"pension":{"type":"number"},"pension_contribution":{"type":"number"},"employer_pension":{"type":"number"},"pre_tax_deductions":{"type":"number"},"niable_pay":{"type":"number"},"taxable_pay":{"type":"number"},"tax":{"type":"number"},"employee_ni":{"type":"number"},"employer_ni":{"type":"number"},"student_loans":{"type":"object","properties":{"plan_2":{"type":"number"}}},"post_tax_deductions":{"type":"number"},"take_home":{"type":"number"}}},"two_weeks":{"type":"object","properties":{"gross":{"type":"number"},"salary_sacrifice":{"type":"number"},"childcare_vouchers":{"type":"number"},"pension":{"type":"number"},"pension_contribution":{"type":"number"},"employer_pension":{"type":"number"},"pre_tax_deductions":{"type":"number"},"niable_pay":{"type":"number"},"taxable_pay":{"type":"number"},"tax":{"type":"number"},"employee_ni":{"type":"number"},"employer_ni":{"type":"number"},"student_loans":{"type":"object","properties":{"plan_2":{"type":"number"}}},"post_tax_deductions":{"type":"number"},"take_home":{"type":"number"}}},"week":{"type":"object","properties":{"gross":{"type":"number"},"salary_sacrifice":{"type":"number"},"childcare_vouchers":{"type":"number"},"pension":{"type":"number"},"pension_contribution":{"type":"number"},"employer_pension":{"type":"number"},"pre_tax_deductions":{"type":"number"},"niable_pay":{"type":"number"},"taxable_pay":{"type":"number"},"tax":{"type":"number"},"employee_ni":{"type":"number"},"employer_ni":{"type":"number"},"student_loans":{"type":"object","properties":{"plan_2":{"type":"number"}}},"post_tax_deductions":{"type":"number"},"take_home":{"type":"number"}}},"day":{"type":"object","properties":{"gross":{"type":"number"},"salary_sacrifice":{"type":"number"},"childcare_vouchers":{"type":"number"},"pension":{"type":"number"},"pension_contribution":{"type":"number"},"employer_pension":{"type":"number"},"pre_tax_deductions":{"type":"number"},"niable_pay":{"type":"number"},"taxable_pay":{"type":"number"},"tax":{"type":"number"},"employee_ni":{"type":"number"},"employer_ni":{"type":"number"},"student_loans":{"type":"object","properties":{"plan_2":{"type":"number"}}},"post_tax_deductions":{"type":"number"},"take_home":{"type":"number"}}},"hour":{"type":"object","properties":{"gross":{"type":"number"},"salary_sacrifice":{"type":"number"},"childcare_vouchers":{"type":"number"},"pension":{"type":"number"},"pension_contribution":{"type":"number"},"employer_pension":{"type":"number"},"pre_tax_deductions":{"type":"number"},"niable_pay":{"type":"number"},"taxable_pay":{"type":"number"},"tax":{"type":"number"},"employee_ni":{"type":"number"},"employer_ni":{"type":"number"},"student_loans":{"type":"object","properties":{"plan_2":{"type":"number"}}},"post_tax_deductions":{"type":"number"},"take_home":{"type":"number"}}}}},"payslips":{"type":"array","items":{"type":"object","properties":{"period":{"type":"number"},"gross":{"type":"number"},"salary_sacrifice":{"type":"number"},"childcare_vouchers":{"type":"number"},"pension":{"type":"number"},"pension_contribution":{"type":"number"},"employer_pension":{"type":"number"},"pre_tax_deductions":{"type":"number"},"niable_pay":{"type":"number"},"taxable_pay":{"type":"number"},"tax":{"type":"number"},"employee_ni":{"type":"number"},"employer_ni":{"type":"number"},"student_loans":{"type":"object","properties":{"plan_2":{"type":"number"}}},"post_tax_deductions":{"type":"number"},"take_home":{"type":"number"}}}},"tax_bands":{"type":"array","items":{"type":"object","properties":{"rate":{"type":"number"},"taxable":{"type":"number"},"tax":{"type":"number"}}}},"rates":{"type":"object","properties":{"effective":{"type":"number"},"marginal":{"type":"number"}}},"assumptions":{"type":"array","items":{"type":"string"}},"sources":{"type":"array","items":{"type":"string"}}},"required":["tax_year","engine","hmrc_test_data","assumptions","sources"]},"example":{"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"]}}}},"400":{"description":"INVALID_INPUT: the message names each field that is wrong.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"UNAUTHENTICATED (no key) or INVALID_KEY (an unknown or revoked key).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"QUOTA_EXCEEDED: the free plan's calculations for the month are used; upgrade_url says where to get more.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"RATE_LIMITED: over the plan's calls a second; Retry-After says when to try again.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"UNAVAILABLE: keys can’t be checked right now; retry with backoff.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/gross-from-net":{"post":{"operationId":"grossFromNet","tags":["Employee pay"],"summary":"Gross from net","description":"The lowest gross salary whose take-home reaches a target, with the same options as take-home.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"tax_year":{"type":"string","default":"2026-27","description":"The tax year, such as 2026-27. The latest when not given."},"region":{"type":"string","enum":["england","scotland","wales","northern_ireland"],"description":"Where the employee lives: england, scotland, wales or northern_ireland. Needed unless tax_code is given (its S or C prefix sets the region)."},"pay_frequency":{"type":"string","enum":["monthly","four_weekly","two_weekly","weekly"],"default":"monthly","description":"How often they are paid: monthly (when not given), four_weekly, two_weekly or weekly. Each period runs through payroll."},"working_pattern":{"type":"object","properties":{"days_per_week":{"type":"number","exclusiveMinimum":0,"maximum":7,"default":5,"description":"Days worked a week: 5 when not given."},"hours_per_week":{"type":"number","exclusiveMinimum":0,"maximum":168,"default":37.5,"description":"Hours worked a week: 37.5 when not given."},"weeks_per_year":{"type":"number","minimum":1,"maximum":53,"default":52,"description":"Weeks paid a year: 52 when not given."}},"additionalProperties":false,"description":"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."},"tax_code":{"type":"string","maxLength":20,"description":"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":{"type":"string","enum":["A","B","C","D","E","F","H","I","J","K","L","M","N","S","V","Z"],"default":"A","description":"National Insurance category letter: A when not given, C over State Pension age."},"student_loans":{"type":"array","items":{"type":"string","enum":["plan_1","plan_2","plan_4","plan_5","postgraduate"]},"description":"Each loan they repay: plan_1, plan_2, plan_4, plan_5, postgraduate."},"pension":{"type":"object","properties":{"method":{"type":"string","enum":["relief_at_source","net_pay","salary_sacrifice"],"description":"How the contribution is taken: relief_at_source, net_pay or salary_sacrifice."},"percent":{"type":"number","minimum":0,"maximum":100,"description":"A percentage of pensionable pay."},"basis":{"type":"string","enum":["pay","qualifying_earnings"],"description":"Pensionable pay: all of it (pay), or only automatic enrolment qualifying earnings. Pay when not given."},"includes":{"type":"array","items":{"type":"string","enum":["overtime","allowances","bonus"]},"description":"Pay besides salary that is pensionable: overtime, allowances, bonus."},"amount":{"type":"object","properties":{"amount":{"type":"number","minimum":0,"exclusiveMaximum":100000000,"description":"Pounds and pence."},"per":{"type":"string","enum":["year","month","four_weeks","two_weeks","week","day","hour"],"description":"The period the amount is for."}},"required":["amount","per"],"additionalProperties":false,"description":"A fixed contribution instead of a percent."}},"required":["method"],"additionalProperties":false,"description":"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."},"employer_pension":{"anyOf":[{"type":"string","const":"auto_enrolment_minimum"},{"type":"object","properties":{"percent":{"type":"number","minimum":0,"maximum":100,"description":"A percentage of pensionable pay."},"basis":{"type":"string","enum":["pay","qualifying_earnings"],"description":"Pensionable pay: all of it (pay), or only automatic enrolment qualifying earnings. Pay when not given."},"includes":{"type":"array","items":{"type":"string","enum":["overtime","allowances","bonus"]},"description":"Pay besides salary that is pensionable: overtime, allowances, bonus."},"amount":{"type":"object","properties":{"amount":{"type":"number","minimum":0,"exclusiveMaximum":100000000,"description":"Pounds and pence."},"per":{"type":"string","enum":["year","month","four_weeks","two_weeks","week","day","hour"],"description":"The period the amount is for."}},"required":["amount","per"],"additionalProperties":false,"description":"A fixed contribution instead of a percent."}},"additionalProperties":false}],"description":"The employer's contribution, on top of pay: auto_enrolment_minimum (3% of qualifying earnings), or a percent or amount."},"overtime":{"type":"array","items":{"anyOf":[{"type":"object","properties":{"amount":{"type":"number","minimum":0,"exclusiveMaximum":100000000,"description":"Pounds and pence."},"per":{"type":"string","enum":["year","month","four_weeks","two_weeks","week","day","hour"],"description":"The period the amount is for."}},"required":["amount","per"],"additionalProperties":false},{"type":"object","properties":{"hours":{"type":"number","minimum":0,"maximum":168,"description":"Overtime hours."},"multiplier":{"type":"number","minimum":0,"maximum":10,"description":"Times the salary's hourly rate: 1.5 for time and a half."},"per":{"type":"string","enum":["year","month","four_weeks","two_weeks","week","day","hour"],"description":"The period the amount or hours are for."}},"required":["hours","multiplier","per"],"additionalProperties":false}]},"maxItems":20,"description":"Overtime: amounts per period, or hours at a multiple of the hourly rate per period."},"allowances":{"type":"object","properties":{"amount":{"type":"number","minimum":0,"exclusiveMaximum":100000000,"description":"Pounds and pence."},"per":{"type":"string","enum":["year","month","four_weeks","two_weeks","week","day","hour"],"description":"The period the amount is for."}},"required":["amount","per"],"additionalProperties":false,"description":"Cash allowances, taxed and NI'd like salary."},"bonus":{"type":"object","properties":{"amount":{"type":"number","minimum":0,"exclusiveMaximum":100000000,"description":"The bonus, in pounds and pence."},"pay_period":{"type":"integer","minimum":1,"maximum":52,"description":"The pay period it is paid in: 1 is the first of the tax year."}},"required":["amount"],"additionalProperties":false,"description":"A one-off bonus, paid in pay_period (the last pay period of the year when not given)."},"salary_sacrifice":{"type":"object","properties":{"amount":{"type":"number","minimum":0,"exclusiveMaximum":100000000,"description":"Pounds and pence."},"per":{"type":"string","enum":["year","month","four_weeks","two_weeks","week","day","hour"],"description":"The period the amount is for."}},"required":["amount","per"],"additionalProperties":false,"description":"Salary given up for something other than a pension: free of tax and NI."},"benefits_in_kind":{"type":"object","properties":{"amount":{"type":"number","minimum":0,"exclusiveMaximum":100000000,"description":"Pounds and pence."},"per":{"type":"string","enum":["year","month","four_weeks","two_weeks","week","day","hour"],"description":"The period the amount is for."}},"required":["amount","per"],"additionalProperties":false,"description":"Taxable benefits in kind, collected through the tax code."},"childcare_vouchers":{"type":"object","properties":{"amount":{"type":"number","minimum":0,"exclusiveMaximum":100000000,"description":"Pounds and pence."},"per":{"type":"string","enum":["year","month","four_weeks","two_weeks","week","day","hour"],"description":"The period the amount is for."},"joined_before_2011":{"type":"boolean","description":"Joined the scheme before 6 April 2011."}},"required":["amount","per"],"additionalProperties":false,"description":"Childcare vouchers taken from pay; joined_before_2011 gives the old scheme’s basic rate exempt amount."},"pre_tax_deductions":{"type":"object","properties":{"amount":{"type":"number","minimum":0,"exclusiveMaximum":100000000,"description":"Pounds and pence."},"per":{"type":"string","enum":["year","month","four_weeks","two_weeks","week","day","hour"],"description":"The period the amount is for."}},"required":["amount","per"],"additionalProperties":false,"description":"Deductions before tax but after NI, such as payroll giving."},"post_tax_deductions":{"type":"object","properties":{"amount":{"type":"number","minimum":0,"exclusiveMaximum":100000000,"description":"Pounds and pence."},"per":{"type":"string","enum":["year","month","four_weeks","two_weeks","week","day","hour"],"description":"The period the amount is for."}},"required":["amount","per"],"additionalProperties":false,"description":"Deductions from net pay."},"blind":{"type":"boolean","description":"Blind Person's Allowance."},"marriage_allowance":{"type":"string","enum":["transferring","receiving"],"description":"Marriage Allowance: transferring or receiving."},"married_couples_allowance":{"type":"boolean","description":"Claims Married Couple's Allowance (one of the couple born before 6 April 1935)."},"child_benefit":{"type":"object","properties":{"children":{"type":"integer","minimum":1,"maximum":20,"description":"Children Child Benefit is paid for."},"weeks":{"type":"integer","minimum":1,"maximum":53,"description":"Weeks of the tax year it is paid for: all of them when not given."}},"required":["children"],"additionalProperties":false,"description":"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)."},"target_take_home":{"type":"object","properties":{"amount":{"type":"number","minimum":0,"exclusiveMaximum":100000000,"description":"Pounds and pence."},"per":{"type":"string","enum":["year","month","four_weeks","two_weeks","week"],"description":"The period the amount is for."}},"required":["amount","per"],"additionalProperties":false,"description":"The take-home pay to reach: { amount, per } a year, month, four_weeks, two_weeks or week."}},"required":["target_take_home"],"additionalProperties":false},"example":{"region":"england","target_take_home":{"amount":3000,"per":"month"}}}}},"responses":{"200":{"description":"The result, with what produced it, the assumptions and the sources.","content":{"application/json":{"schema":{"type":"object","properties":{"tax_year":{"type":"string"},"engine":{"type":"string"},"hmrc_test_data":{"type":"string"},"gross":{"type":"number"},"tax_code":{"type":"string"},"tax_code_derived":{"type":"boolean"},"tax_region":{"type":"string"},"pay_frequency":{"type":"string"},"personal_allowance":{"type":"number"},"adjusted_net_income":{"type":"number"},"benefits_in_kind":{"type":"number"},"married_couples_allowance":{"type":"number"},"childcare_voucher_band":{},"child_benefit":{},"periods":{"type":"object","properties":{"year":{"type":"object","properties":{"gross":{"type":"number"},"salary_sacrifice":{"type":"number"},"childcare_vouchers":{"type":"number"},"pension":{"type":"number"},"pension_contribution":{"type":"number"},"employer_pension":{"type":"number"},"pre_tax_deductions":{"type":"number"},"niable_pay":{"type":"number"},"taxable_pay":{"type":"number"},"tax":{"type":"number"},"employee_ni":{"type":"number"},"employer_ni":{"type":"number"},"student_loans":{"type":"object","properties":{}},"post_tax_deductions":{"type":"number"},"take_home":{"type":"number"}}},"month":{"type":"object","properties":{"gross":{"type":"number"},"salary_sacrifice":{"type":"number"},"childcare_vouchers":{"type":"number"},"pension":{"type":"number"},"pension_contribution":{"type":"number"},"employer_pension":{"type":"number"},"pre_tax_deductions":{"type":"number"},"niable_pay":{"type":"number"},"taxable_pay":{"type":"number"},"tax":{"type":"number"},"employee_ni":{"type":"number"},"employer_ni":{"type":"number"},"student_loans":{"type":"object","properties":{}},"post_tax_deductions":{"type":"number"},"take_home":{"type":"number"}}},"four_weeks":{"type":"object","properties":{"gross":{"type":"number"},"salary_sacrifice":{"type":"number"},"childcare_vouchers":{"type":"number"},"pension":{"type":"number"},"pension_contribution":{"type":"number"},"employer_pension":{"type":"number"},"pre_tax_deductions":{"type":"number"},"niable_pay":{"type":"number"},"taxable_pay":{"type":"number"},"tax":{"type":"number"},"employee_ni":{"type":"number"},"employer_ni":{"type":"number"},"student_loans":{"type":"object","properties":{}},"post_tax_deductions":{"type":"number"},"take_home":{"type":"number"}}},"two_weeks":{"type":"object","properties":{"gross":{"type":"number"},"salary_sacrifice":{"type":"number"},"childcare_vouchers":{"type":"number"},"pension":{"type":"number"},"pension_contribution":{"type":"number"},"employer_pension":{"type":"number"},"pre_tax_deductions":{"type":"number"},"niable_pay":{"type":"number"},"taxable_pay":{"type":"number"},"tax":{"type":"number"},"employee_ni":{"type":"number"},"employer_ni":{"type":"number"},"student_loans":{"type":"object","properties":{}},"post_tax_deductions":{"type":"number"},"take_home":{"type":"number"}}},"week":{"type":"object","properties":{"gross":{"type":"number"},"salary_sacrifice":{"type":"number"},"childcare_vouchers":{"type":"number"},"pension":{"type":"number"},"pension_contribution":{"type":"number"},"employer_pension":{"type":"number"},"pre_tax_deductions":{"type":"number"},"niable_pay":{"type":"number"},"taxable_pay":{"type":"number"},"tax":{"type":"number"},"employee_ni":{"type":"number"},"employer_ni":{"type":"number"},"student_loans":{"type":"object","properties":{}},"post_tax_deductions":{"type":"number"},"take_home":{"type":"number"}}},"day":{"type":"object","properties":{"gross":{"type":"number"},"salary_sacrifice":{"type":"number"},"childcare_vouchers":{"type":"number"},"pension":{"type":"number"},"pension_contribution":{"type":"number"},"employer_pension":{"type":"number"},"pre_tax_deductions":{"type":"number"},"niable_pay":{"type":"number"},"taxable_pay":{"type":"number"},"tax":{"type":"number"},"employee_ni":{"type":"number"},"employer_ni":{"type":"number"},"student_loans":{"type":"object","properties":{}},"post_tax_deductions":{"type":"number"},"take_home":{"type":"number"}}},"hour":{"type":"object","properties":{"gross":{"type":"number"},"salary_sacrifice":{"type":"number"},"childcare_vouchers":{"type":"number"},"pension":{"type":"number"},"pension_contribution":{"type":"number"},"employer_pension":{"type":"number"},"pre_tax_deductions":{"type":"number"},"niable_pay":{"type":"number"},"taxable_pay":{"type":"number"},"tax":{"type":"number"},"employee_ni":{"type":"number"},"employer_ni":{"type":"number"},"student_loans":{"type":"object","properties":{}},"post_tax_deductions":{"type":"number"},"take_home":{"type":"number"}}}}},"payslips":{"type":"array","items":{"type":"object","properties":{"period":{"type":"number"},"gross":{"type":"number"},"salary_sacrifice":{"type":"number"},"childcare_vouchers":{"type":"number"},"pension":{"type":"number"},"pension_contribution":{"type":"number"},"employer_pension":{"type":"number"},"pre_tax_deductions":{"type":"number"},"niable_pay":{"type":"number"},"taxable_pay":{"type":"number"},"tax":{"type":"number"},"employee_ni":{"type":"number"},"employer_ni":{"type":"number"},"student_loans":{"type":"object","properties":{}},"post_tax_deductions":{"type":"number"},"take_home":{"type":"number"}}}},"tax_bands":{"type":"array","items":{"type":"object","properties":{"rate":{"type":"number"},"taxable":{"type":"number"},"tax":{"type":"number"}}}},"rates":{"type":"object","properties":{"effective":{"type":"number"},"marginal":{"type":"number"}}},"assumptions":{"type":"array","items":{"type":"string"}},"sources":{"type":"array","items":{"type":"string"}}},"required":["tax_year","engine","hmrc_test_data","assumptions","sources"]},"example":{"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","gross":45108.36,"tax_code":"1257L","tax_code_derived":true,"tax_region":"rest_of_uk","pay_frequency":"monthly","personal_allowance":12570,"adjusted_net_income":45108.36,"benefits_in_kind":0,"married_couples_allowance":0,"childcare_voucher_band":null,"child_benefit":null,"periods":{"year":{"gross":45108.36,"salary_sacrifice":0,"childcare_vouchers":0,"pension":0,"pension_contribution":0,"employer_pension":0,"pre_tax_deductions":0,"niable_pay":45108.36,"taxable_pay":45108.36,"tax":6505.8,"employee_ni":2602.56,"employer_ni":6015.6,"student_loans":{},"post_tax_deductions":0,"take_home":36000},"month":{"gross":3759.03,"salary_sacrifice":0,"childcare_vouchers":0,"pension":0,"pension_contribution":0,"employer_pension":0,"pre_tax_deductions":0,"niable_pay":3759.03,"taxable_pay":3759.03,"tax":542.15,"employee_ni":216.88,"employer_ni":501.3,"student_loans":{},"post_tax_deductions":0,"take_home":3000},"four_weeks":{"gross":3469.87,"salary_sacrifice":0,"childcare_vouchers":0,"pension":0,"pension_contribution":0,"employer_pension":0,"pre_tax_deductions":0,"niable_pay":3469.87,"taxable_pay":3469.87,"tax":500.45,"employee_ni":200.2,"employer_ni":462.74,"student_loans":{},"post_tax_deductions":0,"take_home":2769.23},"two_weeks":{"gross":1734.94,"salary_sacrifice":0,"childcare_vouchers":0,"pension":0,"pension_contribution":0,"employer_pension":0,"pre_tax_deductions":0,"niable_pay":1734.94,"taxable_pay":1734.94,"tax":250.22,"employee_ni":100.1,"employer_ni":231.37,"student_loans":{},"post_tax_deductions":0,"take_home":1384.62},"week":{"gross":867.47,"salary_sacrifice":0,"childcare_vouchers":0,"pension":0,"pension_contribution":0,"employer_pension":0,"pre_tax_deductions":0,"niable_pay":867.47,"taxable_pay":867.47,"tax":125.11,"employee_ni":50.05,"employer_ni":115.68,"student_loans":{},"post_tax_deductions":0,"take_home":692.31},"day":{"gross":173.49,"salary_sacrifice":0,"childcare_vouchers":0,"pension":0,"pension_contribution":0,"employer_pension":0,"pre_tax_deductions":0,"niable_pay":173.49,"taxable_pay":173.49,"tax":25.02,"employee_ni":10.01,"employer_ni":23.14,"student_loans":{},"post_tax_deductions":0,"take_home":138.46},"hour":{"gross":23.13,"salary_sacrifice":0,"childcare_vouchers":0,"pension":0,"pension_contribution":0,"employer_pension":0,"pre_tax_deductions":0,"niable_pay":23.13,"taxable_pay":23.13,"tax":3.34,"employee_ni":1.33,"employer_ni":3.08,"student_loans":{},"post_tax_deductions":0,"take_home":18.46}},"payslips":[{"period":1,"gross":3759.03,"salary_sacrifice":0,"childcare_vouchers":0,"pension":0,"pension_contribution":0,"employer_pension":0,"pre_tax_deductions":0,"niable_pay":3759.03,"taxable_pay":3759.03,"tax":542,"employee_ni":216.88,"employer_ni":501.3,"student_loans":{},"post_tax_deductions":0,"take_home":3000.15},{"period":2,"gross":3759.03,"salary_sacrifice":0,"childcare_vouchers":0,"pension":0,"pension_contribution":0,"employer_pension":0,"pre_tax_deductions":0,"niable_pay":3759.03,"taxable_pay":3759.03,"tax":542.2,"employee_ni":216.88,"employer_ni":501.3,"student_loans":{},"post_tax_deductions":0,"take_home":2999.95},{"period":3,"gross":3759.03,"salary_sacrifice":0,"childcare_vouchers":0,"pension":0,"pension_contribution":0,"employer_pension":0,"pre_tax_deductions":0,"niable_pay":3759.03,"taxable_pay":3759.03,"tax":542.2,"employee_ni":216.88,"employer_ni":501.3,"student_loans":{},"post_tax_deductions":0,"take_home":2999.95},{"period":4,"gross":3759.03,"salary_sacrifice":0,"childcare_vouchers":0,"pension":0,"pension_contribution":0,"employer_pension":0,"pre_tax_deductions":0,"niable_pay":3759.03,"taxable_pay":3759.03,"tax":542.2,"employee_ni":216.88,"employer_ni":501.3,"student_loans":{},"post_tax_deductions":0,"take_home":2999.95},{"period":5,"gross":3759.03,"salary_sacrifice":0,"childcare_vouchers":0,"pension":0,"pension_contribution":0,"employer_pension":0,"pre_tax_deductions":0,"niable_pay":3759.03,"taxable_pay":3759.03,"tax":542,"employee_ni":216.88,"employer_ni":501.3,"student_loans":{},"post_tax_deductions":0,"take_home":3000.15},{"period":6,"gross":3759.03,"salary_sacrifice":0,"childcare_vouchers":0,"pension":0,"pension_contribution":0,"employer_pension":0,"pre_tax_deductions":0,"niable_pay":3759.03,"taxable_pay":3759.03,"tax":542.2,"employee_ni":216.88,"employer_ni":501.3,"student_loans":{},"post_tax_deductions":0,"take_home":2999.95},{"period":7,"gross":3759.03,"salary_sacrifice":0,"childcare_vouchers":0,"pension":0,"pension_contribution":0,"employer_pension":0,"pre_tax_deductions":0,"niable_pay":3759.03,"taxable_pay":3759.03,"tax":542.2,"employee_ni":216.88,"employer_ni":501.3,"student_loans":{},"post_tax_deductions":0,"take_home":2999.95},{"period":8,"gross":3759.03,"salary_sacrifice":0,"childcare_vouchers":0,"pension":0,"pension_contribution":0,"employer_pension":0,"pre_tax_deductions":0,"niable_pay":3759.03,"taxable_pay":3759.03,"tax":542.2,"employee_ni":216.88,"employer_ni":501.3,"student_loans":{},"post_tax_deductions":0,"take_home":2999.95},{"period":9,"gross":3759.03,"salary_sacrifice":0,"childcare_vouchers":0,"pension":0,"pension_contribution":0,"employer_pension":0,"pre_tax_deductions":0,"niable_pay":3759.03,"taxable_pay":3759.03,"tax":542,"employee_ni":216.88,"employer_ni":501.3,"student_loans":{},"post_tax_deductions":0,"take_home":3000.15},{"period":10,"gross":3759.03,"salary_sacrifice":0,"childcare_vouchers":0,"pension":0,"pension_contribution":0,"employer_pension":0,"pre_tax_deductions":0,"niable_pay":3759.03,"taxable_pay":3759.03,"tax":542.2,"employee_ni":216.88,"employer_ni":501.3,"student_loans":{},"post_tax_deductions":0,"take_home":2999.95},{"period":11,"gross":3759.03,"salary_sacrifice":0,"childcare_vouchers":0,"pension":0,"pension_contribution":0,"employer_pension":0,"pre_tax_deductions":0,"niable_pay":3759.03,"taxable_pay":3759.03,"tax":542.2,"employee_ni":216.88,"employer_ni":501.3,"student_loans":{},"post_tax_deductions":0,"take_home":2999.95},{"period":12,"gross":3759.03,"salary_sacrifice":0,"childcare_vouchers":0,"pension":0,"pension_contribution":0,"employer_pension":0,"pre_tax_deductions":0,"niable_pay":3759.03,"taxable_pay":3759.03,"tax":542.2,"employee_ni":216.88,"employer_ni":501.3,"student_loans":{},"post_tax_deductions":0,"take_home":2999.95}],"tax_bands":[{"rate":20,"taxable":32529,"tax":6505.8}],"rates":{"effective":20.19,"marginal":28},"assumptions":["gross is the lowest salary a year whose take-home reaches the target over the year.","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"]}}}},"400":{"description":"INVALID_INPUT: the message names each field that is wrong.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"UNAUTHENTICATED (no key) or INVALID_KEY (an unknown or revoked key).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"QUOTA_EXCEEDED: the free plan's calculations for the month are used; upgrade_url says where to get more.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"RATE_LIMITED: over the plan's calls a second; Retry-After says when to try again.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"UNAVAILABLE: keys can’t be checked right now; retry with backoff.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/employer-cost":{"post":{"operationId":"employerCost","tags":["Employee pay"],"summary":"Employer cost","description":"What employing someone costs over a year: pay, employer NI less any Employment Allowance, Class 1A NI on benefits, the employer pension (including the auto-enrolment minimum) and the Apprenticeship Levy.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"tax_year":{"type":"string","default":"2026-27","description":"The tax year, such as 2026-27. The latest when not given."},"region":{"type":"string","enum":["england","scotland","wales","northern_ireland"],"description":"Where the employee lives: england, scotland, wales or northern_ireland. Needed unless tax_code is given (its S or C prefix sets the region)."},"pay_frequency":{"type":"string","enum":["monthly","four_weekly","two_weekly","weekly"],"default":"monthly","description":"How often they are paid: monthly (when not given), four_weekly, two_weekly or weekly. Each period runs through payroll."},"working_pattern":{"type":"object","properties":{"days_per_week":{"type":"number","exclusiveMinimum":0,"maximum":7,"default":5,"description":"Days worked a week: 5 when not given."},"hours_per_week":{"type":"number","exclusiveMinimum":0,"maximum":168,"default":37.5,"description":"Hours worked a week: 37.5 when not given."},"weeks_per_year":{"type":"number","minimum":1,"maximum":53,"default":52,"description":"Weeks paid a year: 52 when not given."}},"additionalProperties":false,"description":"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."},"tax_code":{"type":"string","maxLength":20,"description":"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":{"type":"string","enum":["A","B","C","D","E","F","H","I","J","K","L","M","N","S","V","Z"],"default":"A","description":"National Insurance category letter: A when not given, C over State Pension age."},"student_loans":{"type":"array","items":{"type":"string","enum":["plan_1","plan_2","plan_4","plan_5","postgraduate"]},"description":"Each loan they repay: plan_1, plan_2, plan_4, plan_5, postgraduate."},"pension":{"type":"object","properties":{"method":{"type":"string","enum":["relief_at_source","net_pay","salary_sacrifice"],"description":"How the contribution is taken: relief_at_source, net_pay or salary_sacrifice."},"percent":{"type":"number","minimum":0,"maximum":100,"description":"A percentage of pensionable pay."},"basis":{"type":"string","enum":["pay","qualifying_earnings"],"description":"Pensionable pay: all of it (pay), or only automatic enrolment qualifying earnings. Pay when not given."},"includes":{"type":"array","items":{"type":"string","enum":["overtime","allowances","bonus"]},"description":"Pay besides salary that is pensionable: overtime, allowances, bonus."},"amount":{"type":"object","properties":{"amount":{"type":"number","minimum":0,"exclusiveMaximum":100000000,"description":"Pounds and pence."},"per":{"type":"string","enum":["year","month","four_weeks","two_weeks","week","day","hour"],"description":"The period the amount is for."}},"required":["amount","per"],"additionalProperties":false,"description":"A fixed contribution instead of a percent."}},"required":["method"],"additionalProperties":false,"description":"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."},"employer_pension":{"anyOf":[{"type":"string","const":"auto_enrolment_minimum"},{"type":"object","properties":{"percent":{"type":"number","minimum":0,"maximum":100,"description":"A percentage of pensionable pay."},"basis":{"type":"string","enum":["pay","qualifying_earnings"],"description":"Pensionable pay: all of it (pay), or only automatic enrolment qualifying earnings. Pay when not given."},"includes":{"type":"array","items":{"type":"string","enum":["overtime","allowances","bonus"]},"description":"Pay besides salary that is pensionable: overtime, allowances, bonus."},"amount":{"type":"object","properties":{"amount":{"type":"number","minimum":0,"exclusiveMaximum":100000000,"description":"Pounds and pence."},"per":{"type":"string","enum":["year","month","four_weeks","two_weeks","week","day","hour"],"description":"The period the amount is for."}},"required":["amount","per"],"additionalProperties":false,"description":"A fixed contribution instead of a percent."}},"additionalProperties":false}],"description":"The employer's contribution, on top of pay: auto_enrolment_minimum (3% of qualifying earnings), or a percent or amount."},"overtime":{"type":"array","items":{"anyOf":[{"type":"object","properties":{"amount":{"type":"number","minimum":0,"exclusiveMaximum":100000000,"description":"Pounds and pence."},"per":{"type":"string","enum":["year","month","four_weeks","two_weeks","week","day","hour"],"description":"The period the amount is for."}},"required":["amount","per"],"additionalProperties":false},{"type":"object","properties":{"hours":{"type":"number","minimum":0,"maximum":168,"description":"Overtime hours."},"multiplier":{"type":"number","minimum":0,"maximum":10,"description":"Times the salary's hourly rate: 1.5 for time and a half."},"per":{"type":"string","enum":["year","month","four_weeks","two_weeks","week","day","hour"],"description":"The period the amount or hours are for."}},"required":["hours","multiplier","per"],"additionalProperties":false}]},"maxItems":20,"description":"Overtime: amounts per period, or hours at a multiple of the hourly rate per period."},"allowances":{"type":"object","properties":{"amount":{"type":"number","minimum":0,"exclusiveMaximum":100000000,"description":"Pounds and pence."},"per":{"type":"string","enum":["year","month","four_weeks","two_weeks","week","day","hour"],"description":"The period the amount is for."}},"required":["amount","per"],"additionalProperties":false,"description":"Cash allowances, taxed and NI'd like salary."},"bonus":{"type":"object","properties":{"amount":{"type":"number","minimum":0,"exclusiveMaximum":100000000,"description":"The bonus, in pounds and pence."},"pay_period":{"type":"integer","minimum":1,"maximum":52,"description":"The pay period it is paid in: 1 is the first of the tax year."}},"required":["amount"],"additionalProperties":false,"description":"A one-off bonus, paid in pay_period (the last pay period of the year when not given)."},"salary_sacrifice":{"type":"object","properties":{"amount":{"type":"number","minimum":0,"exclusiveMaximum":100000000,"description":"Pounds and pence."},"per":{"type":"string","enum":["year","month","four_weeks","two_weeks","week","day","hour"],"description":"The period the amount is for."}},"required":["amount","per"],"additionalProperties":false,"description":"Salary given up for something other than a pension: free of tax and NI."},"benefits_in_kind":{"type":"object","properties":{"amount":{"type":"number","minimum":0,"exclusiveMaximum":100000000,"description":"Pounds and pence."},"per":{"type":"string","enum":["year","month","four_weeks","two_weeks","week","day","hour"],"description":"The period the amount is for."}},"required":["amount","per"],"additionalProperties":false,"description":"Taxable benefits in kind, collected through the tax code."},"childcare_vouchers":{"type":"object","properties":{"amount":{"type":"number","minimum":0,"exclusiveMaximum":100000000,"description":"Pounds and pence."},"per":{"type":"string","enum":["year","month","four_weeks","two_weeks","week","day","hour"],"description":"The period the amount is for."},"joined_before_2011":{"type":"boolean","description":"Joined the scheme before 6 April 2011."}},"required":["amount","per"],"additionalProperties":false,"description":"Childcare vouchers taken from pay; joined_before_2011 gives the old scheme’s basic rate exempt amount."},"pre_tax_deductions":{"type":"object","properties":{"amount":{"type":"number","minimum":0,"exclusiveMaximum":100000000,"description":"Pounds and pence."},"per":{"type":"string","enum":["year","month","four_weeks","two_weeks","week","day","hour"],"description":"The period the amount is for."}},"required":["amount","per"],"additionalProperties":false,"description":"Deductions before tax but after NI, such as payroll giving."},"post_tax_deductions":{"type":"object","properties":{"amount":{"type":"number","minimum":0,"exclusiveMaximum":100000000,"description":"Pounds and pence."},"per":{"type":"string","enum":["year","month","four_weeks","two_weeks","week","day","hour"],"description":"The period the amount is for."}},"required":["amount","per"],"additionalProperties":false,"description":"Deductions from net pay."},"blind":{"type":"boolean","description":"Blind Person's Allowance."},"marriage_allowance":{"type":"string","enum":["transferring","receiving"],"description":"Marriage Allowance: transferring or receiving."},"married_couples_allowance":{"type":"boolean","description":"Claims Married Couple's Allowance (one of the couple born before 6 April 1935)."},"child_benefit":{"type":"object","properties":{"children":{"type":"integer","minimum":1,"maximum":20,"description":"Children Child Benefit is paid for."},"weeks":{"type":"integer","minimum":1,"maximum":53,"description":"Weeks of the tax year it is paid for: all of them when not given."}},"required":["children"],"additionalProperties":false,"description":"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)."},"gross":{"type":"object","properties":{"amount":{"type":"number","minimum":0,"exclusiveMaximum":100000000,"description":"Pounds and pence."},"per":{"type":"string","enum":["year","month","four_weeks","two_weeks","week","day","hour"],"description":"The period the amount is for."}},"required":["amount","per"],"additionalProperties":false,"description":"Gross pay: { amount, per } with per as year, month, four_weeks, two_weeks, week, day or hour."},"employment_allowance":{"type":"boolean","description":"Sets the year's Employment Allowance against this employee's employer NI."},"apprenticeship_levy":{"type":"boolean","description":"Adds the Apprenticeship Levy: 0.5% of this employee's NI-able pay."}},"required":["gross"],"additionalProperties":false},"example":{"gross":{"amount":40000,"per":"year"},"region":"england","employer_pension":"auto_enrolment_minimum"}}}},"responses":{"200":{"description":"The result, with what produced it, the assumptions and the sources.","content":{"application/json":{"schema":{"type":"object","properties":{"tax_year":{"type":"string"},"engine":{"type":"string"},"hmrc_test_data":{"type":"string"},"cost":{"type":"object","properties":{"pay":{"type":"number"},"benefits_in_kind":{"type":"number"},"employer_ni":{"type":"number"},"employment_allowance":{"type":"number"},"class_1a_ni":{"type":"number"},"employer_pension":{"type":"number"},"apprenticeship_levy":{"type":"number"},"total":{"type":"number"}}},"employee":{"type":"object","properties":{"tax_code":{"type":"string"},"tax_code_derived":{"type":"boolean"},"tax_region":{"type":"string"},"pay_frequency":{"type":"string"},"personal_allowance":{"type":"number"},"adjusted_net_income":{"type":"number"},"benefits_in_kind":{"type":"number"},"married_couples_allowance":{"type":"number"},"childcare_voucher_band":{},"child_benefit":{},"periods":{"type":"object","properties":{"year":{"type":"object","properties":{"gross":{"type":"number"},"salary_sacrifice":{"type":"number"},"childcare_vouchers":{"type":"number"},"pension":{"type":"number"},"pension_contribution":{"type":"number"},"employer_pension":{"type":"number"},"pre_tax_deductions":{"type":"number"},"niable_pay":{"type":"number"},"taxable_pay":{"type":"number"},"tax":{"type":"number"},"employee_ni":{"type":"number"},"employer_ni":{"type":"number"},"student_loans":{"type":"object","properties":{}},"post_tax_deductions":{"type":"number"},"take_home":{"type":"number"}}},"month":{"type":"object","properties":{"gross":{"type":"number"},"salary_sacrifice":{"type":"number"},"childcare_vouchers":{"type":"number"},"pension":{"type":"number"},"pension_contribution":{"type":"number"},"employer_pension":{"type":"number"},"pre_tax_deductions":{"type":"number"},"niable_pay":{"type":"number"},"taxable_pay":{"type":"number"},"tax":{"type":"number"},"employee_ni":{"type":"number"},"employer_ni":{"type":"number"},"student_loans":{"type":"object","properties":{}},"post_tax_deductions":{"type":"number"},"take_home":{"type":"number"}}},"four_weeks":{"type":"object","properties":{"gross":{"type":"number"},"salary_sacrifice":{"type":"number"},"childcare_vouchers":{"type":"number"},"pension":{"type":"number"},"pension_contribution":{"type":"number"},"employer_pension":{"type":"number"},"pre_tax_deductions":{"type":"number"},"niable_pay":{"type":"number"},"taxable_pay":{"type":"number"},"tax":{"type":"number"},"employee_ni":{"type":"number"},"employer_ni":{"type":"number"},"student_loans":{"type":"object","properties":{}},"post_tax_deductions":{"type":"number"},"take_home":{"type":"number"}}},"two_weeks":{"type":"object","properties":{"gross":{"type":"number"},"salary_sacrifice":{"type":"number"},"childcare_vouchers":{"type":"number"},"pension":{"type":"number"},"pension_contribution":{"type":"number"},"employer_pension":{"type":"number"},"pre_tax_deductions":{"type":"number"},"niable_pay":{"type":"number"},"taxable_pay":{"type":"number"},"tax":{"type":"number"},"employee_ni":{"type":"number"},"employer_ni":{"type":"number"},"student_loans":{"type":"object","properties":{}},"post_tax_deductions":{"type":"number"},"take_home":{"type":"number"}}},"week":{"type":"object","properties":{"gross":{"type":"number"},"salary_sacrifice":{"type":"number"},"childcare_vouchers":{"type":"number"},"pension":{"type":"number"},"pension_contribution":{"type":"number"},"employer_pension":{"type":"number"},"pre_tax_deductions":{"type":"number"},"niable_pay":{"type":"number"},"taxable_pay":{"type":"number"},"tax":{"type":"number"},"employee_ni":{"type":"number"},"employer_ni":{"type":"number"},"student_loans":{"type":"object","properties":{}},"post_tax_deductions":{"type":"number"},"take_home":{"type":"number"}}},"day":{"type":"object","properties":{"gross":{"type":"number"},"salary_sacrifice":{"type":"number"},"childcare_vouchers":{"type":"number"},"pension":{"type":"number"},"pension_contribution":{"type":"number"},"employer_pension":{"type":"number"},"pre_tax_deductions":{"type":"number"},"niable_pay":{"type":"number"},"taxable_pay":{"type":"number"},"tax":{"type":"number"},"employee_ni":{"type":"number"},"employer_ni":{"type":"number"},"student_loans":{"type":"object","properties":{}},"post_tax_deductions":{"type":"number"},"take_home":{"type":"number"}}},"hour":{"type":"object","properties":{"gross":{"type":"number"},"salary_sacrifice":{"type":"number"},"childcare_vouchers":{"type":"number"},"pension":{"type":"number"},"pension_contribution":{"type":"number"},"employer_pension":{"type":"number"},"pre_tax_deductions":{"type":"number"},"niable_pay":{"type":"number"},"taxable_pay":{"type":"number"},"tax":{"type":"number"},"employee_ni":{"type":"number"},"employer_ni":{"type":"number"},"student_loans":{"type":"object","properties":{}},"post_tax_deductions":{"type":"number"},"take_home":{"type":"number"}}}}},"payslips":{"type":"array","items":{"type":"object","properties":{"period":{"type":"number"},"gross":{"type":"number"},"salary_sacrifice":{"type":"number"},"childcare_vouchers":{"type":"number"},"pension":{"type":"number"},"pension_contribution":{"type":"number"},"employer_pension":{"type":"number"},"pre_tax_deductions":{"type":"number"},"niable_pay":{"type":"number"},"taxable_pay":{"type":"number"},"tax":{"type":"number"},"employee_ni":{"type":"number"},"employer_ni":{"type":"number"},"student_loans":{"type":"object","properties":{}},"post_tax_deductions":{"type":"number"},"take_home":{"type":"number"}}}},"tax_bands":{"type":"array","items":{"type":"object","properties":{"rate":{"type":"number"},"taxable":{"type":"number"},"tax":{"type":"number"}}}},"rates":{"type":"object","properties":{"effective":{"type":"number"},"marginal":{"type":"number"}}}}},"assumptions":{"type":"array","items":{"type":"string"}},"sources":{"type":"array","items":{"type":"string"}}},"required":["tax_year","engine","hmrc_test_data","assumptions","sources"]},"example":{"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","cost":{"pay":40000,"benefits_in_kind":0,"employer_ni":5249.4,"employment_allowance":0,"class_1a_ni":0,"employer_pension":1012.8,"apprenticeship_levy":0,"total":46262.2},"employee":{"tax_code":"1257L","tax_code_derived":true,"tax_region":"rest_of_uk","pay_frequency":"monthly","personal_allowance":12570,"adjusted_net_income":40000,"benefits_in_kind":0,"married_couples_allowance":0,"childcare_voucher_band":null,"child_benefit":null,"periods":{"year":{"gross":40000,"salary_sacrifice":0,"childcare_vouchers":0,"pension":0,"pension_contribution":0,"employer_pension":1012.8,"pre_tax_deductions":0,"niable_pay":40000,"taxable_pay":40000,"tax":5484,"employee_ni":2193.96,"employer_ni":5249.4,"student_loans":{},"post_tax_deductions":0,"take_home":32322.04},"month":{"gross":3333.33,"salary_sacrifice":0,"childcare_vouchers":0,"pension":0,"pension_contribution":0,"employer_pension":84.4,"pre_tax_deductions":0,"niable_pay":3333.33,"taxable_pay":3333.33,"tax":457,"employee_ni":182.83,"employer_ni":437.45,"student_loans":{},"post_tax_deductions":0,"take_home":2693.5},"four_weeks":{"gross":3076.92,"salary_sacrifice":0,"childcare_vouchers":0,"pension":0,"pension_contribution":0,"employer_pension":77.91,"pre_tax_deductions":0,"niable_pay":3076.92,"taxable_pay":3076.92,"tax":421.85,"employee_ni":168.77,"employer_ni":403.8,"student_loans":{},"post_tax_deductions":0,"take_home":2486.31},"two_weeks":{"gross":1538.46,"salary_sacrifice":0,"childcare_vouchers":0,"pension":0,"pension_contribution":0,"employer_pension":38.95,"pre_tax_deductions":0,"niable_pay":1538.46,"taxable_pay":1538.46,"tax":210.92,"employee_ni":84.38,"employer_ni":201.9,"student_loans":{},"post_tax_deductions":0,"take_home":1243.16},"week":{"gross":769.23,"salary_sacrifice":0,"childcare_vouchers":0,"pension":0,"pension_contribution":0,"employer_pension":19.48,"pre_tax_deductions":0,"niable_pay":769.23,"taxable_pay":769.23,"tax":105.46,"employee_ni":42.19,"employer_ni":100.95,"student_loans":{},"post_tax_deductions":0,"take_home":621.58},"day":{"gross":153.85,"salary_sacrifice":0,"childcare_vouchers":0,"pension":0,"pension_contribution":0,"employer_pension":3.9,"pre_tax_deductions":0,"niable_pay":153.85,"taxable_pay":153.85,"tax":21.09,"employee_ni":8.44,"employer_ni":20.19,"student_loans":{},"post_tax_deductions":0,"take_home":124.32},"hour":{"gross":20.51,"salary_sacrifice":0,"childcare_vouchers":0,"pension":0,"pension_contribution":0,"employer_pension":0.52,"pre_tax_deductions":0,"niable_pay":20.51,"taxable_pay":20.51,"tax":2.81,"employee_ni":1.13,"employer_ni":2.69,"student_loans":{},"post_tax_deductions":0,"take_home":16.58}},"payslips":[{"period":1,"gross":3333.34,"salary_sacrifice":0,"childcare_vouchers":0,"pension":0,"pension_contribution":0,"employer_pension":84.4,"pre_tax_deductions":0,"niable_pay":3333.34,"taxable_pay":3333.34,"tax":457,"employee_ni":182.83,"employer_ni":437.45,"student_loans":{},"post_tax_deductions":0,"take_home":2693.51},{"period":2,"gross":3333.34,"salary_sacrifice":0,"childcare_vouchers":0,"pension":0,"pension_contribution":0,"employer_pension":84.4,"pre_tax_deductions":0,"niable_pay":3333.34,"taxable_pay":3333.34,"tax":457,"employee_ni":182.83,"employer_ni":437.45,"student_loans":{},"post_tax_deductions":0,"take_home":2693.51},{"period":3,"gross":3333.34,"salary_sacrifice":0,"childcare_vouchers":0,"pension":0,"pension_contribution":0,"employer_pension":84.4,"pre_tax_deductions":0,"niable_pay":3333.34,"taxable_pay":3333.34,"tax":457,"employee_ni":182.83,"employer_ni":437.45,"student_loans":{},"post_tax_deductions":0,"take_home":2693.51},{"period":4,"gross":3333.34,"salary_sacrifice":0,"childcare_vouchers":0,"pension":0,"pension_contribution":0,"employer_pension":84.4,"pre_tax_deductions":0,"niable_pay":3333.34,"taxable_pay":3333.34,"tax":457,"employee_ni":182.83,"employer_ni":437.45,"student_loans":{},"post_tax_deductions":0,"take_home":2693.51},{"period":5,"gross":3333.33,"salary_sacrifice":0,"childcare_vouchers":0,"pension":0,"pension_contribution":0,"employer_pension":84.4,"pre_tax_deductions":0,"niable_pay":3333.33,"taxable_pay":3333.33,"tax":457,"employee_ni":182.83,"employer_ni":437.45,"student_loans":{},"post_tax_deductions":0,"take_home":2693.5},{"period":6,"gross":3333.33,"salary_sacrifice":0,"childcare_vouchers":0,"pension":0,"pension_contribution":0,"employer_pension":84.4,"pre_tax_deductions":0,"niable_pay":3333.33,"taxable_pay":3333.33,"tax":457,"employee_ni":182.83,"employer_ni":437.45,"student_loans":{},"post_tax_deductions":0,"take_home":2693.5},{"period":7,"gross":3333.33,"salary_sacrifice":0,"childcare_vouchers":0,"pension":0,"pension_contribution":0,"employer_pension":84.4,"pre_tax_deductions":0,"niable_pay":3333.33,"taxable_pay":3333.33,"tax":457,"employee_ni":182.83,"employer_ni":437.45,"student_loans":{},"post_tax_deductions":0,"take_home":2693.5},{"period":8,"gross":3333.33,"salary_sacrifice":0,"childcare_vouchers":0,"pension":0,"pension_contribution":0,"employer_pension":84.4,"pre_tax_deductions":0,"niable_pay":3333.33,"taxable_pay":3333.33,"tax":457,"employee_ni":182.83,"employer_ni":437.45,"student_loans":{},"post_tax_deductions":0,"take_home":2693.5},{"period":9,"gross":3333.33,"salary_sacrifice":0,"childcare_vouchers":0,"pension":0,"pension_contribution":0,"employer_pension":84.4,"pre_tax_deductions":0,"niable_pay":3333.33,"taxable_pay":3333.33,"tax":457,"employee_ni":182.83,"employer_ni":437.45,"student_loans":{},"post_tax_deductions":0,"take_home":2693.5},{"period":10,"gross":3333.33,"salary_sacrifice":0,"childcare_vouchers":0,"pension":0,"pension_contribution":0,"employer_pension":84.4,"pre_tax_deductions":0,"niable_pay":3333.33,"taxable_pay":3333.33,"tax":457,"employee_ni":182.83,"employer_ni":437.45,"student_loans":{},"post_tax_deductions":0,"take_home":2693.5},{"period":11,"gross":3333.33,"salary_sacrifice":0,"childcare_vouchers":0,"pension":0,"pension_contribution":0,"employer_pension":84.4,"pre_tax_deductions":0,"niable_pay":3333.33,"taxable_pay":3333.33,"tax":457,"employee_ni":182.83,"employer_ni":437.45,"student_loans":{},"post_tax_deductions":0,"take_home":2693.5},{"period":12,"gross":3333.33,"salary_sacrifice":0,"childcare_vouchers":0,"pension":0,"pension_contribution":0,"employer_pension":84.4,"pre_tax_deductions":0,"niable_pay":3333.33,"taxable_pay":3333.33,"tax":457,"employee_ni":182.83,"employer_ni":437.45,"student_loans":{},"post_tax_deductions":0,"take_home":2693.5}],"tax_bands":[{"rate":20,"taxable":27420,"tax":5484}],"rates":{"effective":19.19,"marginal":27.99}},"assumptions":["Benefits in kind count at their taxable value, as an estimate of what they cost.","apprenticeship_levy is the marginal cost for an employer whose pay bill is over £3 million: 0.5% of this employee's NI-able pay.","employment_allowance sets the whole allowance against this employee: right for an employer with no one else using it. It is not available where the only employee paid above the secondary threshold is a director.","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","https://www.gov.uk/guidance/rates-and-thresholds-for-employers-2026-to-2027","https://www.thepensionsregulator.gov.uk/en/business-advisers/automatic-enrolment-guide-for-business-advisers/minimum-contribution-increases-planned-by-law-phasing","https://www.thepensionsregulator.gov.uk/en/employers/new-employers/im-an-employer-who-has-to-provide-a-pension/declare-your-compliance/ongoing-duties-for-employers/earnings-thresholds"]}}}},"400":{"description":"INVALID_INPUT: the message names each field that is wrong.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"UNAUTHENTICATED (no key) or INVALID_KEY (an unknown or revoked key).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"QUOTA_EXCEEDED: the free plan's calculations for the month are used; upgrade_url says where to get more.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"RATE_LIMITED: over the plan's calls a second; Retry-After says when to try again.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"UNAVAILABLE: keys can’t be checked right now; retry with backoff.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/payroll/period":{"post":{"operationId":"payrollPeriod","tags":["Payroll"],"summary":"One pay period","description":"One pay period the way payroll software runs it: tax on a cumulative or week 1/month 1 code, employee and employer NI by category letter (directors on the annual earnings period), student loans and the NI earnings bands. Every case in HMRC's payroll test data runs through this endpoint.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"tax_year":{"type":"string","default":"2026-27","description":"The tax year, such as 2026-27. The latest when not given."},"pay_frequency":{"type":"string","enum":["monthly","four_weekly","two_weekly","weekly"],"description":"How often the employee is paid: monthly, four_weekly, two_weekly or weekly."},"period":{"type":"integer","minimum":1,"maximum":52,"description":"The tax week or month for weekly and monthly pay, else the pay period number."},"tax_code":{"type":"string","maxLength":20,"description":"The tax code on the payroll record, with W1 or M1 for the week 1/month 1 basis."},"gross_pay":{"type":"number","minimum":0,"exclusiveMaximum":100000000,"description":"Pay this period subject to NI, which student loans are also worked on."},"taxable_pay":{"type":"number","exclusiveMinimum":-100000000,"exclusiveMaximum":100000000,"description":"Pay this period subject to tax, payrolled benefits included; gross_pay when not given."},"payrolled_benefits":{"type":"number","minimum":0,"exclusiveMaximum":100000000,"description":"Payrolled benefits in kind in taxable_pay: taxed, but outside the 50% limit."},"taxable_pay_to_date":{"type":"number","exclusiveMinimum":-100000000,"exclusiveMaximum":100000000,"default":0,"description":"Taxable pay in this employment in earlier periods of the year."},"tax_to_date":{"type":"number","exclusiveMinimum":-100000000,"exclusiveMaximum":100000000,"default":0,"description":"Tax deducted in this employment in earlier periods of the year."},"ni_category":{"type":"string","enum":["A","B","C","D","E","F","H","I","J","K","L","M","N","S","V","Z"],"default":"A","description":"National Insurance category letter: A when not given."},"student_loans":{"type":"array","items":{"type":"string","enum":["plan_1","plan_2","plan_4","plan_5","postgraduate"]},"default":[],"description":"Each loan the employee repays: plan_1, plan_2, plan_4, plan_5, postgraduate."},"director":{"type":"object","properties":{"earnings_to_date":{"type":"number","minimum":0,"exclusiveMaximum":100000000,"description":"NI-able earnings as a director in earlier periods."},"employee_ni_to_date":{"type":"number","minimum":0,"exclusiveMaximum":100000000,"description":"Employee NI paid in earlier periods as a director."},"employer_ni_to_date":{"type":"number","minimum":0,"exclusiveMaximum":100000000,"description":"Employer NI paid in earlier periods as a director."},"weeks_as_director":{"type":"integer","minimum":1,"maximum":52,"description":"Weeks as a director this year, when appointed during it (pro rata thresholds)."}},"required":["earnings_to_date","employee_ni_to_date","employer_ni_to_date"],"additionalProperties":false,"description":"A company director on the annual earnings period: NI this period is the year's NI on earnings to date less what earlier periods paid."}},"required":["pay_frequency","period","tax_code","gross_pay"],"additionalProperties":false},"example":{"pay_frequency":"monthly","period":1,"tax_code":"1257L","gross_pay":3000,"student_loans":["plan_2"]}}}},"responses":{"200":{"description":"The result, with what produced it, the assumptions and the sources.","content":{"application/json":{"schema":{"type":"object","properties":{"tax_year":{"type":"string"},"engine":{"type":"string"},"hmrc_test_data":{"type":"string"},"tax_code":{"type":"string"},"tax":{"type":"number"},"tax_to_date":{"type":"number"},"regulatory_limit_applied":{"type":"boolean"},"employee_ni":{"type":"number"},"employer_ni":{"type":"number"},"ni_earnings":{"type":"object","properties":{"at_lower_earnings_limit":{"type":"number"},"lower_earnings_limit_to_primary_threshold":{"type":"number"},"primary_threshold_to_upper_earnings_limit":{"type":"number"}}},"student_loans":{"type":"object","properties":{"plan_2":{"type":"number"}}},"assumptions":{"type":"array","items":{"type":"string"}},"sources":{"type":"array","items":{"type":"string"}}},"required":["tax_year","engine","hmrc_test_data","assumptions","sources"]},"example":{"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":390.2,"tax_to_date":390.2,"regulatory_limit_applied":false,"employee_ni":156.16,"employer_ni":387.45,"ni_earnings":{"at_lower_earnings_limit":559,"lower_earnings_limit_to_primary_threshold":489,"primary_threshold_to_upper_earnings_limit":1952},"student_loans":{"plan_2":49},"assumptions":["taxable_pay_to_date and tax_to_date are for this employment only, before this period."],"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/government/publications/software-developers-payroll-test-data-2026-to-2027"]}}}},"400":{"description":"INVALID_INPUT: the message names each field that is wrong.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"UNAUTHENTICATED (no key) or INVALID_KEY (an unknown or revoked key).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"QUOTA_EXCEEDED: the free plan's calculations for the month are used; upgrade_url says where to get more.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"RATE_LIMITED: over the plan's calls a second; Retry-After says when to try again.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"UNAVAILABLE: keys can’t be checked right now; retry with backoff.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/statutory/sick-pay":{"post":{"operationId":"sickPay","tags":["Statutory pay"],"summary":"Statutory Sick Pay","description":"One payment of Statutory Sick Pay: the lower of the flat rate and 80% of average weekly earnings, per qualifying day, rounded up to the penny, up to 28 weeks.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"tax_year":{"type":"string","default":"2026-27","description":"The tax year, such as 2026-27. The latest when not given."},"average_weekly_earnings":{"anyOf":[{"type":"object","properties":{"amount":{"type":"number","minimum":0,"exclusiveMaximum":100000000,"description":"Average weekly earnings, when already known."}},"required":["amount"],"additionalProperties":false},{"type":"object","properties":{"earnings":{"type":"number","minimum":0,"exclusiveMaximum":100000000,"description":"Gross earnings paid in the relevant period."},"weeks":{"type":"integer","minimum":1,"maximum":52,"description":"Whole weeks in the relevant period, for weekly, two-weekly and four-weekly pay."}},"required":["earnings","weeks"],"additionalProperties":false},{"type":"object","properties":{"earnings":{"type":"number","minimum":0,"exclusiveMaximum":100000000,"description":"Gross earnings paid in the relevant period."},"months":{"type":"integer","minimum":1,"maximum":12,"description":"Months in the relevant period, for monthly pay."}},"required":["earnings","months"],"additionalProperties":false},{"type":"object","properties":{"earnings":{"type":"number","minimum":0,"exclusiveMaximum":100000000,"description":"Gross earnings paid in the relevant period."},"days":{"type":"integer","minimum":1,"maximum":366,"description":"Days in the relevant period, for irregular pay or a new employee."}},"required":["earnings","days"],"additionalProperties":false}],"description":"Average weekly earnings: { amount } a week, or the earnings in the relevant period with the weeks, months or days to divide them by."},"qualifying_days_per_week":{"type":"integer","minimum":1,"maximum":7,"description":"The employee's usual working days in a week."},"days":{"type":"integer","minimum":0,"maximum":366,"description":"Qualifying days off sick in this pay period."},"days_paid_before":{"type":"integer","minimum":0,"maximum":196,"default":0,"description":"Qualifying days of SSP already paid in this period of incapacity (and linked ones), for the 28-week limit."}},"required":["average_weekly_earnings","qualifying_days_per_week","days"],"additionalProperties":false},"example":{"average_weekly_earnings":{"amount":600},"qualifying_days_per_week":5,"days":5}}}},"responses":{"200":{"description":"The result, with what produced it, the assumptions and the sources.","content":{"application/json":{"schema":{"type":"object","properties":{"tax_year":{"type":"string"},"engine":{"type":"string"},"hmrc_test_data":{"type":"string"},"average_weekly_earnings":{"type":"number"},"weekly_rate":{"type":"number"},"days":{"type":"number"},"amount":{"type":"number"},"days_remaining":{"type":"number"},"assumptions":{"type":"array","items":{"type":"string"}},"sources":{"type":"array","items":{"type":"string"}}},"required":["tax_year","engine","hmrc_test_data","assumptions","sources"]},"example":{"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","average_weekly_earnings":600,"weekly_rate":123.25,"days":5,"amount":123.25,"days_remaining":135,"assumptions":["Statutory Sick Pay from 6 April 2026: from the first day off sick, at any earnings, at the lower of £123.25 a week and 80% of average weekly earnings.","A day is the weekly rate divided by the qualifying days in the week, and each payment rounds up to the penny, so send one request per pay period.","The caller checks entitlement (an employee, sick for at least one full working day: from 6 April 2026 there is no 4-day rule) and works out the qualifying days and linked periods of sickness."],"sources":["https://www.gov.uk/guidance/rates-and-thresholds-for-employers-2026-to-2027","https://www.gov.uk/guidance/statutory-sick-pay-manually-calculate-your-employees-payments"]}}}},"400":{"description":"INVALID_INPUT: the message names each field that is wrong.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"UNAUTHENTICATED (no key) or INVALID_KEY (an unknown or revoked key).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"QUOTA_EXCEEDED: the free plan's calculations for the month are used; upgrade_url says where to get more.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"RATE_LIMITED: over the plan's calls a second; Retry-After says when to try again.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"UNAVAILABLE: keys can’t be checked right now; retry with backoff.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/statutory/maternity-pay":{"post":{"operationId":"maternityPay","tags":["Statutory pay"],"summary":"Statutory Maternity Pay","description":"Statutory Maternity Pay, week by week for up to 39 weeks, from average weekly earnings, with eligibility on the lower earnings limit.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"tax_year":{"type":"string","default":"2026-27","description":"The tax year, such as 2026-27. The latest when not given."},"average_weekly_earnings":{"anyOf":[{"type":"object","properties":{"amount":{"type":"number","minimum":0,"exclusiveMaximum":100000000,"description":"Average weekly earnings, when already known."}},"required":["amount"],"additionalProperties":false},{"type":"object","properties":{"earnings":{"type":"number","minimum":0,"exclusiveMaximum":100000000,"description":"Gross earnings paid in the relevant period."},"weeks":{"type":"integer","minimum":1,"maximum":52,"description":"Whole weeks in the relevant period, for weekly, two-weekly and four-weekly pay."}},"required":["earnings","weeks"],"additionalProperties":false},{"type":"object","properties":{"earnings":{"type":"number","minimum":0,"exclusiveMaximum":100000000,"description":"Gross earnings paid in the relevant period."},"months":{"type":"integer","minimum":1,"maximum":12,"description":"Months in the relevant period, for monthly pay."}},"required":["earnings","months"],"additionalProperties":false},{"type":"object","properties":{"earnings":{"type":"number","minimum":0,"exclusiveMaximum":100000000,"description":"Gross earnings paid in the relevant period."},"days":{"type":"integer","minimum":1,"maximum":366,"description":"Days in the relevant period, for irregular pay or a new employee."}},"required":["earnings","days"],"additionalProperties":false}],"description":"Average weekly earnings: { amount } a week, or the earnings in the relevant period with the weeks, months or days to divide them by."},"from_week":{"type":"integer","minimum":1,"maximum":39,"default":1,"description":"The first week of the claim to pay, for a claim split across tax years."},"weeks":{"type":"integer","minimum":1,"maximum":39,"description":"Weeks to pay from from_week, when fewer than the rest."}},"required":["average_weekly_earnings"],"additionalProperties":false},"example":{"average_weekly_earnings":{"amount":400}}}}},"responses":{"200":{"description":"The result, with what produced it, the assumptions and the sources.","content":{"application/json":{"schema":{"type":"object","properties":{"tax_year":{"type":"string"},"engine":{"type":"string"},"hmrc_test_data":{"type":"string"},"average_weekly_earnings":{"type":"number"},"eligible":{"type":"boolean"},"lower_earnings_limit":{"type":"number"},"weeks":{"type":"array","items":{"type":"object","properties":{"from":{"type":"number"},"to":{"type":"number"},"weekly":{"type":"number"}}}},"total":{"type":"number"},"assumptions":{"type":"array","items":{"type":"string"}},"sources":{"type":"array","items":{"type":"string"}}},"required":["tax_year","engine","hmrc_test_data","assumptions","sources"]},"example":{"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","average_weekly_earnings":400,"eligible":true,"lower_earnings_limit":129,"weeks":[{"from":1,"to":6,"weekly":360},{"from":7,"to":39,"weekly":194.32}],"total":8572.56,"assumptions":["90% of average weekly earnings for the first 6 weeks, then the lower of £194.32 and 90% for up to 33 more.","Payable when average weekly earnings reach the lower earnings limit. The caller checks the employment conditions (such as 26 weeks with the employer by the qualifying week) and works out the relevant period.","Every week is at this tax year's rates: for weeks after 5 April, ask again with the next tax year and from_week."],"sources":["https://www.gov.uk/guidance/rates-and-thresholds-for-employers-2026-to-2027","https://www.gov.uk/guidance/statutory-sick-pay-manually-calculate-your-employees-payments"]}}}},"400":{"description":"INVALID_INPUT: the message names each field that is wrong.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"UNAUTHENTICATED (no key) or INVALID_KEY (an unknown or revoked key).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"QUOTA_EXCEEDED: the free plan's calculations for the month are used; upgrade_url says where to get more.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"RATE_LIMITED: over the plan's calls a second; Retry-After says when to try again.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"UNAVAILABLE: keys can’t be checked right now; retry with backoff.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/statutory/adoption-pay":{"post":{"operationId":"adoptionPay","tags":["Statutory pay"],"summary":"Statutory Adoption Pay","description":"Statutory Adoption Pay, week by week for up to 39 weeks, from average weekly earnings, with eligibility on the lower earnings limit.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"tax_year":{"type":"string","default":"2026-27","description":"The tax year, such as 2026-27. The latest when not given."},"average_weekly_earnings":{"anyOf":[{"type":"object","properties":{"amount":{"type":"number","minimum":0,"exclusiveMaximum":100000000,"description":"Average weekly earnings, when already known."}},"required":["amount"],"additionalProperties":false},{"type":"object","properties":{"earnings":{"type":"number","minimum":0,"exclusiveMaximum":100000000,"description":"Gross earnings paid in the relevant period."},"weeks":{"type":"integer","minimum":1,"maximum":52,"description":"Whole weeks in the relevant period, for weekly, two-weekly and four-weekly pay."}},"required":["earnings","weeks"],"additionalProperties":false},{"type":"object","properties":{"earnings":{"type":"number","minimum":0,"exclusiveMaximum":100000000,"description":"Gross earnings paid in the relevant period."},"months":{"type":"integer","minimum":1,"maximum":12,"description":"Months in the relevant period, for monthly pay."}},"required":["earnings","months"],"additionalProperties":false},{"type":"object","properties":{"earnings":{"type":"number","minimum":0,"exclusiveMaximum":100000000,"description":"Gross earnings paid in the relevant period."},"days":{"type":"integer","minimum":1,"maximum":366,"description":"Days in the relevant period, for irregular pay or a new employee."}},"required":["earnings","days"],"additionalProperties":false}],"description":"Average weekly earnings: { amount } a week, or the earnings in the relevant period with the weeks, months or days to divide them by."},"from_week":{"type":"integer","minimum":1,"maximum":39,"default":1,"description":"The first week of the claim to pay, for a claim split across tax years."},"weeks":{"type":"integer","minimum":1,"maximum":39,"description":"Weeks to pay from from_week, when fewer than the rest."}},"required":["average_weekly_earnings"],"additionalProperties":false},"example":{"average_weekly_earnings":{"amount":400}}}}},"responses":{"200":{"description":"The result, with what produced it, the assumptions and the sources.","content":{"application/json":{"schema":{"type":"object","properties":{"tax_year":{"type":"string"},"engine":{"type":"string"},"hmrc_test_data":{"type":"string"},"average_weekly_earnings":{"type":"number"},"eligible":{"type":"boolean"},"lower_earnings_limit":{"type":"number"},"weeks":{"type":"array","items":{"type":"object","properties":{"from":{"type":"number"},"to":{"type":"number"},"weekly":{"type":"number"}}}},"total":{"type":"number"},"assumptions":{"type":"array","items":{"type":"string"}},"sources":{"type":"array","items":{"type":"string"}}},"required":["tax_year","engine","hmrc_test_data","assumptions","sources"]},"example":{"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","average_weekly_earnings":400,"eligible":true,"lower_earnings_limit":129,"weeks":[{"from":1,"to":6,"weekly":360},{"from":7,"to":39,"weekly":194.32}],"total":8572.56,"assumptions":["90% of average weekly earnings for the first 6 weeks, then the lower of £194.32 and 90% for up to 33 more.","Payable when average weekly earnings reach the lower earnings limit. The caller checks the employment conditions (such as 26 weeks with the employer by the qualifying week) and works out the relevant period.","Every week is at this tax year's rates: for weeks after 5 April, ask again with the next tax year and from_week."],"sources":["https://www.gov.uk/guidance/rates-and-thresholds-for-employers-2026-to-2027","https://www.gov.uk/guidance/statutory-sick-pay-manually-calculate-your-employees-payments"]}}}},"400":{"description":"INVALID_INPUT: the message names each field that is wrong.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"UNAUTHENTICATED (no key) or INVALID_KEY (an unknown or revoked key).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"QUOTA_EXCEEDED: the free plan's calculations for the month are used; upgrade_url says where to get more.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"RATE_LIMITED: over the plan's calls a second; Retry-After says when to try again.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"UNAVAILABLE: keys can’t be checked right now; retry with backoff.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/statutory/paternity-pay":{"post":{"operationId":"paternityPay","tags":["Statutory pay"],"summary":"Statutory Paternity Pay","description":"Statutory Paternity Pay, week by week for up to 2 weeks, from average weekly earnings, with eligibility on the lower earnings limit.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"tax_year":{"type":"string","default":"2026-27","description":"The tax year, such as 2026-27. The latest when not given."},"average_weekly_earnings":{"anyOf":[{"type":"object","properties":{"amount":{"type":"number","minimum":0,"exclusiveMaximum":100000000,"description":"Average weekly earnings, when already known."}},"required":["amount"],"additionalProperties":false},{"type":"object","properties":{"earnings":{"type":"number","minimum":0,"exclusiveMaximum":100000000,"description":"Gross earnings paid in the relevant period."},"weeks":{"type":"integer","minimum":1,"maximum":52,"description":"Whole weeks in the relevant period, for weekly, two-weekly and four-weekly pay."}},"required":["earnings","weeks"],"additionalProperties":false},{"type":"object","properties":{"earnings":{"type":"number","minimum":0,"exclusiveMaximum":100000000,"description":"Gross earnings paid in the relevant period."},"months":{"type":"integer","minimum":1,"maximum":12,"description":"Months in the relevant period, for monthly pay."}},"required":["earnings","months"],"additionalProperties":false},{"type":"object","properties":{"earnings":{"type":"number","minimum":0,"exclusiveMaximum":100000000,"description":"Gross earnings paid in the relevant period."},"days":{"type":"integer","minimum":1,"maximum":366,"description":"Days in the relevant period, for irregular pay or a new employee."}},"required":["earnings","days"],"additionalProperties":false}],"description":"Average weekly earnings: { amount } a week, or the earnings in the relevant period with the weeks, months or days to divide them by."},"from_week":{"type":"integer","minimum":1,"maximum":39,"default":1,"description":"The first week of the claim to pay, for a claim split across tax years."},"weeks":{"type":"integer","minimum":1,"maximum":39,"description":"Weeks to pay from from_week, when fewer than the rest."}},"required":["average_weekly_earnings"],"additionalProperties":false},"example":{"average_weekly_earnings":{"amount":400}}}}},"responses":{"200":{"description":"The result, with what produced it, the assumptions and the sources.","content":{"application/json":{"schema":{"type":"object","properties":{"tax_year":{"type":"string"},"engine":{"type":"string"},"hmrc_test_data":{"type":"string"},"average_weekly_earnings":{"type":"number"},"eligible":{"type":"boolean"},"lower_earnings_limit":{"type":"number"},"weeks":{"type":"array","items":{"type":"object","properties":{"from":{"type":"number"},"to":{"type":"number"},"weekly":{"type":"number"}}}},"total":{"type":"number"},"assumptions":{"type":"array","items":{"type":"string"}},"sources":{"type":"array","items":{"type":"string"}}},"required":["tax_year","engine","hmrc_test_data","assumptions","sources"]},"example":{"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","average_weekly_earnings":400,"eligible":true,"lower_earnings_limit":129,"weeks":[{"from":1,"to":2,"weekly":194.32}],"total":388.64,"assumptions":["The lower of £194.32 and 90% of average weekly earnings for each week, up to 2.","Payable when average weekly earnings reach the lower earnings limit. The caller checks the employment conditions (such as 26 weeks with the employer by the qualifying week) and works out the relevant period.","Every week is at this tax year's rates: for weeks after 5 April, ask again with the next tax year and from_week."],"sources":["https://www.gov.uk/guidance/rates-and-thresholds-for-employers-2026-to-2027","https://www.gov.uk/guidance/statutory-sick-pay-manually-calculate-your-employees-payments"]}}}},"400":{"description":"INVALID_INPUT: the message names each field that is wrong.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"UNAUTHENTICATED (no key) or INVALID_KEY (an unknown or revoked key).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"QUOTA_EXCEEDED: the free plan's calculations for the month are used; upgrade_url says where to get more.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"RATE_LIMITED: over the plan's calls a second; Retry-After says when to try again.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"UNAVAILABLE: keys can’t be checked right now; retry with backoff.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/statutory/shared-parental-pay":{"post":{"operationId":"sharedParentalPay","tags":["Statutory pay"],"summary":"Statutory Shared Parental Pay","description":"Statutory Shared Parental Pay, week by week for up to 37 weeks, from average weekly earnings, with eligibility on the lower earnings limit.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"tax_year":{"type":"string","default":"2026-27","description":"The tax year, such as 2026-27. The latest when not given."},"average_weekly_earnings":{"anyOf":[{"type":"object","properties":{"amount":{"type":"number","minimum":0,"exclusiveMaximum":100000000,"description":"Average weekly earnings, when already known."}},"required":["amount"],"additionalProperties":false},{"type":"object","properties":{"earnings":{"type":"number","minimum":0,"exclusiveMaximum":100000000,"description":"Gross earnings paid in the relevant period."},"weeks":{"type":"integer","minimum":1,"maximum":52,"description":"Whole weeks in the relevant period, for weekly, two-weekly and four-weekly pay."}},"required":["earnings","weeks"],"additionalProperties":false},{"type":"object","properties":{"earnings":{"type":"number","minimum":0,"exclusiveMaximum":100000000,"description":"Gross earnings paid in the relevant period."},"months":{"type":"integer","minimum":1,"maximum":12,"description":"Months in the relevant period, for monthly pay."}},"required":["earnings","months"],"additionalProperties":false},{"type":"object","properties":{"earnings":{"type":"number","minimum":0,"exclusiveMaximum":100000000,"description":"Gross earnings paid in the relevant period."},"days":{"type":"integer","minimum":1,"maximum":366,"description":"Days in the relevant period, for irregular pay or a new employee."}},"required":["earnings","days"],"additionalProperties":false}],"description":"Average weekly earnings: { amount } a week, or the earnings in the relevant period with the weeks, months or days to divide them by."},"from_week":{"type":"integer","minimum":1,"maximum":39,"default":1,"description":"The first week of the claim to pay, for a claim split across tax years."},"weeks":{"type":"integer","minimum":1,"maximum":39,"description":"Weeks to pay from from_week, when fewer than the rest."}},"required":["average_weekly_earnings"],"additionalProperties":false},"example":{"average_weekly_earnings":{"amount":400}}}}},"responses":{"200":{"description":"The result, with what produced it, the assumptions and the sources.","content":{"application/json":{"schema":{"type":"object","properties":{"tax_year":{"type":"string"},"engine":{"type":"string"},"hmrc_test_data":{"type":"string"},"average_weekly_earnings":{"type":"number"},"eligible":{"type":"boolean"},"lower_earnings_limit":{"type":"number"},"weeks":{"type":"array","items":{"type":"object","properties":{"from":{"type":"number"},"to":{"type":"number"},"weekly":{"type":"number"}}}},"total":{"type":"number"},"assumptions":{"type":"array","items":{"type":"string"}},"sources":{"type":"array","items":{"type":"string"}}},"required":["tax_year","engine","hmrc_test_data","assumptions","sources"]},"example":{"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","average_weekly_earnings":400,"eligible":true,"lower_earnings_limit":129,"weeks":[{"from":1,"to":37,"weekly":194.32}],"total":7189.84,"assumptions":["The lower of £194.32 and 90% of average weekly earnings for each week, up to 37.","Payable when average weekly earnings reach the lower earnings limit. The caller checks the employment conditions (such as 26 weeks with the employer by the qualifying week) and works out the relevant period.","Every week is at this tax year's rates: for weeks after 5 April, ask again with the next tax year and from_week."],"sources":["https://www.gov.uk/guidance/rates-and-thresholds-for-employers-2026-to-2027","https://www.gov.uk/guidance/statutory-sick-pay-manually-calculate-your-employees-payments"]}}}},"400":{"description":"INVALID_INPUT: the message names each field that is wrong.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"UNAUTHENTICATED (no key) or INVALID_KEY (an unknown or revoked key).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"QUOTA_EXCEEDED: the free plan's calculations for the month are used; upgrade_url says where to get more.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"RATE_LIMITED: over the plan's calls a second; Retry-After says when to try again.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"UNAVAILABLE: keys can’t be checked right now; retry with backoff.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/statutory/parental-bereavement-pay":{"post":{"operationId":"parentalBereavementPay","tags":["Statutory pay"],"summary":"Statutory Parental Bereavement Pay","description":"Statutory Parental Bereavement Pay, week by week for up to 2 weeks, from average weekly earnings, with eligibility on the lower earnings limit.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"tax_year":{"type":"string","default":"2026-27","description":"The tax year, such as 2026-27. The latest when not given."},"average_weekly_earnings":{"anyOf":[{"type":"object","properties":{"amount":{"type":"number","minimum":0,"exclusiveMaximum":100000000,"description":"Average weekly earnings, when already known."}},"required":["amount"],"additionalProperties":false},{"type":"object","properties":{"earnings":{"type":"number","minimum":0,"exclusiveMaximum":100000000,"description":"Gross earnings paid in the relevant period."},"weeks":{"type":"integer","minimum":1,"maximum":52,"description":"Whole weeks in the relevant period, for weekly, two-weekly and four-weekly pay."}},"required":["earnings","weeks"],"additionalProperties":false},{"type":"object","properties":{"earnings":{"type":"number","minimum":0,"exclusiveMaximum":100000000,"description":"Gross earnings paid in the relevant period."},"months":{"type":"integer","minimum":1,"maximum":12,"description":"Months in the relevant period, for monthly pay."}},"required":["earnings","months"],"additionalProperties":false},{"type":"object","properties":{"earnings":{"type":"number","minimum":0,"exclusiveMaximum":100000000,"description":"Gross earnings paid in the relevant period."},"days":{"type":"integer","minimum":1,"maximum":366,"description":"Days in the relevant period, for irregular pay or a new employee."}},"required":["earnings","days"],"additionalProperties":false}],"description":"Average weekly earnings: { amount } a week, or the earnings in the relevant period with the weeks, months or days to divide them by."},"from_week":{"type":"integer","minimum":1,"maximum":39,"default":1,"description":"The first week of the claim to pay, for a claim split across tax years."},"weeks":{"type":"integer","minimum":1,"maximum":39,"description":"Weeks to pay from from_week, when fewer than the rest."}},"required":["average_weekly_earnings"],"additionalProperties":false},"example":{"average_weekly_earnings":{"amount":400}}}}},"responses":{"200":{"description":"The result, with what produced it, the assumptions and the sources.","content":{"application/json":{"schema":{"type":"object","properties":{"tax_year":{"type":"string"},"engine":{"type":"string"},"hmrc_test_data":{"type":"string"},"average_weekly_earnings":{"type":"number"},"eligible":{"type":"boolean"},"lower_earnings_limit":{"type":"number"},"weeks":{"type":"array","items":{"type":"object","properties":{"from":{"type":"number"},"to":{"type":"number"},"weekly":{"type":"number"}}}},"total":{"type":"number"},"assumptions":{"type":"array","items":{"type":"string"}},"sources":{"type":"array","items":{"type":"string"}}},"required":["tax_year","engine","hmrc_test_data","assumptions","sources"]},"example":{"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","average_weekly_earnings":400,"eligible":true,"lower_earnings_limit":129,"weeks":[{"from":1,"to":2,"weekly":194.32}],"total":388.64,"assumptions":["The lower of £194.32 and 90% of average weekly earnings for each week, up to 2.","Payable when average weekly earnings reach the lower earnings limit. The caller checks the employment conditions (such as 26 weeks with the employer by the qualifying week) and works out the relevant period.","Every week is at this tax year's rates: for weeks after 5 April, ask again with the next tax year and from_week."],"sources":["https://www.gov.uk/guidance/rates-and-thresholds-for-employers-2026-to-2027","https://www.gov.uk/guidance/statutory-sick-pay-manually-calculate-your-employees-payments"]}}}},"400":{"description":"INVALID_INPUT: the message names each field that is wrong.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"UNAUTHENTICATED (no key) or INVALID_KEY (an unknown or revoked key).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"QUOTA_EXCEEDED: the free plan's calculations for the month are used; upgrade_url says where to get more.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"RATE_LIMITED: over the plan's calls a second; Retry-After says when to try again.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"UNAVAILABLE: keys can’t be checked right now; retry with backoff.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/statutory/neonatal-care-pay":{"post":{"operationId":"neonatalCarePay","tags":["Statutory pay"],"summary":"Statutory Neonatal Care Pay","description":"Statutory Neonatal Care Pay, week by week for up to 12 weeks, from average weekly earnings, with eligibility on the lower earnings limit.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"tax_year":{"type":"string","default":"2026-27","description":"The tax year, such as 2026-27. The latest when not given."},"average_weekly_earnings":{"anyOf":[{"type":"object","properties":{"amount":{"type":"number","minimum":0,"exclusiveMaximum":100000000,"description":"Average weekly earnings, when already known."}},"required":["amount"],"additionalProperties":false},{"type":"object","properties":{"earnings":{"type":"number","minimum":0,"exclusiveMaximum":100000000,"description":"Gross earnings paid in the relevant period."},"weeks":{"type":"integer","minimum":1,"maximum":52,"description":"Whole weeks in the relevant period, for weekly, two-weekly and four-weekly pay."}},"required":["earnings","weeks"],"additionalProperties":false},{"type":"object","properties":{"earnings":{"type":"number","minimum":0,"exclusiveMaximum":100000000,"description":"Gross earnings paid in the relevant period."},"months":{"type":"integer","minimum":1,"maximum":12,"description":"Months in the relevant period, for monthly pay."}},"required":["earnings","months"],"additionalProperties":false},{"type":"object","properties":{"earnings":{"type":"number","minimum":0,"exclusiveMaximum":100000000,"description":"Gross earnings paid in the relevant period."},"days":{"type":"integer","minimum":1,"maximum":366,"description":"Days in the relevant period, for irregular pay or a new employee."}},"required":["earnings","days"],"additionalProperties":false}],"description":"Average weekly earnings: { amount } a week, or the earnings in the relevant period with the weeks, months or days to divide them by."},"from_week":{"type":"integer","minimum":1,"maximum":39,"default":1,"description":"The first week of the claim to pay, for a claim split across tax years."},"weeks":{"type":"integer","minimum":1,"maximum":39,"description":"Weeks to pay from from_week, when fewer than the rest."}},"required":["average_weekly_earnings"],"additionalProperties":false},"example":{"average_weekly_earnings":{"amount":400}}}}},"responses":{"200":{"description":"The result, with what produced it, the assumptions and the sources.","content":{"application/json":{"schema":{"type":"object","properties":{"tax_year":{"type":"string"},"engine":{"type":"string"},"hmrc_test_data":{"type":"string"},"average_weekly_earnings":{"type":"number"},"eligible":{"type":"boolean"},"lower_earnings_limit":{"type":"number"},"weeks":{"type":"array","items":{"type":"object","properties":{"from":{"type":"number"},"to":{"type":"number"},"weekly":{"type":"number"}}}},"total":{"type":"number"},"assumptions":{"type":"array","items":{"type":"string"}},"sources":{"type":"array","items":{"type":"string"}}},"required":["tax_year","engine","hmrc_test_data","assumptions","sources"]},"example":{"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","average_weekly_earnings":400,"eligible":true,"lower_earnings_limit":129,"weeks":[{"from":1,"to":12,"weekly":194.32}],"total":2331.84,"assumptions":["The lower of £194.32 and 90% of average weekly earnings for each week, up to 12.","Payable when average weekly earnings reach the lower earnings limit. The caller checks the employment conditions (such as 26 weeks with the employer by the qualifying week) and works out the relevant period.","Every week is at this tax year's rates: for weeks after 5 April, ask again with the next tax year and from_week."],"sources":["https://www.gov.uk/guidance/rates-and-thresholds-for-employers-2026-to-2027","https://www.gov.uk/guidance/statutory-sick-pay-manually-calculate-your-employees-payments"]}}}},"400":{"description":"INVALID_INPUT: the message names each field that is wrong.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"UNAUTHENTICATED (no key) or INVALID_KEY (an unknown or revoked key).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"QUOTA_EXCEEDED: the free plan's calculations for the month are used; upgrade_url says where to get more.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"RATE_LIMITED: over the plan's calls a second; Retry-After says when to try again.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"UNAVAILABLE: keys can’t be checked right now; retry with backoff.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/redundancy-pay":{"post":{"operationId":"redundancyPay","tags":["Entitlements"],"summary":"Statutory redundancy pay","description":"Statutory redundancy pay from age, full years of service and weekly pay, with the weekly cap.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"tax_year":{"type":"string","default":"2026-27","description":"The tax year, such as 2026-27. The latest when not given."},"age":{"type":"integer","minimum":16,"maximum":100,"description":"Age at the redundancy, in whole years."},"years_of_service":{"type":"integer","minimum":0,"maximum":84,"description":"Full years of continuous employment."},"weekly_pay":{"type":"number","minimum":0,"exclusiveMaximum":100000000,"description":"Gross weekly pay."}},"required":["age","years_of_service","weekly_pay"],"additionalProperties":false},"example":{"age":45,"years_of_service":10,"weekly_pay":800}}}},"responses":{"200":{"description":"The result, with what produced it, the assumptions and the sources.","content":{"application/json":{"schema":{"type":"object","properties":{"tax_year":{"type":"string"},"engine":{"type":"string"},"hmrc_test_data":{"type":"string"},"eligible":{"type":"boolean"},"weeks":{"type":"number"},"weekly_pay":{"type":"number"},"weekly_pay_cap":{"type":"number"},"amount":{"type":"number"},"assumptions":{"type":"array","items":{"type":"string"}},"sources":{"type":"array","items":{"type":"string"}}},"required":["tax_year","engine","hmrc_test_data","assumptions","sources"]},"example":{"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","eligible":true,"weeks":12,"weekly_pay":751,"weekly_pay_cap":751,"amount":9012,"assumptions":["Statutory redundancy pay needs 2 years of continuous employment. Counting back from the redundancy over at most 20 years: half a week for each year under 22, a week from 22, a week and a half from 41, a year counting at the age at its start.","Weekly pay is capped at £751 for redundancies on or after 6 April 2026.","A contract can pay more: this is the legal minimum."],"sources":["https://www.gov.uk/redundant-your-rights/redundancy-pay"]}}}},"400":{"description":"INVALID_INPUT: the message names each field that is wrong.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"UNAUTHENTICATED (no key) or INVALID_KEY (an unknown or revoked key).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"QUOTA_EXCEEDED: the free plan's calculations for the month are used; upgrade_url says where to get more.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"RATE_LIMITED: over the plan's calls a second; Retry-After says when to try again.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"UNAVAILABLE: keys can’t be checked right now; retry with backoff.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/notice-pay":{"post":{"operationId":"noticePay","tags":["Entitlements"],"summary":"Statutory notice","description":"The least notice an employer must give, and the notice pay for it when a weekly pay is given.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"tax_year":{"type":"string","default":"2026-27","description":"The tax year, such as 2026-27. The latest when not given."},"months_of_service":{"type":"integer","minimum":0,"maximum":1000,"description":"Months of continuous employment."},"weekly_pay":{"type":"number","minimum":0,"exclusiveMaximum":100000000,"description":"A week's pay, for the notice pay."}},"required":["months_of_service"],"additionalProperties":false},"example":{"months_of_service":59,"weekly_pay":512.5}}}},"responses":{"200":{"description":"The result, with what produced it, the assumptions and the sources.","content":{"application/json":{"schema":{"type":"object","properties":{"tax_year":{"type":"string"},"engine":{"type":"string"},"hmrc_test_data":{"type":"string"},"notice_weeks":{"type":"number"},"notice_pay":{"type":["number","null"]},"assumptions":{"type":"array","items":{"type":"string"}},"sources":{"type":"array","items":{"type":"string"}}},"required":["tax_year","engine","hmrc_test_data","assumptions","sources"]},"example":{"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"]}}}},"400":{"description":"INVALID_INPUT: the message names each field that is wrong.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"UNAUTHENTICATED (no key) or INVALID_KEY (an unknown or revoked key).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"QUOTA_EXCEEDED: the free plan's calculations for the month are used; upgrade_url says where to get more.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"RATE_LIMITED: over the plan's calls a second; Retry-After says when to try again.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"UNAVAILABLE: keys can’t be checked right now; retry with backoff.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/holiday-entitlement":{"post":{"operationId":"holidayEntitlement","tags":["Entitlements"],"summary":"Holiday entitlement","description":"Statutory annual leave from days worked a week, or the holiday an irregular hours or part-year worker accrues from hours worked (12.07%).","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"tax_year":{"type":"string","default":"2026-27","description":"The tax year, such as 2026-27. The latest when not given."},"days_per_week":{"type":"number","exclusiveMinimum":0,"maximum":7,"description":"Days worked a week, for a regular pattern."},"hours_worked":{"type":"number","minimum":0,"maximum":744,"description":"Hours worked in a pay period, for an irregular hours or part-year worker."}},"additionalProperties":false},"example":{"days_per_week":4}}}},"responses":{"200":{"description":"The result, with what produced it, the assumptions and the sources.","content":{"application/json":{"schema":{"type":"object","properties":{"tax_year":{"type":"string"},"engine":{"type":"string"},"hmrc_test_data":{"type":"string"},"days":{"type":"number"},"capped":{"type":"boolean"},"assumptions":{"type":"array","items":{"type":"string"}},"sources":{"type":"array","items":{"type":"string"}},"accrued_hours":{"type":"number"}},"required":["tax_year","engine","hmrc_test_data","assumptions","sources"]},"example":{"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","days":22.4,"capped":false,"assumptions":["Statutory annual leave is 5.6 weeks of the working pattern, at most 28 days, not rounded to whole days. Bank holidays can be counted in it."],"sources":["https://www.gov.uk/holiday-entitlement-rights","https://www.legislation.gov.uk/uksi/1998/1833/regulation/13"]}}}},"400":{"description":"INVALID_INPUT: the message names each field that is wrong.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"UNAUTHENTICATED (no key) or INVALID_KEY (an unknown or revoked key).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"QUOTA_EXCEEDED: the free plan's calculations for the month are used; upgrade_url says where to get more.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"RATE_LIMITED: over the plan's calls a second; Retry-After says when to try again.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"UNAVAILABLE: keys can’t be checked right now; retry with backoff.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/minimum-wage-check":{"post":{"operationId":"minimumWageCheck","tags":["Entitlements"],"summary":"Minimum wage check","description":"Whether pay for the hours worked meets the National Minimum Wage or National Living Wage for the age, and by how much it falls short.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"tax_year":{"type":"string","default":"2026-27","description":"The tax year, such as 2026-27. The latest when not given."},"age":{"type":"integer","minimum":16,"maximum":100,"description":"The minimum wage applies from school-leaving age."},"apprentice":{"type":"boolean","default":false,"description":"An apprentice."},"apprentice_first_year":{"type":"boolean","default":false,"description":"In the first year of the apprenticeship."},"pay":{"type":"number","minimum":0,"exclusiveMaximum":100000000,"description":"Pay for the period."},"hours":{"type":"number","minimum":0.01,"maximum":744,"description":"Hours worked in the period, to two decimal places."}},"required":["age","pay","hours"],"additionalProperties":false},"example":{"age":25,"pay":1300,"hours":100}}}},"responses":{"200":{"description":"The result, with what produced it, the assumptions and the sources.","content":{"application/json":{"schema":{"type":"object","properties":{"tax_year":{"type":"string"},"engine":{"type":"string"},"hmrc_test_data":{"type":"string"},"band":{"type":"string"},"rate":{"type":"number"},"hourly_pay":{"type":"number"},"meets_minimum":{"type":"boolean"},"shortfall":{"type":"number"},"assumptions":{"type":"array","items":{"type":"string"}},"sources":{"type":"array","items":{"type":"string"}}},"required":["tax_year","engine","hmrc_test_data","assumptions","sources"]},"example":{"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","band":"aged21AndOver","rate":12.71,"hourly_pay":13,"meets_minimum":true,"shortfall":0,"assumptions":["The apprentice rate applies under 19 or in the first year of an apprenticeship; after that, the rate for the age.","pay is what counts towards the minimum wage for the hours given: the caller leaves out what does not (tips, most premiums, some deductions)."],"sources":["https://www.gov.uk/national-minimum-wage-rates"]}}}},"400":{"description":"INVALID_INPUT: the message names each field that is wrong.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"UNAUTHENTICATED (no key) or INVALID_KEY (an unknown or revoked key).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"QUOTA_EXCEEDED: the free plan's calculations for the month are used; upgrade_url says where to get more.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"RATE_LIMITED: over the plan's calls a second; Retry-After says when to try again.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"UNAVAILABLE: keys can’t be checked right now; retry with backoff.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/self-employed":{"post":{"operationId":"selfEmployed","tags":["Contractors"],"summary":"Self-employed take-home","description":"A sole trader's year through Self Assessment: income tax, Class 4 NI, voluntary Class 2, student loans and relief at source pension contributions.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"tax_year":{"type":"string","default":"2026-27","description":"The tax year, such as 2026-27. The latest when not given."},"region":{"type":"string","enum":["england","scotland","wales","northern_ireland"],"description":"Where they live: england, scotland, wales or northern_ireland."},"profit":{"type":"number","minimum":0,"exclusiveMaximum":100000000,"description":"Taxable profits for the year."},"pension":{"type":"number","minimum":0,"exclusiveMaximum":100000000,"default":0,"description":"Gross relief at source pension contributions for the year."},"student_loans":{"type":"array","items":{"type":"string","enum":["plan_1","plan_2","plan_4","plan_5","postgraduate"]},"default":[],"description":"Each loan they repay: plan_1, plan_2, plan_4, plan_5, postgraduate."},"voluntary_class_2":{"type":"boolean","default":false,"description":"Pays voluntary Class 2 NI, for a year of State Pension with profits below the small profits threshold."},"blind":{"type":"boolean","default":false,"description":"Blind Person's Allowance."},"marriage_allowance":{"type":"string","enum":["transferring","receiving"],"description":"Marriage Allowance: transferring or receiving."}},"required":["region","profit"],"additionalProperties":false},"example":{"region":"england","profit":50000,"student_loans":["plan_2"]}}}},"responses":{"200":{"description":"The result, with what produced it, the assumptions and the sources.","content":{"application/json":{"schema":{"type":"object","properties":{"tax_year":{"type":"string"},"engine":{"type":"string"},"hmrc_test_data":{"type":"string"},"income_tax":{"type":"object","properties":{"adjusted_net_income":{"type":"number"},"allowances":{"type":"number"},"income_bands":{"type":"array","items":{"type":"object","properties":{"rate":{"type":"number"},"taxable":{"type":"number"},"tax":{"type":"number"}}}},"dividend_bands":{"type":"array","items":{}},"marriage_allowance_reduction":{"type":"number"},"tax":{"type":"number"}}},"class_4_ni":{"type":"number"},"class_2_ni":{"type":"number"},"student_loans":{"type":"object","properties":{"plan_2":{"type":"number"}}},"pension":{"type":"number"},"take_home":{"type":"number"},"assumptions":{"type":"array","items":{"type":"string"}},"sources":{"type":"array","items":{"type":"string"}}},"required":["tax_year","engine","hmrc_test_data","assumptions","sources"]},"example":{"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","income_tax":{"adjusted_net_income":50000,"allowances":12570,"income_bands":[{"rate":20,"taxable":37430,"tax":7486}],"dividend_bands":[],"marriage_allowance_reduction":0,"tax":7486},"class_4_ni":2245.8,"class_2_ni":0,"student_loans":{"plan_2":1855},"pension":0,"take_home":38413.2,"assumptions":["A year of Self Assessment on trading profits: income tax, Class 4 NI and student loans. Class 2 is treated as paid at or above the small profits threshold, and only paid voluntarily below it when asked.","pension is gross relief at source contributions: they cost 80% and widen the basic rate band. The caller checks Marriage Allowance is only received by a basic rate taxpayer.","Payments on account and the timing of payments are not shown."],"sources":["https://www.gov.uk/self-employed-national-insurance-rates","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/payroll-technical-specifications-student-loans/collection-of-student-loans-from-6-april-2026"]}}}},"400":{"description":"INVALID_INPUT: the message names each field that is wrong.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"UNAUTHENTICATED (no key) or INVALID_KEY (an unknown or revoked key).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"QUOTA_EXCEEDED: the free plan's calculations for the month are used; upgrade_url says where to get more.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"RATE_LIMITED: over the plan's calls a second; Retry-After says when to try again.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"UNAVAILABLE: keys can’t be checked right now; retry with backoff.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/director-pay":{"post":{"operationId":"directorPay","tags":["Contractors"],"summary":"Director salary and dividends","description":"A director paid from their own company: corporation tax with marginal relief, employer and employee NI, dividend tax and take-home. Give a salary and dividends, or leave the salary out to try the usual choices.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"tax_year":{"type":"string","default":"2026-27","description":"The tax year, such as 2026-27. The latest when not given."},"region":{"type":"string","enum":["england","scotland","wales","northern_ireland"],"description":"Where they live: england, scotland, wales or northern_ireland."},"profit":{"type":"number","minimum":0,"exclusiveMaximum":100000000,"description":"The company's profit for the year before the director's salary and its employer NI."},"salary":{"type":"number","minimum":0,"exclusiveMaximum":100000000,"description":"The director's salary for the year; the usual choices are tried when not given."},"dividends":{"type":"number","minimum":0,"exclusiveMaximum":100000000,"description":"Dividends paid; all the profit left after corporation tax when not given."},"employer_pension":{"type":"number","minimum":0,"exclusiveMaximum":100000000,"default":0,"description":"The company's pension contribution for the director."},"employment_allowance":{"type":"boolean","default":false,"description":"Sets the Employment Allowance against employer NI. Not available where the director is the only employee paid above the secondary threshold."},"student_loans":{"type":"array","items":{"type":"string","enum":["plan_1","plan_2","plan_4","plan_5","postgraduate"]},"default":[],"description":"Each loan they repay: plan_1, plan_2, plan_4, plan_5, postgraduate."}},"required":["region","profit"],"additionalProperties":false},"example":{"region":"england","profit":100000}}}},"responses":{"200":{"description":"The result, with what produced it, the assumptions and the sources.","content":{"application/json":{"schema":{"type":"object","properties":{"tax_year":{"type":"string"},"engine":{"type":"string"},"hmrc_test_data":{"type":"string"},"salary_basis":{"type":"string"},"company":{"type":"object","properties":{"salary":{"type":"number"},"employer_ni":{"type":"number"},"employer_pension":{"type":"number"},"taxable_profit":{"type":"number"},"corporation_tax":{"type":"number"},"dividends":{"type":"number"},"retained":{"type":"number"}}},"director":{"type":"object","properties":{"salary":{"type":"number"},"employee_ni":{"type":"number"},"dividends":{"type":"number"},"income_tax":{"type":"object","properties":{"adjusted_net_income":{"type":"number"},"allowances":{"type":"number"},"income_bands":{"type":"array","items":{}},"dividend_bands":{"type":"array","items":{"type":"object","properties":{"rate":{"type":"number"},"taxable":{"type":"number"},"tax":{"type":"number"}}}},"marriage_allowance_reduction":{"type":"number"},"tax":{"type":"number"}}},"student_loans":{"type":"object","properties":{}},"take_home":{"type":"number"}}},"tried":{"type":"array","items":{"type":"object","properties":{"salary":{"type":"number"},"take_home":{"type":"number"}}}},"assumptions":{"type":"array","items":{"type":"string"}},"sources":{"type":"array","items":{"type":"string"}},"dividends_capped":{"type":"boolean"}},"required":["tax_year","engine","hmrc_test_data","assumptions","sources"]},"example":{"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","salary_basis":"usual_choices","company":{"salary":12570,"employer_ni":1135.5,"employer_pension":0,"taxable_profit":86294,"corporation_tax":19117.91,"dividends":67176.59,"retained":0},"director":{"salary":12570,"employee_ni":0,"dividends":67176.59,"income_tax":{"adjusted_net_income":79746.59,"allowances":12570,"income_bands":[],"dividend_bands":[{"rate":0,"taxable":500,"tax":0},{"rate":10.75,"taxable":37200,"tax":3999},{"rate":35.75,"taxable":29476,"tax":10537.67}],"marriage_allowance_reduction":0,"tax":14536.67},"student_loans":{},"take_home":65209.92},"tried":[{"salary":0,"take_home":63605.65},{"salary":5000,"take_home":64456.97},{"salary":6708,"take_home":64627.12},{"salary":12570,"take_home":65209.92}],"assumptions":["With no salary given, the usual salaries are tried (none, the secondary threshold, the lower earnings limit, the primary threshold, and with Employment Allowance the salary it covers) as far as the profit can pay them, each with the rest as dividends; the one leaving the most is shown. This is not a full search: at high profits another salary can leave a little more.","Corporation tax is for a 12-month accounting period with no associated companies, with marginal relief between the limits.","Employment Allowance (employment_allowance) is not available to a company whose only employee paid above the secondary threshold is a director: the caller checks it applies.","The director's NI is on the annual earnings period, category A. Income tax is on the year's salary and dividends together, as Self Assessment settles it."],"sources":["https://www.gov.uk/corporation-tax-rates","https://www.gov.uk/guidance/corporation-tax-marginal-relief","https://www.gov.uk/tax-on-dividends","https://www.gov.uk/government/publications/payroll-technical-specifications-national-insurance","https://www.gov.uk/guidance/rates-and-thresholds-for-employers-2026-to-2027","https://www.thepensionsregulator.gov.uk/en/business-advisers/automatic-enrolment-guide-for-business-advisers/minimum-contribution-increases-planned-by-law-phasing"]}}}},"400":{"description":"INVALID_INPUT: the message names each field that is wrong.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"UNAUTHENTICATED (no key) or INVALID_KEY (an unknown or revoked key).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"QUOTA_EXCEEDED: the free plan's calculations for the month are used; upgrade_url says where to get more.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"RATE_LIMITED: over the plan's calls a second; Retry-After says when to try again.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"UNAVAILABLE: keys can’t be checked right now; retry with backoff.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/umbrella-pay":{"post":{"operationId":"umbrellaPay","tags":["Contractors"],"summary":"Umbrella company pay","description":"Inside IR35 through an umbrella: the salary its margin and employment costs leave from a day rate, and the take-home on it.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"tax_year":{"type":"string","default":"2026-27","description":"The tax year, such as 2026-27. The latest when not given."},"region":{"type":"string","enum":["england","scotland","wales","northern_ireland"],"description":"Where the employee lives: england, scotland, wales or northern_ireland. Needed unless tax_code is given (its S or C prefix sets the region)."},"pay_frequency":{"type":"string","enum":["monthly","four_weekly","two_weekly","weekly"],"default":"monthly","description":"How often they are paid: monthly (when not given), four_weekly, two_weekly or weekly. Each period runs through payroll."},"working_pattern":{"type":"object","properties":{"days_per_week":{"type":"number","exclusiveMinimum":0,"maximum":7,"default":5,"description":"Days worked a week: 5 when not given."},"hours_per_week":{"type":"number","exclusiveMinimum":0,"maximum":168,"default":37.5,"description":"Hours worked a week: 37.5 when not given."},"weeks_per_year":{"type":"number","minimum":1,"maximum":53,"default":52,"description":"Weeks paid a year: 52 when not given."}},"additionalProperties":false,"description":"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."},"tax_code":{"type":"string","maxLength":20,"description":"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":{"type":"string","enum":["A","B","C","D","E","F","H","I","J","K","L","M","N","S","V","Z"],"default":"A","description":"National Insurance category letter: A when not given, C over State Pension age."},"student_loans":{"type":"array","items":{"type":"string","enum":["plan_1","plan_2","plan_4","plan_5","postgraduate"]},"description":"Each loan they repay: plan_1, plan_2, plan_4, plan_5, postgraduate."},"pension":{"type":"object","properties":{"method":{"type":"string","enum":["relief_at_source","net_pay","salary_sacrifice"],"description":"How the contribution is taken: relief_at_source, net_pay or salary_sacrifice."},"percent":{"type":"number","minimum":0,"maximum":100,"description":"A percentage of pensionable pay."},"basis":{"type":"string","enum":["pay","qualifying_earnings"],"description":"Pensionable pay: all of it (pay), or only automatic enrolment qualifying earnings. Pay when not given."},"includes":{"type":"array","items":{"type":"string","enum":["overtime","allowances","bonus"]},"description":"Pay besides salary that is pensionable: overtime, allowances, bonus."},"amount":{"type":"object","properties":{"amount":{"type":"number","minimum":0,"exclusiveMaximum":100000000,"description":"Pounds and pence."},"per":{"type":"string","enum":["year","month","four_weeks","two_weeks","week","day","hour"],"description":"The period the amount is for."}},"required":["amount","per"],"additionalProperties":false,"description":"A fixed contribution instead of a percent."}},"required":["method"],"additionalProperties":false,"description":"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."},"employer_pension":{"anyOf":[{"type":"string","const":"auto_enrolment_minimum"},{"type":"object","properties":{"percent":{"type":"number","minimum":0,"maximum":100,"description":"A percentage of pensionable pay."},"basis":{"type":"string","enum":["pay","qualifying_earnings"],"description":"Pensionable pay: all of it (pay), or only automatic enrolment qualifying earnings. Pay when not given."},"includes":{"type":"array","items":{"type":"string","enum":["overtime","allowances","bonus"]},"description":"Pay besides salary that is pensionable: overtime, allowances, bonus."},"amount":{"type":"object","properties":{"amount":{"type":"number","minimum":0,"exclusiveMaximum":100000000,"description":"Pounds and pence."},"per":{"type":"string","enum":["year","month","four_weeks","two_weeks","week","day","hour"],"description":"The period the amount is for."}},"required":["amount","per"],"additionalProperties":false,"description":"A fixed contribution instead of a percent."}},"additionalProperties":false}],"description":"The employer's contribution, on top of pay: auto_enrolment_minimum (3% of qualifying earnings), or a percent or amount."},"overtime":{"type":"array","items":{"anyOf":[{"type":"object","properties":{"amount":{"type":"number","minimum":0,"exclusiveMaximum":100000000,"description":"Pounds and pence."},"per":{"type":"string","enum":["year","month","four_weeks","two_weeks","week","day","hour"],"description":"The period the amount is for."}},"required":["amount","per"],"additionalProperties":false},{"type":"object","properties":{"hours":{"type":"number","minimum":0,"maximum":168,"description":"Overtime hours."},"multiplier":{"type":"number","minimum":0,"maximum":10,"description":"Times the salary's hourly rate: 1.5 for time and a half."},"per":{"type":"string","enum":["year","month","four_weeks","two_weeks","week","day","hour"],"description":"The period the amount or hours are for."}},"required":["hours","multiplier","per"],"additionalProperties":false}]},"maxItems":20,"description":"Overtime: amounts per period, or hours at a multiple of the hourly rate per period."},"allowances":{"type":"object","properties":{"amount":{"type":"number","minimum":0,"exclusiveMaximum":100000000,"description":"Pounds and pence."},"per":{"type":"string","enum":["year","month","four_weeks","two_weeks","week","day","hour"],"description":"The period the amount is for."}},"required":["amount","per"],"additionalProperties":false,"description":"Cash allowances, taxed and NI'd like salary."},"bonus":{"type":"object","properties":{"amount":{"type":"number","minimum":0,"exclusiveMaximum":100000000,"description":"The bonus, in pounds and pence."},"pay_period":{"type":"integer","minimum":1,"maximum":52,"description":"The pay period it is paid in: 1 is the first of the tax year."}},"required":["amount"],"additionalProperties":false,"description":"A one-off bonus, paid in pay_period (the last pay period of the year when not given)."},"salary_sacrifice":{"type":"object","properties":{"amount":{"type":"number","minimum":0,"exclusiveMaximum":100000000,"description":"Pounds and pence."},"per":{"type":"string","enum":["year","month","four_weeks","two_weeks","week","day","hour"],"description":"The period the amount is for."}},"required":["amount","per"],"additionalProperties":false,"description":"Salary given up for something other than a pension: free of tax and NI."},"benefits_in_kind":{"type":"object","properties":{"amount":{"type":"number","minimum":0,"exclusiveMaximum":100000000,"description":"Pounds and pence."},"per":{"type":"string","enum":["year","month","four_weeks","two_weeks","week","day","hour"],"description":"The period the amount is for."}},"required":["amount","per"],"additionalProperties":false,"description":"Taxable benefits in kind, collected through the tax code."},"childcare_vouchers":{"type":"object","properties":{"amount":{"type":"number","minimum":0,"exclusiveMaximum":100000000,"description":"Pounds and pence."},"per":{"type":"string","enum":["year","month","four_weeks","two_weeks","week","day","hour"],"description":"The period the amount is for."},"joined_before_2011":{"type":"boolean","description":"Joined the scheme before 6 April 2011."}},"required":["amount","per"],"additionalProperties":false,"description":"Childcare vouchers taken from pay; joined_before_2011 gives the old scheme’s basic rate exempt amount."},"pre_tax_deductions":{"type":"object","properties":{"amount":{"type":"number","minimum":0,"exclusiveMaximum":100000000,"description":"Pounds and pence."},"per":{"type":"string","enum":["year","month","four_weeks","two_weeks","week","day","hour"],"description":"The period the amount is for."}},"required":["amount","per"],"additionalProperties":false,"description":"Deductions before tax but after NI, such as payroll giving."},"post_tax_deductions":{"type":"object","properties":{"amount":{"type":"number","minimum":0,"exclusiveMaximum":100000000,"description":"Pounds and pence."},"per":{"type":"string","enum":["year","month","four_weeks","two_weeks","week","day","hour"],"description":"The period the amount is for."}},"required":["amount","per"],"additionalProperties":false,"description":"Deductions from net pay."},"blind":{"type":"boolean","description":"Blind Person's Allowance."},"marriage_allowance":{"type":"string","enum":["transferring","receiving"],"description":"Marriage Allowance: transferring or receiving."},"married_couples_allowance":{"type":"boolean","description":"Claims Married Couple's Allowance (one of the couple born before 6 April 1935)."},"child_benefit":{"type":"object","properties":{"children":{"type":"integer","minimum":1,"maximum":20,"description":"Children Child Benefit is paid for."},"weeks":{"type":"integer","minimum":1,"maximum":53,"description":"Weeks of the tax year it is paid for: all of them when not given."}},"required":["children"],"additionalProperties":false,"description":"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)."},"income":{"type":"object","properties":{"amount":{"type":"number","minimum":0,"exclusiveMaximum":100000000,"description":"Pounds and pence."},"per":{"type":"string","enum":["year","month","four_weeks","two_weeks","week","day","hour"],"description":"The period the amount is for."}},"required":["amount","per"],"additionalProperties":false,"description":"Contract income: a day rate per day, or an amount a year, month or week."},"margin":{"type":"object","properties":{"amount":{"type":"number","minimum":0,"exclusiveMaximum":100000000,"description":"Pounds and pence."},"per":{"type":"string","enum":["year","month","four_weeks","two_weeks","week","day","hour"],"description":"The period the amount is for."}},"required":["amount","per"],"additionalProperties":false,"description":"The umbrella's margin."},"apprenticeship_levy":{"type":"boolean","default":true,"description":"Counts the Apprenticeship Levy in the umbrella's costs (0.5% of pay, for an umbrella whose pay bill is over £3 million). True when not given."}},"required":["income","margin"],"additionalProperties":false},"example":{"region":"england","income":{"amount":500,"per":"day"},"margin":{"amount":25,"per":"week"}}}}},"responses":{"200":{"description":"The result, with what produced it, the assumptions and the sources.","content":{"application/json":{"schema":{"type":"object","properties":{"tax_year":{"type":"string"},"engine":{"type":"string"},"hmrc_test_data":{"type":"string"},"salary":{"type":"number"},"within_budget":{"type":"boolean"},"cost":{"type":"object","properties":{"pay":{"type":"number"},"employer_ni":{"type":"number"},"employer_pension":{"type":"number"},"apprenticeship_levy":{"type":"number"},"total":{"type":"number"}}},"employee":{"type":"object","properties":{"tax_code":{"type":"string"},"tax_code_derived":{"type":"boolean"},"tax_region":{"type":"string"},"pay_frequency":{"type":"string"},"personal_allowance":{"type":"number"},"adjusted_net_income":{"type":"number"},"benefits_in_kind":{"type":"number"},"married_couples_allowance":{"type":"number"},"childcare_voucher_band":{},"child_benefit":{},"periods":{"type":"object","properties":{"year":{"type":"object","properties":{"gross":{"type":"number"},"salary_sacrifice":{"type":"number"},"childcare_vouchers":{"type":"number"},"pension":{"type":"number"},"pension_contribution":{"type":"number"},"employer_pension":{"type":"number"},"pre_tax_deductions":{"type":"number"},"niable_pay":{"type":"number"},"taxable_pay":{"type":"number"},"tax":{"type":"number"},"employee_ni":{"type":"number"},"employer_ni":{"type":"number"},"student_loans":{"type":"object","properties":{}},"post_tax_deductions":{"type":"number"},"take_home":{"type":"number"}}},"month":{"type":"object","properties":{"gross":{"type":"number"},"salary_sacrifice":{"type":"number"},"childcare_vouchers":{"type":"number"},"pension":{"type":"number"},"pension_contribution":{"type":"number"},"employer_pension":{"type":"number"},"pre_tax_deductions":{"type":"number"},"niable_pay":{"type":"number"},"taxable_pay":{"type":"number"},"tax":{"type":"number"},"employee_ni":{"type":"number"},"employer_ni":{"type":"number"},"student_loans":{"type":"object","properties":{}},"post_tax_deductions":{"type":"number"},"take_home":{"type":"number"}}},"four_weeks":{"type":"object","properties":{"gross":{"type":"number"},"salary_sacrifice":{"type":"number"},"childcare_vouchers":{"type":"number"},"pension":{"type":"number"},"pension_contribution":{"type":"number"},"employer_pension":{"type":"number"},"pre_tax_deductions":{"type":"number"},"niable_pay":{"type":"number"},"taxable_pay":{"type":"number"},"tax":{"type":"number"},"employee_ni":{"type":"number"},"employer_ni":{"type":"number"},"student_loans":{"type":"object","properties":{}},"post_tax_deductions":{"type":"number"},"take_home":{"type":"number"}}},"two_weeks":{"type":"object","properties":{"gross":{"type":"number"},"salary_sacrifice":{"type":"number"},"childcare_vouchers":{"type":"number"},"pension":{"type":"number"},"pension_contribution":{"type":"number"},"employer_pension":{"type":"number"},"pre_tax_deductions":{"type":"number"},"niable_pay":{"type":"number"},"taxable_pay":{"type":"number"},"tax":{"type":"number"},"employee_ni":{"type":"number"},"employer_ni":{"type":"number"},"student_loans":{"type":"object","properties":{}},"post_tax_deductions":{"type":"number"},"take_home":{"type":"number"}}},"week":{"type":"object","properties":{"gross":{"type":"number"},"salary_sacrifice":{"type":"number"},"childcare_vouchers":{"type":"number"},"pension":{"type":"number"},"pension_contribution":{"type":"number"},"employer_pension":{"type":"number"},"pre_tax_deductions":{"type":"number"},"niable_pay":{"type":"number"},"taxable_pay":{"type":"number"},"tax":{"type":"number"},"employee_ni":{"type":"number"},"employer_ni":{"type":"number"},"student_loans":{"type":"object","properties":{}},"post_tax_deductions":{"type":"number"},"take_home":{"type":"number"}}},"day":{"type":"object","properties":{"gross":{"type":"number"},"salary_sacrifice":{"type":"number"},"childcare_vouchers":{"type":"number"},"pension":{"type":"number"},"pension_contribution":{"type":"number"},"employer_pension":{"type":"number"},"pre_tax_deductions":{"type":"number"},"niable_pay":{"type":"number"},"taxable_pay":{"type":"number"},"tax":{"type":"number"},"employee_ni":{"type":"number"},"employer_ni":{"type":"number"},"student_loans":{"type":"object","properties":{}},"post_tax_deductions":{"type":"number"},"take_home":{"type":"number"}}},"hour":{"type":"object","properties":{"gross":{"type":"number"},"salary_sacrifice":{"type":"number"},"childcare_vouchers":{"type":"number"},"pension":{"type":"number"},"pension_contribution":{"type":"number"},"employer_pension":{"type":"number"},"pre_tax_deductions":{"type":"number"},"niable_pay":{"type":"number"},"taxable_pay":{"type":"number"},"tax":{"type":"number"},"employee_ni":{"type":"number"},"employer_ni":{"type":"number"},"student_loans":{"type":"object","properties":{}},"post_tax_deductions":{"type":"number"},"take_home":{"type":"number"}}}}},"payslips":{"type":"array","items":{"type":"object","properties":{"period":{"type":"number"},"gross":{"type":"number"},"salary_sacrifice":{"type":"number"},"childcare_vouchers":{"type":"number"},"pension":{"type":"number"},"pension_contribution":{"type":"number"},"employer_pension":{"type":"number"},"pre_tax_deductions":{"type":"number"},"niable_pay":{"type":"number"},"taxable_pay":{"type":"number"},"tax":{"type":"number"},"employee_ni":{"type":"number"},"employer_ni":{"type":"number"},"student_loans":{"type":"object","properties":{}},"post_tax_deductions":{"type":"number"},"take_home":{"type":"number"}}}},"tax_bands":{"type":"array","items":{"type":"object","properties":{"rate":{"type":"number"},"taxable":{"type":"number"},"tax":{"type":"number"}}}},"rates":{"type":"object","properties":{"effective":{"type":"number"},"marginal":{"type":"number"}}}}},"assumptions":{"type":"array","items":{"type":"string"}},"sources":{"type":"array","items":{"type":"string"}}},"required":["tax_year","engine","hmrc_test_data","assumptions","sources"]},"example":{"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","salary":112078.45,"within_budget":true,"cost":{"pay":112078.45,"employer_ni":16061.16,"employer_pension":0,"apprenticeship_levy":560.39,"total":128700},"employee":{"tax_code":"653L","tax_code_derived":true,"tax_region":"rest_of_uk","pay_frequency":"monthly","personal_allowance":6531,"adjusted_net_income":112078.45,"benefits_in_kind":0,"married_couples_allowance":0,"childcare_voucher_band":null,"child_benefit":null,"periods":{"year":{"gross":112078.45,"salary_sacrifice":0,"childcare_vouchers":0,"pension":0,"pension_contribution":0,"employer_pension":0,"pre_tax_deductions":0,"niable_pay":112078.45,"taxable_pay":112078.45,"tax":34675.6,"employee_ni":4251.6,"employer_ni":16061.16,"student_loans":{},"post_tax_deductions":0,"take_home":73151.25},"month":{"gross":9339.87,"salary_sacrifice":0,"childcare_vouchers":0,"pension":0,"pension_contribution":0,"employer_pension":0,"pre_tax_deductions":0,"niable_pay":9339.87,"taxable_pay":9339.87,"tax":2889.63,"employee_ni":354.3,"employer_ni":1338.43,"student_loans":{},"post_tax_deductions":0,"take_home":6095.94},"four_weeks":{"gross":8621.42,"salary_sacrifice":0,"childcare_vouchers":0,"pension":0,"pension_contribution":0,"employer_pension":0,"pre_tax_deductions":0,"niable_pay":8621.42,"taxable_pay":8621.42,"tax":2667.35,"employee_ni":327.05,"employer_ni":1235.47,"student_loans":{},"post_tax_deductions":0,"take_home":5627.02},"two_weeks":{"gross":4310.71,"salary_sacrifice":0,"childcare_vouchers":0,"pension":0,"pension_contribution":0,"employer_pension":0,"pre_tax_deductions":0,"niable_pay":4310.71,"taxable_pay":4310.71,"tax":1333.68,"employee_ni":163.52,"employer_ni":617.74,"student_loans":{},"post_tax_deductions":0,"take_home":2813.51},"week":{"gross":2155.35,"salary_sacrifice":0,"childcare_vouchers":0,"pension":0,"pension_contribution":0,"employer_pension":0,"pre_tax_deductions":0,"niable_pay":2155.35,"taxable_pay":2155.35,"tax":666.84,"employee_ni":81.76,"employer_ni":308.87,"student_loans":{},"post_tax_deductions":0,"take_home":1406.75},"day":{"gross":431.07,"salary_sacrifice":0,"childcare_vouchers":0,"pension":0,"pension_contribution":0,"employer_pension":0,"pre_tax_deductions":0,"niable_pay":431.07,"taxable_pay":431.07,"tax":133.37,"employee_ni":16.35,"employer_ni":61.77,"student_loans":{},"post_tax_deductions":0,"take_home":281.35},"hour":{"gross":57.48,"salary_sacrifice":0,"childcare_vouchers":0,"pension":0,"pension_contribution":0,"employer_pension":0,"pre_tax_deductions":0,"niable_pay":57.48,"taxable_pay":57.48,"tax":17.78,"employee_ni":2.18,"employer_ni":8.24,"student_loans":{},"post_tax_deductions":0,"take_home":37.51}},"payslips":[{"period":1,"gross":9339.88,"salary_sacrifice":0,"childcare_vouchers":0,"pension":0,"pension_contribution":0,"employer_pension":0,"pre_tax_deductions":0,"niable_pay":9339.88,"taxable_pay":9339.88,"tax":2889.26,"employee_ni":354.3,"employer_ni":1338.43,"student_loans":{},"post_tax_deductions":0,"take_home":6096.32},{"period":2,"gross":9339.87,"salary_sacrifice":0,"childcare_vouchers":0,"pension":0,"pension_contribution":0,"employer_pension":0,"pre_tax_deductions":0,"niable_pay":9339.87,"taxable_pay":9339.87,"tax":2889.67,"employee_ni":354.3,"employer_ni":1338.43,"student_loans":{},"post_tax_deductions":0,"take_home":6095.9},{"period":3,"gross":9339.87,"salary_sacrifice":0,"childcare_vouchers":0,"pension":0,"pension_contribution":0,"employer_pension":0,"pre_tax_deductions":0,"niable_pay":9339.87,"taxable_pay":9339.87,"tax":2889.67,"employee_ni":354.3,"employer_ni":1338.43,"student_loans":{},"post_tax_deductions":0,"take_home":6095.9},{"period":4,"gross":9339.87,"salary_sacrifice":0,"childcare_vouchers":0,"pension":0,"pension_contribution":0,"employer_pension":0,"pre_tax_deductions":0,"niable_pay":9339.87,"taxable_pay":9339.87,"tax":2889.66,"employee_ni":354.3,"employer_ni":1338.43,"student_loans":{},"post_tax_deductions":0,"take_home":6095.91},{"period":5,"gross":9339.87,"salary_sacrifice":0,"childcare_vouchers":0,"pension":0,"pension_contribution":0,"employer_pension":0,"pre_tax_deductions":0,"niable_pay":9339.87,"taxable_pay":9339.87,"tax":2889.67,"employee_ni":354.3,"employer_ni":1338.43,"student_loans":{},"post_tax_deductions":0,"take_home":6095.9},{"period":6,"gross":9339.87,"salary_sacrifice":0,"childcare_vouchers":0,"pension":0,"pension_contribution":0,"employer_pension":0,"pre_tax_deductions":0,"niable_pay":9339.87,"taxable_pay":9339.87,"tax":2889.67,"employee_ni":354.3,"employer_ni":1338.43,"student_loans":{},"post_tax_deductions":0,"take_home":6095.9},{"period":7,"gross":9339.87,"salary_sacrifice":0,"childcare_vouchers":0,"pension":0,"pension_contribution":0,"employer_pension":0,"pre_tax_deductions":0,"niable_pay":9339.87,"taxable_pay":9339.87,"tax":2889.66,"employee_ni":354.3,"employer_ni":1338.43,"student_loans":{},"post_tax_deductions":0,"take_home":6095.91},{"period":8,"gross":9339.87,"salary_sacrifice":0,"childcare_vouchers":0,"pension":0,"pension_contribution":0,"employer_pension":0,"pre_tax_deductions":0,"niable_pay":9339.87,"taxable_pay":9339.87,"tax":2889.67,"employee_ni":354.3,"employer_ni":1338.43,"student_loans":{},"post_tax_deductions":0,"take_home":6095.9},{"period":9,"gross":9339.87,"salary_sacrifice":0,"childcare_vouchers":0,"pension":0,"pension_contribution":0,"employer_pension":0,"pre_tax_deductions":0,"niable_pay":9339.87,"taxable_pay":9339.87,"tax":2889.67,"employee_ni":354.3,"employer_ni":1338.43,"student_loans":{},"post_tax_deductions":0,"take_home":6095.9},{"period":10,"gross":9339.87,"salary_sacrifice":0,"childcare_vouchers":0,"pension":0,"pension_contribution":0,"employer_pension":0,"pre_tax_deductions":0,"niable_pay":9339.87,"taxable_pay":9339.87,"tax":2889.66,"employee_ni":354.3,"employer_ni":1338.43,"student_loans":{},"post_tax_deductions":0,"take_home":6095.91},{"period":11,"gross":9339.87,"salary_sacrifice":0,"childcare_vouchers":0,"pension":0,"pension_contribution":0,"employer_pension":0,"pre_tax_deductions":0,"niable_pay":9339.87,"taxable_pay":9339.87,"tax":2889.67,"employee_ni":354.3,"employer_ni":1338.43,"student_loans":{},"post_tax_deductions":0,"take_home":6095.9},{"period":12,"gross":9339.87,"salary_sacrifice":0,"childcare_vouchers":0,"pension":0,"pension_contribution":0,"employer_pension":0,"pre_tax_deductions":0,"niable_pay":9339.87,"taxable_pay":9339.87,"tax":2889.67,"employee_ni":354.3,"employer_ni":1338.43,"student_loans":{},"post_tax_deductions":0,"take_home":6095.9}],"tax_bands":[{"rate":20,"taxable":37700,"tax":7540},{"rate":40,"taxable":67839,"tax":27135.6}],"rates":{"effective":34.73,"marginal":61.99}},"assumptions":["Inside IR35 through an umbrella: the salary is the largest whose employment cost (employer NI, the Apprenticeship Levy, any employer pension) fits what the margin leaves of the income. within_budget is false when costs that do not depend on salary (a fixed employer pension, say) use up what the margin leaves on their own.","The umbrella pays the Apprenticeship Levy unless apprenticeship_levy is false, and claims no Employment Allowance. Holiday pay held back is not modelled."],"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/guidance/rates-and-thresholds-for-employers-2026-to-2027","https://www.thepensionsregulator.gov.uk/en/business-advisers/automatic-enrolment-guide-for-business-advisers/minimum-contribution-increases-planned-by-law-phasing"]}}}},"400":{"description":"INVALID_INPUT: the message names each field that is wrong.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"UNAUTHENTICATED (no key) or INVALID_KEY (an unknown or revoked key).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"QUOTA_EXCEEDED: the free plan's calculations for the month are used; upgrade_url says where to get more.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"RATE_LIMITED: over the plan's calls a second; Retry-After says when to try again.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"UNAVAILABLE: keys can’t be checked right now; retry with backoff.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/ir35-compare":{"post":{"operationId":"ir35Compare","tags":["Contractors"],"summary":"Inside against outside IR35","description":"The same contract income inside IR35 through an umbrella and outside IR35 through your own limited company, with the difference in take-home.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"tax_year":{"type":"string","default":"2026-27","description":"The tax year, such as 2026-27. The latest when not given."},"region":{"type":"string","enum":["england","scotland","wales","northern_ireland"],"description":"Where they live: england, scotland, wales or northern_ireland."},"pay_frequency":{"type":"string","enum":["monthly","four_weekly","two_weekly","weekly"],"default":"monthly","description":"How often they are paid: monthly (when not given), four_weekly, two_weekly or weekly. Each period runs through payroll."},"working_pattern":{"type":"object","properties":{"days_per_week":{"type":"number","exclusiveMinimum":0,"maximum":7,"default":5,"description":"Days worked a week: 5 when not given."},"hours_per_week":{"type":"number","exclusiveMinimum":0,"maximum":168,"default":37.5,"description":"Hours worked a week: 37.5 when not given."},"weeks_per_year":{"type":"number","minimum":1,"maximum":53,"default":52,"description":"Weeks paid a year: 52 when not given."}},"additionalProperties":false,"description":"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."},"income":{"type":"object","properties":{"amount":{"type":"number","minimum":0,"exclusiveMaximum":100000000,"description":"Pounds and pence."},"per":{"type":"string","enum":["year","month","four_weeks","two_weeks","week","day","hour"],"description":"The period the amount is for."}},"required":["amount","per"],"additionalProperties":false,"description":"Contract income: a day rate per day, or an amount a year, month or week."},"margin":{"type":"object","properties":{"amount":{"type":"number","minimum":0,"exclusiveMaximum":100000000,"description":"Pounds and pence."},"per":{"type":"string","enum":["year","month","four_weeks","two_weeks","week","day","hour"],"description":"The period the amount is for."}},"required":["amount","per"],"additionalProperties":false,"description":"The umbrella's margin, for the umbrella side."},"expenses":{"type":"object","properties":{"amount":{"type":"number","minimum":0,"exclusiveMaximum":100000000,"description":"Pounds and pence."},"per":{"type":"string","enum":["year","month","four_weeks","two_weeks","week","day","hour"],"description":"The period the amount is for."}},"required":["amount","per"],"additionalProperties":false,"description":"Business costs a limited company pays from the income (accountant, insurance, equipment)."},"student_loans":{"type":"array","items":{"type":"string","enum":["plan_1","plan_2","plan_4","plan_5","postgraduate"]},"default":[],"description":"Each loan they repay: plan_1, plan_2, plan_4, plan_5, postgraduate."},"apprenticeship_levy":{"type":"boolean","default":true,"description":"Counts the Apprenticeship Levy in the umbrella's costs (0.5% of pay, for an umbrella whose pay bill is over £3 million). True when not given."}},"required":["region","income","margin"],"additionalProperties":false},"example":{"region":"england","income":{"amount":500,"per":"day"},"margin":{"amount":25,"per":"week"},"expenses":{"amount":3000,"per":"year"}}}}},"responses":{"200":{"description":"The result, with what produced it, the assumptions and the sources.","content":{"application/json":{"schema":{"type":"object","properties":{"tax_year":{"type":"string"},"engine":{"type":"string"},"hmrc_test_data":{"type":"string"},"income":{"type":"number"},"inside_ir35":{"type":"object","properties":{"route":{"type":"string"},"salary":{"type":"number"},"within_budget":{"type":"boolean"},"take_home":{"type":"number"}}},"outside_ir35":{"type":"object","properties":{"route":{"type":"string"},"salary":{"type":"number"},"dividends":{"type":"number"},"corporation_tax":{"type":"number"},"take_home":{"type":"number"}}},"difference":{"type":"number"},"assumptions":{"type":"array","items":{"type":"string"}},"sources":{"type":"array","items":{"type":"string"}}},"required":["tax_year","engine","hmrc_test_data","assumptions","sources"]},"example":{"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","income":130000,"inside_ir35":{"route":"umbrella","salary":112078.45,"within_budget":true,"take_home":73151.25},"outside_ir35":{"route":"limited_company","salary":12570,"dividends":87021.59,"corporation_tax":26272.91,"take_home":77960.34},"difference":4809.09,"assumptions":["Inside IR35 is through an umbrella company; outside IR35 is through your own limited company with no other employees (so no Employment Allowance), a salary from the usual choices and the rest of the profit as dividends.","Only what applies to both routes is asked for, so the difference is for the same income. Inside IR35 through your own company (the deemed payment) is not modelled.","Corporation tax is for a 12-month accounting period with no associated companies, with marginal relief between the limits.","Employment Allowance (employment_allowance) is not available to a company whose only employee paid above the secondary threshold is a director: the caller checks it applies.","The director's NI is on the annual earnings period, category A. Income tax is on the year's salary and dividends together, as Self Assessment settles it."],"sources":["https://www.gov.uk/corporation-tax-rates","https://www.gov.uk/guidance/corporation-tax-marginal-relief","https://www.gov.uk/tax-on-dividends","https://www.gov.uk/government/publications/payroll-technical-specifications-national-insurance","https://www.gov.uk/guidance/rates-and-thresholds-for-employers-2026-to-2027","https://www.thepensionsregulator.gov.uk/en/business-advisers/automatic-enrolment-guide-for-business-advisers/minimum-contribution-increases-planned-by-law-phasing","https://www.gov.uk/government/publications/payroll-technical-specifications-income-tax"]}}}},"400":{"description":"INVALID_INPUT: the message names each field that is wrong.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"UNAUTHENTICATED (no key) or INVALID_KEY (an unknown or revoked key).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"QUOTA_EXCEEDED: the free plan's calculations for the month are used; upgrade_url says where to get more.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"RATE_LIMITED: over the plan's calls a second; Retry-After says when to try again.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"UNAVAILABLE: keys can’t be checked right now; retry with backoff.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/tax-years":{"get":{"operationId":"taxYears","tags":["Reference data"],"summary":"Tax years","description":"The tax years supported, with the HMRC test data each one passes. No key needed.","security":[],"responses":{"200":{"description":"The result, with what produced it, the assumptions and the sources.","content":{"application/json":{"schema":{"type":"object","properties":{"tax_year":{"type":"string"},"engine":{"type":"string"},"hmrc_test_data":{"type":"string"},"tax_years":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"latest":{"type":"boolean"},"tax_year":{"type":"string"},"engine":{"type":"string"},"hmrc_test_data":{"type":"string"}}}},"assumptions":{"type":"array","items":{"type":"string"}},"sources":{"type":"array","items":{"type":"string"}}},"required":["tax_year","engine","hmrc_test_data","assumptions","sources"]},"example":{"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_years":[{"id":"2026-27","latest":true,"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"}],"assumptions":["A tax year runs from 6 April to 5 April."],"sources":["https://www.gov.uk/government/publications/software-developers-payroll-test-data-2026-to-2027"]}}}},"400":{"description":"INVALID_INPUT: the message names each field that is wrong.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/rates":{"get":{"operationId":"rates","tags":["Reference data"],"summary":"Rates and thresholds","description":"Every rate and threshold for a tax year: income tax bands by region, NI thresholds and rates by category letter, student loans, allowances, employer costs, statutory pay, dividends, the self-employed, corporation tax, the minimum wage and redundancy pay, with gov.uk sources. No key needed.","security":[],"parameters":[{"name":"tax_year","in":"query","required":false,"description":"The tax year, such as 2026-27. The latest when not given.","schema":{"type":"string"}}],"responses":{"200":{"description":"The result, with what produced it, the assumptions and the sources.","content":{"application/json":{"schema":{"type":"object","properties":{"tax_year":{"type":"string"},"engine":{"type":"string"},"hmrc_test_data":{"type":"string"},"income_tax":{"type":"object","properties":{"personal_allowance":{"type":"number"},"personal_allowance_taper_threshold":{"type":"number"},"blind_persons_allowance":{"type":"number"},"marriage_allowance":{"type":"number"},"bands":{"type":"object","properties":{"rest_of_uk":{"type":"array","items":{"type":"object","properties":{"rate":{"type":"number"},"from":{"type":"number"},"to":{"type":["number","null"]}}}},"scotland":{"type":"array","items":{"type":"object","properties":{"rate":{"type":"number"},"from":{"type":"number"},"to":{"type":["number","null"]}}}},"wales":{"type":"array","items":{"type":"object","properties":{"rate":{"type":"number"},"from":{"type":"number"},"to":{"type":["number","null"]}}}}}},"regulatory_limit":{"type":"number"}}},"national_insurance":{"type":"object","properties":{"thresholds":{"type":"object","properties":{"lower_earnings_limit":{"type":"number"},"primary_threshold":{"type":"number"},"secondary_threshold":{"type":"number"},"freeport_upper_secondary_threshold":{"type":"number"},"upper_earnings_limit":{"type":"number"}}},"employee":{"type":"object","properties":{"A":{"type":"object","properties":{"lower_earnings_limit_to_primary_threshold":{"type":"number"},"primary_threshold_to_upper_earnings_limit":{"type":"number"},"above_upper_earnings_limit":{"type":"number"}}},"M":{"type":"object","properties":{"lower_earnings_limit_to_primary_threshold":{"type":"number"},"primary_threshold_to_upper_earnings_limit":{"type":"number"},"above_upper_earnings_limit":{"type":"number"}}},"H":{"type":"object","properties":{"lower_earnings_limit_to_primary_threshold":{"type":"number"},"primary_threshold_to_upper_earnings_limit":{"type":"number"},"above_upper_earnings_limit":{"type":"number"}}},"F":{"type":"object","properties":{"lower_earnings_limit_to_primary_threshold":{"type":"number"},"primary_threshold_to_upper_earnings_limit":{"type":"number"},"above_upper_earnings_limit":{"type":"number"}}},"V":{"type":"object","properties":{"lower_earnings_limit_to_primary_threshold":{"type":"number"},"primary_threshold_to_upper_earnings_limit":{"type":"number"},"above_upper_earnings_limit":{"type":"number"}}},"N":{"type":"object","properties":{"lower_earnings_limit_to_primary_threshold":{"type":"number"},"primary_threshold_to_upper_earnings_limit":{"type":"number"},"above_upper_earnings_limit":{"type":"number"}}},"B":{"type":"object","properties":{"lower_earnings_limit_to_primary_threshold":{"type":"number"},"primary_threshold_to_upper_earnings_limit":{"type":"number"},"above_upper_earnings_limit":{"type":"number"}}},"I":{"type":"object","properties":{"lower_earnings_limit_to_primary_threshold":{"type":"number"},"primary_threshold_to_upper_earnings_limit":{"type":"number"},"above_upper_earnings_limit":{"type":"number"}}},"E":{"type":"object","properties":{"lower_earnings_limit_to_primary_threshold":{"type":"number"},"primary_threshold_to_upper_earnings_limit":{"type":"number"},"above_upper_earnings_limit":{"type":"number"}}},"C":{"type":"object","properties":{"lower_earnings_limit_to_primary_threshold":{"type":"number"},"primary_threshold_to_upper_earnings_limit":{"type":"number"},"above_upper_earnings_limit":{"type":"number"}}},"S":{"type":"object","properties":{"lower_earnings_limit_to_primary_threshold":{"type":"number"},"primary_threshold_to_upper_earnings_limit":{"type":"number"},"above_upper_earnings_limit":{"type":"number"}}},"K":{"type":"object","properties":{"lower_earnings_limit_to_primary_threshold":{"type":"number"},"primary_threshold_to_upper_earnings_limit":{"type":"number"},"above_upper_earnings_limit":{"type":"number"}}},"J":{"type":"object","properties":{"lower_earnings_limit_to_primary_threshold":{"type":"number"},"primary_threshold_to_upper_earnings_limit":{"type":"number"},"above_upper_earnings_limit":{"type":"number"}}},"L":{"type":"object","properties":{"lower_earnings_limit_to_primary_threshold":{"type":"number"},"primary_threshold_to_upper_earnings_limit":{"type":"number"},"above_upper_earnings_limit":{"type":"number"}}},"Z":{"type":"object","properties":{"lower_earnings_limit_to_primary_threshold":{"type":"number"},"primary_threshold_to_upper_earnings_limit":{"type":"number"},"above_upper_earnings_limit":{"type":"number"}}},"D":{"type":"object","properties":{"lower_earnings_limit_to_primary_threshold":{"type":"number"},"primary_threshold_to_upper_earnings_limit":{"type":"number"},"above_upper_earnings_limit":{"type":"number"}}}}},"employer":{"type":"object","properties":{"A":{"type":"object","properties":{"secondary_threshold_to_upper_earnings_limit":{"type":"number"},"above_upper_earnings_limit":{"type":"number"}}},"B":{"type":"object","properties":{"secondary_threshold_to_upper_earnings_limit":{"type":"number"},"above_upper_earnings_limit":{"type":"number"}}},"C":{"type":"object","properties":{"secondary_threshold_to_upper_earnings_limit":{"type":"number"},"above_upper_earnings_limit":{"type":"number"}}},"J":{"type":"object","properties":{"secondary_threshold_to_upper_earnings_limit":{"type":"number"},"above_upper_earnings_limit":{"type":"number"}}},"H":{"type":"object","properties":{"secondary_threshold_to_upper_earnings_limit":{"type":"number"},"above_upper_earnings_limit":{"type":"number"}}},"M":{"type":"object","properties":{"secondary_threshold_to_upper_earnings_limit":{"type":"number"},"above_upper_earnings_limit":{"type":"number"}}},"V":{"type":"object","properties":{"secondary_threshold_to_upper_earnings_limit":{"type":"number"},"above_upper_earnings_limit":{"type":"number"}}},"Z":{"type":"object","properties":{"secondary_threshold_to_upper_earnings_limit":{"type":"number"},"above_upper_earnings_limit":{"type":"number"}}},"F":{"type":"object","properties":{"secondary_threshold_to_freeport_upper_secondary_threshold":{"type":"number"},"freeport_upper_secondary_threshold_to_upper_earnings_limit":{"type":"number"},"above_upper_earnings_limit":{"type":"number"}}},"I":{"type":"object","properties":{"secondary_threshold_to_freeport_upper_secondary_threshold":{"type":"number"},"freeport_upper_secondary_threshold_to_upper_earnings_limit":{"type":"number"},"above_upper_earnings_limit":{"type":"number"}}},"S":{"type":"object","properties":{"secondary_threshold_to_freeport_upper_secondary_threshold":{"type":"number"},"freeport_upper_secondary_threshold_to_upper_earnings_limit":{"type":"number"},"above_upper_earnings_limit":{"type":"number"}}},"L":{"type":"object","properties":{"secondary_threshold_to_freeport_upper_secondary_threshold":{"type":"number"},"freeport_upper_secondary_threshold_to_upper_earnings_limit":{"type":"number"},"above_upper_earnings_limit":{"type":"number"}}},"D":{"type":"object","properties":{"secondary_threshold_to_freeport_upper_secondary_threshold":{"type":"number"},"freeport_upper_secondary_threshold_to_upper_earnings_limit":{"type":"number"},"above_upper_earnings_limit":{"type":"number"}}},"E":{"type":"object","properties":{"secondary_threshold_to_freeport_upper_secondary_threshold":{"type":"number"},"freeport_upper_secondary_threshold_to_upper_earnings_limit":{"type":"number"},"above_upper_earnings_limit":{"type":"number"}}},"K":{"type":"object","properties":{"secondary_threshold_to_freeport_upper_secondary_threshold":{"type":"number"},"freeport_upper_secondary_threshold_to_upper_earnings_limit":{"type":"number"},"above_upper_earnings_limit":{"type":"number"}}},"N":{"type":"object","properties":{"secondary_threshold_to_freeport_upper_secondary_threshold":{"type":"number"},"freeport_upper_secondary_threshold_to_upper_earnings_limit":{"type":"number"},"above_upper_earnings_limit":{"type":"number"}}}}}}},"student_loans":{"type":"object","properties":{"plan_1":{"type":"object","properties":{"threshold":{"type":"number"},"rate":{"type":"number"}}},"plan_2":{"type":"object","properties":{"threshold":{"type":"number"},"rate":{"type":"number"}}},"plan_4":{"type":"object","properties":{"threshold":{"type":"number"},"rate":{"type":"number"}}},"plan_5":{"type":"object","properties":{"threshold":{"type":"number"},"rate":{"type":"number"}}},"postgraduate":{"type":"object","properties":{"threshold":{"type":"number"},"rate":{"type":"number"}}}}},"married_couples_allowance":{"type":"object","properties":{"maximum":{"type":"number"},"minimum":{"type":"number"},"income_limit":{"type":"number"},"rate":{"type":"number"}}},"child_benefit":{"type":"object","properties":{"eldest_child_weekly":{"type":"number"},"other_child_weekly":{"type":"number"},"weeks_in_year":{"type":"number"},"high_income_charge_threshold":{"type":"number"},"high_income_charge_step":{"type":"number"}}},"childcare_vouchers":{"type":"object","properties":{"weekly":{"type":"object","properties":{"basic":{"type":"number"},"higher":{"type":"number"},"additional":{"type":"number"}}},"monthly":{"type":"object","properties":{"basic":{"type":"number"},"higher":{"type":"number"},"additional":{"type":"number"}}}}},"employer":{"type":"object","properties":{"class_1a_ni":{"type":"number"},"employment_allowance":{"type":"number"},"apprenticeship_levy":{"type":"number"},"auto_enrolment_minimum":{"type":"number"},"qualifying_earnings":{"type":"object","properties":{"weekly":{"type":"object","properties":{"lower":{"type":"number"},"upper":{"type":"number"}}},"two_weekly":{"type":"object","properties":{"lower":{"type":"number"},"upper":{"type":"number"}}},"four_weekly":{"type":"object","properties":{"lower":{"type":"number"},"upper":{"type":"number"}}},"monthly":{"type":"object","properties":{"lower":{"type":"number"},"upper":{"type":"number"}}}}}}},"statutory_pay":{"type":"object","properties":{"sick_pay_weekly":{"type":"number"},"sick_pay_earnings_percent":{"type":"number"},"sick_pay_max_weeks":{"type":"number"},"family_pay_weekly":{"type":"number"},"family_pay_earnings_percent":{"type":"number"}}},"dividends":{"type":"object","properties":{"allowance":{"type":"number"},"basic":{"type":"number"},"higher":{"type":"number"},"additional":{"type":"number"}}},"self_employed":{"type":"object","properties":{"lower_profits_limit":{"type":"number"},"upper_profits_limit":{"type":"number"},"class_4_main":{"type":"number"},"class_4_additional":{"type":"number"},"small_profits_threshold":{"type":"number"},"class_2_weekly":{"type":"number"}}},"corporation_tax":{"type":"object","properties":{"small_profits_rate":{"type":"number"},"main_rate":{"type":"number"},"lower_limit":{"type":"number"},"upper_limit":{"type":"number"},"marginal_relief_fraction":{"type":"string"}}},"minimum_wage":{"type":"object","properties":{"aged_21_and_over":{"type":"number"},"aged_18_to_20":{"type":"number"},"under_18":{"type":"number"},"apprentice":{"type":"number"}}},"redundancy":{"type":"object","properties":{"weekly_pay_cap":{"type":"number"}}},"assumptions":{"type":"array","items":{"type":"string"}},"sources":{"type":"array","items":{"type":"string"}}},"required":["tax_year","engine","hmrc_test_data","assumptions","sources"]},"example":{"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","income_tax":{"personal_allowance":12570,"personal_allowance_taper_threshold":100000,"blind_persons_allowance":3250,"marriage_allowance":1260,"bands":{"rest_of_uk":[{"rate":20,"from":0,"to":37700},{"rate":40,"from":37700,"to":125140},{"rate":45,"from":125140,"to":null}],"scotland":[{"rate":19,"from":0,"to":3967},{"rate":20,"from":3967,"to":16956},{"rate":21,"from":16956,"to":31092},{"rate":42,"from":31092,"to":62430},{"rate":45,"from":62430,"to":125140},{"rate":48,"from":125140,"to":null}],"wales":[{"rate":20,"from":0,"to":37700},{"rate":40,"from":37700,"to":125140},{"rate":45,"from":125140,"to":null}]},"regulatory_limit":50},"national_insurance":{"thresholds":{"lower_earnings_limit":6708,"primary_threshold":12570,"secondary_threshold":5000,"freeport_upper_secondary_threshold":25000,"upper_earnings_limit":50270},"employee":{"A":{"lower_earnings_limit_to_primary_threshold":0,"primary_threshold_to_upper_earnings_limit":8,"above_upper_earnings_limit":2},"M":{"lower_earnings_limit_to_primary_threshold":0,"primary_threshold_to_upper_earnings_limit":8,"above_upper_earnings_limit":2},"H":{"lower_earnings_limit_to_primary_threshold":0,"primary_threshold_to_upper_earnings_limit":8,"above_upper_earnings_limit":2},"F":{"lower_earnings_limit_to_primary_threshold":0,"primary_threshold_to_upper_earnings_limit":8,"above_upper_earnings_limit":2},"V":{"lower_earnings_limit_to_primary_threshold":0,"primary_threshold_to_upper_earnings_limit":8,"above_upper_earnings_limit":2},"N":{"lower_earnings_limit_to_primary_threshold":0,"primary_threshold_to_upper_earnings_limit":8,"above_upper_earnings_limit":2},"B":{"lower_earnings_limit_to_primary_threshold":0,"primary_threshold_to_upper_earnings_limit":1.85,"above_upper_earnings_limit":2},"I":{"lower_earnings_limit_to_primary_threshold":0,"primary_threshold_to_upper_earnings_limit":1.85,"above_upper_earnings_limit":2},"E":{"lower_earnings_limit_to_primary_threshold":0,"primary_threshold_to_upper_earnings_limit":1.85,"above_upper_earnings_limit":2},"C":{"lower_earnings_limit_to_primary_threshold":0,"primary_threshold_to_upper_earnings_limit":0,"above_upper_earnings_limit":0},"S":{"lower_earnings_limit_to_primary_threshold":0,"primary_threshold_to_upper_earnings_limit":0,"above_upper_earnings_limit":0},"K":{"lower_earnings_limit_to_primary_threshold":0,"primary_threshold_to_upper_earnings_limit":0,"above_upper_earnings_limit":0},"J":{"lower_earnings_limit_to_primary_threshold":0,"primary_threshold_to_upper_earnings_limit":2,"above_upper_earnings_limit":2},"L":{"lower_earnings_limit_to_primary_threshold":0,"primary_threshold_to_upper_earnings_limit":2,"above_upper_earnings_limit":2},"Z":{"lower_earnings_limit_to_primary_threshold":0,"primary_threshold_to_upper_earnings_limit":2,"above_upper_earnings_limit":2},"D":{"lower_earnings_limit_to_primary_threshold":0,"primary_threshold_to_upper_earnings_limit":2,"above_upper_earnings_limit":2}},"employer":{"A":{"secondary_threshold_to_upper_earnings_limit":15,"above_upper_earnings_limit":15},"B":{"secondary_threshold_to_upper_earnings_limit":15,"above_upper_earnings_limit":15},"C":{"secondary_threshold_to_upper_earnings_limit":15,"above_upper_earnings_limit":15},"J":{"secondary_threshold_to_upper_earnings_limit":15,"above_upper_earnings_limit":15},"H":{"secondary_threshold_to_upper_earnings_limit":0,"above_upper_earnings_limit":15},"M":{"secondary_threshold_to_upper_earnings_limit":0,"above_upper_earnings_limit":15},"V":{"secondary_threshold_to_upper_earnings_limit":0,"above_upper_earnings_limit":15},"Z":{"secondary_threshold_to_upper_earnings_limit":0,"above_upper_earnings_limit":15},"F":{"secondary_threshold_to_freeport_upper_secondary_threshold":0,"freeport_upper_secondary_threshold_to_upper_earnings_limit":15,"above_upper_earnings_limit":15},"I":{"secondary_threshold_to_freeport_upper_secondary_threshold":0,"freeport_upper_secondary_threshold_to_upper_earnings_limit":15,"above_upper_earnings_limit":15},"S":{"secondary_threshold_to_freeport_upper_secondary_threshold":0,"freeport_upper_secondary_threshold_to_upper_earnings_limit":15,"above_upper_earnings_limit":15},"L":{"secondary_threshold_to_freeport_upper_secondary_threshold":0,"freeport_upper_secondary_threshold_to_upper_earnings_limit":15,"above_upper_earnings_limit":15},"D":{"secondary_threshold_to_freeport_upper_secondary_threshold":0,"freeport_upper_secondary_threshold_to_upper_earnings_limit":15,"above_upper_earnings_limit":15},"E":{"secondary_threshold_to_freeport_upper_secondary_threshold":0,"freeport_upper_secondary_threshold_to_upper_earnings_limit":15,"above_upper_earnings_limit":15},"K":{"secondary_threshold_to_freeport_upper_secondary_threshold":0,"freeport_upper_secondary_threshold_to_upper_earnings_limit":15,"above_upper_earnings_limit":15},"N":{"secondary_threshold_to_freeport_upper_secondary_threshold":0,"freeport_upper_secondary_threshold_to_upper_earnings_limit":15,"above_upper_earnings_limit":15}}},"student_loans":{"plan_1":{"threshold":26900,"rate":9},"plan_2":{"threshold":29385,"rate":9},"plan_4":{"threshold":33795,"rate":9},"plan_5":{"threshold":25000,"rate":9},"postgraduate":{"threshold":21000,"rate":6}},"married_couples_allowance":{"maximum":11700,"minimum":4530,"income_limit":39200,"rate":10},"child_benefit":{"eldest_child_weekly":27.05,"other_child_weekly":17.9,"weeks_in_year":53,"high_income_charge_threshold":60000,"high_income_charge_step":200},"childcare_vouchers":{"weekly":{"basic":55,"higher":28,"additional":25},"monthly":{"basic":243,"higher":124,"additional":110}},"employer":{"class_1a_ni":15,"employment_allowance":10500,"apprenticeship_levy":0.5,"auto_enrolment_minimum":3,"qualifying_earnings":{"weekly":{"lower":120,"upper":967},"two_weekly":{"lower":240,"upper":1934},"four_weekly":{"lower":480,"upper":3867},"monthly":{"lower":520,"upper":4189}}},"statutory_pay":{"sick_pay_weekly":123.25,"sick_pay_earnings_percent":80,"sick_pay_max_weeks":28,"family_pay_weekly":194.32,"family_pay_earnings_percent":90},"dividends":{"allowance":500,"basic":10.75,"higher":35.75,"additional":39.35},"self_employed":{"lower_profits_limit":12570,"upper_profits_limit":50270,"class_4_main":6,"class_4_additional":2,"small_profits_threshold":7105,"class_2_weekly":3.65},"corporation_tax":{"small_profits_rate":19,"main_rate":25,"lower_limit":50000,"upper_limit":250000,"marginal_relief_fraction":"3/200"},"minimum_wage":{"aged_21_and_over":12.71,"aged_18_to_20":10.85,"under_18":8,"apprentice":8},"redundancy":{"weekly_pay_cap":751},"assumptions":["Amounts are pounds a year unless the name says weekly or monthly; rates are percentages.","Income tax bands are taxable income above the allowances. National Insurance thresholds are annual; payroll works them out for each pay period."],"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.thepensionsregulator.gov.uk/en/employers/new-employers/im-an-employer-who-has-to-provide-a-pension/declare-your-compliance/ongoing-duties-for-employers/earnings-thresholds","https://www.litrg.org.uk/tax-and-nic/income-tax/tax-allowances/married-couples-allowance","https://www.gov.uk/government/publications/rates-and-allowances-tax-credits-child-benefit-and-guardians-allowance/tax-credits-child-benefit-and-guardians-allowance","https://www.gov.uk/child-benefit-tax-charge","https://www.gov.uk/hmrc-internal-manuals/employment-income-manual/eim22012","https://www.gov.uk/hmrc-internal-manuals/employment-income-manual/eim16056","https://www.gov.uk/expenses-and-benefits-childcare/whats-exempt","https://www.gov.uk/national-minimum-wage-rates","https://www.gov.uk/redundant-your-rights/redundancy-pay","https://www.gov.uk/tax-on-dividends","https://www.gov.uk/self-employed-national-insurance-rates","https://www.gov.uk/corporation-tax-rates","https://www.gov.uk/guidance/corporation-tax-marginal-relief","https://www.gov.uk/guidance/rates-and-thresholds-for-employers-2026-to-2027","https://www.gov.uk/guidance/statutory-sick-pay-manually-calculate-your-employees-payments","https://www.thepensionsregulator.gov.uk/en/business-advisers/automatic-enrolment-guide-for-business-advisers/minimum-contribution-increases-planned-by-law-phasing","https://www.gov.uk/government/publications/software-developers-payroll-test-data-2026-to-2027"]}}}},"400":{"description":"INVALID_INPUT: the message names each field that is wrong.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/tax-codes/{code}":{"get":{"operationId":"decodeTaxCode","tags":["Reference data"],"summary":"Decode a tax code","description":"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.","security":[],"parameters":[{"name":"code","in":"path","required":true,"description":"The tax code, such as 1257L, S1257L, K475 M1, BR or NT.","schema":{"type":"string"},"example":"1257L"},{"name":"tax_year","in":"query","required":false,"description":"The tax year, such as 2026-27. The latest when not given.","schema":{"type":"string"}}],"responses":{"200":{"description":"The result, with what produced it, the assumptions and the sources.","content":{"application/json":{"schema":{"type":"object","properties":{"tax_year":{"type":"string"},"engine":{"type":"string"},"hmrc_test_data":{"type":"string"},"code":{"type":"string"},"kind":{"type":"string"},"region":{"type":["string","null"]},"basis":{"type":"string"},"allowance":{"type":"number"},"description":{"type":"string"},"assumptions":{"type":"array","items":{"type":"string"}},"sources":{"type":"array","items":{"type":"string"}},"flat_rate":{"type":"number"},"addition":{"type":"number"}},"required":["tax_year","engine","hmrc_test_data","assumptions","sources"]},"example":{"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"]}}}},"400":{"description":"INVALID_INPUT: the message names each field that is wrong.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}},"components":{"securitySchemes":{"bearer":{"type":"http","scheme":"bearer"}},"schemas":{"Error":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["INVALID_INPUT","UNAUTHENTICATED","INVALID_KEY","NOT_FOUND","QUOTA_EXCEEDED","RATE_LIMITED","UNAVAILABLE","INTERNAL"]},"message":{"type":"string"},"upgrade_url":{"type":"string","description":"With QUOTA_EXCEEDED: where to choose a plan with more."},"claim_url":{"type":"string","description":"With QUOTA_EXCEEDED on an agent's account: the link for its person to claim it, then choose a plan."}}}}}}}}