This version is in beta - expect some breaking changes.
Individual Calculations (MTD) API
|Available in Sandbox||Yes|
|Sandbox base URL||https://test-api.service.hmrc.gov.uk|
|Available in Production||No|
The individual calculations API allows a self-assessment taxpayer via software, to:
- trigger a self-assessment tax calculation
- list all their self-assessment tax calculations for a Tax year
- retrieve their self-assessment tax calculation result using multiple endpoints
A calculation result is linked to a Calculation ID. The Calculation ID will be returned when triggering a self-assessment tax calculation or it can be retrieved by listing all self-assessment tax calculations for a Tax year.
A Calculation ID will not always have a calculation result. Errors in previously submitted income data can prevent a calculation from being performed. Calculation errors that are present can be returned to the taxpayer via the Retrieve self-assessment tax calculation messages endpoint.
You can find the changelog in the individual-calculations-api GitHub wiki.
It may not be possible to test all scenarios in the sandbox. You can test some scenarios by passing the Gov-Test-Scenario header. Documentation for each endpoint includes a Test data section, which explains the scenarios that you can simulate using the Gov-Test-Scenario header.
If you have a specific testing need that is not supported in the sandbox, contact our support team.
Some APIs may be marked [test only]. This means that they are not available for use in production and may change.
When an API changes in a way that is backwards-incompatible, we increase the version number of the API. See our reference guide for more on versioning.
We use standard HTTP status codes to show whether an API request succeeded or not. They are usually in the range:
- 200 to 299 if it succeeded, including code 202 if it was accepted by an API that needs to wait for further action
- 400 to 499 if it failed because of a client error by your application
- 500 to 599 if it failed because of an error on our server
Errors specific to each API are shown in the Endpoints section, under Response. See our reference guide for more on errors.
Here a developer can:
- List self-assessment tax calculations for a given National Insurance number (NINO) and tax year
- Trigger a self-assessment tax calculation for a given tax year. The result of the calculation can be explored via the “Retrieve a self-assessment tax calculation metadata” endpoint
- Retrieve high-level calculation metadata for a given Calculation ID
- Retrieve the calculated Income Tax and National Insurance contributions for a given NINO and Calculation ID
- Retrieve the taxable income that has been used in the self-assessment tax calculation for a given NINO and Calculation ID
- Retrieve the allowances, deductions and reliefs that exist for the self assessment tax calculation for a given NINO and Calculation ID
- Retrieve the end-of-year Income Tax and National Insurance contribution estimates for a given NINO and Calculation ID
- Retrieve “info”, “warning” and “error” level messages linked to a Calculation ID