> Self-employed take-home with the Check Take Home Pay API, POST /v1/self-employed: every field, an example request in cURL, Node.js and Python, and the response.

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

# Self-employed take-home

`POST /v1/self-employed` Needs a key

A sole trader's year through Self Assessment: income tax, Class 4 NI, voluntary Class 2, student loans and relief at source pension contributions.

## Request

A JSON body. Fields not listed here are rejected.

| Field | Type | Description |
| --- | --- | --- |
| `region` required | string | Where they live: england, scotland, wales or northern\_ireland. One of `england`, `scotland`, `wales`, `northern_ireland`. |
| `profit` required | number | Taxable profits for the year. Allowed: 0 or more, under 100,000,000. |
| `tax_year` optional | string | The tax year, such as 2026-27. The latest when not given. Default `"2026-27"`. |
| `pension` optional | number | Gross relief at source pension contributions for the year. Allowed: 0 or more, under 100,000,000. Default `0`. |
| `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`. Default `[]`. |
| `voluntary_class_2` optional | boolean | Pays voluntary Class 2 NI, for a year of State Pension with profits below the small profits threshold. Default `false`. |
| `blind` optional | boolean | Blind Person's Allowance. Default `false`. |
| `marriage_allowance` optional | string | Marriage Allowance: transferring or receiving. One of `transferring`, `receiving`. |

## Example

cURL

```
curl https://api.checktakehomepay.co.uk/v1/self-employed \
  -H "Authorization: Bearer $CHECKTAKEHOMEPAY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "region": "england",
  "profit": 50000,
  "student_loans": [
    "plan_2"
  ]
}'
```

Node.js

```
const response = await fetch('https://api.checktakehomepay.co.uk/v1/self-employed', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.CHECKTAKEHOMEPAY_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "region": "england",
    "profit": 50000,
    "student_loans": [
      "plan_2"
    ]
  }),
});
const result = await response.json();
```

Python

```
import os
import requests

response = requests.post(
    "https://api.checktakehomepay.co.uk/v1/self-employed",
    headers={"Authorization": f"Bearer {os.environ['CHECKTAKEHOMEPAY_API_KEY']}"},
    json={
        "region": "england",
        "profit": 50000,
        "student_loans": ["plan_2"],
    },
)
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",
  "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"
  ]
}
```

## 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).