Last updated 9 October 2026View as Markdown

Umbrella company pay

POST /v1/umbrella-pay Needs a key

Inside IR35 through an umbrella: the salary its margin and employment costs leave from a day rate, and the take-home on it.

Request

A JSON body. Fields not listed here are rejected.

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

Example

curl https://api.checktakehomepay.co.uk/v1/umbrella-pay \
  -H "Authorization: Bearer $CHECKTAKEHOMEPAY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "region": "england",
  "income": {
    "amount": 500,
    "per": "day"
  },
  "margin": {
    "amount": 25,
    "per": "week"
  }
}'

const response = await fetch('https://api.checktakehomepay.co.uk/v1/umbrella-pay', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.CHECKTAKEHOMEPAY_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "region": "england",
    "income": {
      "amount": 500,
      "per": "day"
    },
    "margin": {
      "amount": 25,
      "per": "week"
    }
  }),
});
const result = await response.json();

import os
import requests

response = requests.post(
    "https://api.checktakehomepay.co.uk/v1/umbrella-pay",
    headers={"Authorization": f"Bearer {os.environ['CHECKTAKEHOMEPAY_API_KEY']}"},
    json={
        "region": "england",
        "income": {"amount": 500, "per": "day"},
        "margin": {"amount": 25, "per": "week"},
    },
)
result = response.json()

Response

200, with the result and what produced it: tax_year, engine, hmrc_test_data, assumptions and sources. This is the example's real response. Every field's type is in the OpenAPI document.

200 OK

{
  "tax_year": "2026-27",
  "engine": "2026-27.1",
  "hmrc_test_data": "rest of UK and Welsh tax v1.0, Scottish tax v1.1, NI v1.0, directors NI v1.0, student loans v1.0",
  "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"
  ]
}

Errors

400 INVALID_INPUT: the message names each field that is wrong.
401 UNAUTHENTICATED (no key) or INVALID_KEY (a key we don’t know, or a revoked one).

Every code, and how to handle them: Errors.