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

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

# Director salary and dividends

`POST /v1/director-pay` Needs a key

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.

## 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 | The company's profit for the year before the director's salary and its employer NI. 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"`. |
| `salary` optional | number | The director's salary for the year; the usual choices are tried when not given. Allowed: 0 or more, under 100,000,000. |
| `dividends` optional | number | Dividends paid; all the profit left after corporation tax when not given. Allowed: 0 or more, under 100,000,000. |
| `employer_pension` optional | number | The company's pension contribution for the director. Allowed: 0 or more, under 100,000,000. Default `0`. |
| `employment_allowance` optional | boolean | Sets the Employment Allowance against employer NI. Not available where the director is the only employee paid above the secondary threshold. Default `false`. |
| `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 `[]`. |

## Example

cURL

```
curl https://api.checktakehomepay.co.uk/v1/director-pay \
  -H "Authorization: Bearer $CHECKTAKEHOMEPAY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "region": "england",
  "profit": 100000
}'
```

Node.js

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

Python

```
import os
import requests

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

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