{"openapi":"3.1.0","info":{"title":"TakeHome API","version":"1.0.0","summary":"UK take-home pay calculations with GOV.UK sources and workings on every result.","description":"Calculates UK income tax (rUK and Scotland), employee NI, student loans, pensions and the High Income Child Benefit Charge for tax years 2025-26 and 2026-27. Estimates based on published HMRC and Scottish Government rates. Not tax advice.","contact":{"url":"https://takehomeapi.com"}},"servers":[{"url":"https://api.takehomeapi.com"}],"components":{"securitySchemes":{"apiKey":{"type":"apiKey","in":"header","name":"X-API-Key","description":"Free key: 100 calls/month. Also accepted as Authorization: Bearer <key>."},"x402":{"type":"apiKey","in":"header","name":"PAYMENT-SIGNATURE","description":"Pay per call with x402 (USDC on Base), no account needed. Call without credentials to receive HTTP 402 with the payment terms. Price per call is in x-price-usd."}}},"paths":{"/v1/rates":{"get":{"operationId":"getRates","summary":"Rates and thresholds for a tax year (free)","x-price-usd":0,"parameters":[{"name":"taxYear","in":"query","schema":{"type":"string","enum":["2025-26","2026-27"],"default":"2026-27"}}],"responses":{"200":{"description":"Rates","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object"},"meta":{"type":"object","properties":{"apiVersion":{"type":"string"},"disclaimer":{"type":"string"}}}}}}}},"400":{"description":"Invalid input","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}}}}}}}}}}},"/v1/take-home":{"post":{"operationId":"calculateTakeHome","summary":"Take-home pay for one employee scenario","x-price-usd":0.01,"security":[{"apiKey":[]},{"x402":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["grossSalary"],"properties":{"grossSalary":{"type":"number","minimum":0,"maximum":100000000,"description":"Annual gross salary in GBP before any deductions.","examples":[45000]},"taxYear":{"type":"string","enum":["2025-26","2026-27"],"default":"2026-27"},"region":{"type":"string","enum":["rUK","scotland","england","wales","northern-ireland","ni"],"default":"rUK","description":"Where the employee is a taxpayer. England, Wales and Northern Ireland share rUK bands."},"studentLoans":{"type":"array","maxItems":2,"items":{"type":"string","enum":["plan1","plan2","plan4","plan5","postgrad"]},"description":"At most one undergraduate plan, optionally plus postgrad. plan5 applies from 2026-27."},"pension":{"type":"object","additionalProperties":false,"required":["percent","method"],"properties":{"percent":{"type":"number","minimum":0,"maximum":100,"description":"Gross contribution as a % of salary."},"method":{"type":"string","enum":["salary_sacrifice","net_pay","relief_at_source"]}}},"childBenefitAnnual":{"type":"number","minimum":0,"description":"Child Benefit received in the year, for the High Income Child Benefit Charge."}}},"example":{"grossSalary":45000,"region":"rUK","studentLoans":["plan2"],"pension":{"percent":5,"method":"salary_sacrifice"}}}}},"responses":{"200":{"description":"Breakdown","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"input":{"type":"object"},"personalAllowance":{"type":"number"},"adjustedNetIncome":{"type":"number"},"taxableIncome":{"type":"number"},"incomeTax":{"type":"object","properties":{"total":{"type":"number"},"bands":{"type":"array","items":{"type":"object","properties":{"band":{"type":"string"},"rate":{"type":"number"},"taxedAmount":{"type":"number"},"tax":{"type":"number"}}}}}},"nationalInsurance":{"type":"number"},"studentLoan":{"type":"object"},"pension":{"type":"object"},"childBenefitCharge":{"type":"number"},"netPay":{"type":"object","properties":{"annual":{"type":"number"},"monthly":{"type":"number"},"weekly":{"type":"number"}},"description":"Paid through payroll."},"netAfterAllCharges":{"type":"object","properties":{"annual":{"type":"number"},"monthly":{"type":"number"},"weekly":{"type":"number"}},"description":"Net pay minus the High Income Child Benefit Charge."},"effectiveRate":{"type":"number","description":"Share of gross lost to tax, NI, student loan and HICBC."},"marginalRate":{"type":"number","description":"Share of the next £100 of salary lost to deductions."},"assumptions":{"type":"array","items":{"type":"string"}},"sources":{"type":"array","items":{"type":"string","format":"uri"}}}},"meta":{"type":"object","properties":{"apiVersion":{"type":"string"},"disclaimer":{"type":"string"}}}}}}}},"400":{"description":"Invalid input","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}}}}}}}},"401":{"description":"Missing or invalid API key"},"402":{"description":"Payment required (x402): pay in USDC and retry"},"429":{"description":"Monthly plan limit reached"}}}},"/v1/compare":{"post":{"operationId":"compareScenarios","summary":"Compare 2 to 5 scenarios side by side","x-price-usd":0.03,"security":[{"apiKey":[]},{"x402":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["scenarios"],"properties":{"scenarios":{"type":"array","minItems":2,"maxItems":5,"items":{"type":"object","additionalProperties":false,"required":["grossSalary"],"properties":{"grossSalary":{"type":"number","minimum":0,"maximum":100000000,"description":"Annual gross salary in GBP before any deductions.","examples":[45000]},"taxYear":{"type":"string","enum":["2025-26","2026-27"],"default":"2026-27"},"region":{"type":"string","enum":["rUK","scotland","england","wales","northern-ireland","ni"],"default":"rUK","description":"Where the employee is a taxpayer. England, Wales and Northern Ireland share rUK bands."},"studentLoans":{"type":"array","maxItems":2,"items":{"type":"string","enum":["plan1","plan2","plan4","plan5","postgrad"]},"description":"At most one undergraduate plan, optionally plus postgrad. plan5 applies from 2026-27."},"pension":{"type":"object","additionalProperties":false,"required":["percent","method"],"properties":{"percent":{"type":"number","minimum":0,"maximum":100,"description":"Gross contribution as a % of salary."},"method":{"type":"string","enum":["salary_sacrifice","net_pay","relief_at_source"]}}},"childBenefitAnnual":{"type":"number","minimum":0,"description":"Child Benefit received in the year, for the High Income Child Benefit Charge."}}}}}},"example":{"scenarios":[{"grossSalary":40000},{"grossSalary":45000}]}}}},"responses":{"200":{"description":"Each scenario plus its difference from the first","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"scenarios":{"type":"array","items":{"type":"object","properties":{"input":{"type":"object"},"personalAllowance":{"type":"number"},"adjustedNetIncome":{"type":"number"},"taxableIncome":{"type":"number"},"incomeTax":{"type":"object","properties":{"total":{"type":"number"},"bands":{"type":"array","items":{"type":"object","properties":{"band":{"type":"string"},"rate":{"type":"number"},"taxedAmount":{"type":"number"},"tax":{"type":"number"}}}}}},"nationalInsurance":{"type":"number"},"studentLoan":{"type":"object"},"pension":{"type":"object"},"childBenefitCharge":{"type":"number"},"netPay":{"type":"object","properties":{"annual":{"type":"number"},"monthly":{"type":"number"},"weekly":{"type":"number"}},"description":"Paid through payroll."},"netAfterAllCharges":{"type":"object","properties":{"annual":{"type":"number"},"monthly":{"type":"number"},"weekly":{"type":"number"}},"description":"Net pay minus the High Income Child Benefit Charge."},"effectiveRate":{"type":"number","description":"Share of gross lost to tax, NI, student loan and HICBC."},"marginalRate":{"type":"number","description":"Share of the next £100 of salary lost to deductions."},"assumptions":{"type":"array","items":{"type":"string"}},"sources":{"type":"array","items":{"type":"string","format":"uri"}}}}},"differences":{"type":"array","items":{"type":"object"}}}},"meta":{"type":"object","properties":{"apiVersion":{"type":"string"},"disclaimer":{"type":"string"}}}}}}}},"400":{"description":"Invalid input","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}}}}}}}},"401":{"description":"Missing or invalid API key"},"402":{"description":"Payment required (x402): pay in USDC and retry"},"429":{"description":"Monthly plan limit reached"}}}}}}