> Umbrella company pay with the Check Take Home Pay API, POST /v1/umbrella-pay: every field, an example request in cURL, Node.js and Python, and the response.

Web version: https://checktakehomepay.co.uk/docs/api/umbrella-pay · Last updated: 2026-10-09

# 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

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

Node.js

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

Python

```
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](https://api.checktakehomepay.co.uk/openapi.json).

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](https://checktakehomepay.co.uk/docs/errors).