GOV.UK
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 |
Overview
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.
Changelog
You can find the changelog in the individual-calculations-api GitHub wiki.
Support
- Raise non-technical or platform-related issues with the Software Development Support Team (SDST).
- Raise technical issues on the individual-calculations-api GitHub page.
Testing
You can use the sandbox environment to test this API. You can use the Create Test User API or it's frontend service to create test users.
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.
Versioning
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.
Errors
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.
Endpoints
Self Assessment
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
Self Assessment resources
/individuals/calculations/{nino}/self-assessment
The “List Self Assessment tax calculations” endpoint allows users to list their Self Assessment tax calculations for the supplied NINO and given tax year.
Authorisation
This endpoint is
user-restricted
- it requires an Authorization header containing an OAuth 2.0 Bearer Token with the read:self-assessment scope.
Path parameters
| Name | Description |
|---|---|
|
nino
string
required
|
National Insurance number, in the format AA999999A.
For example: |
Query parameters
| Name | Description |
|---|---|
|
taxYear
string
optional
|
The tax year the data applies to, for example, 2019-20. Calculations for the current tax year are returned if no tax year is supplied.
For example: |
Request headers
| Name | Description |
|---|---|
|
Accept
required
|
Specifies the response format and the version of the API to be used. For example: application/vnd.hmrc.1.0+json
|
|
Gov-Test-Scenario
optional
|
Only in sandbox environment. See Test Data table for all header values. For example: -
|
|
Authorization
required
|
An
OAuth 2.0 Bearer Token
with the read:self-assessment scope.
For example: Bearer bb7fed3fe10dd235a2ccda3d50fb
|
See also fraud prevention for other request headers which will become mandatory.
Response headers
| Name | Description |
|---|---|
|
X-CorrelationId
required
|
Unique ID for operation tracking For example: c75f40a6-a3df-4429-a697-471eeec46435
|
See also fraud prevention for other request headers which will become mandatory.
Response
HTTP status: 200 (OK)
{
"calculations": [
{
"id": "f2fb30e5-4ab6-4a29-b3c1-c7264259ff1c",
"calculationTimestamp": "2019-03-17T09:22:59Z",
"type": "inYear",
"requestedBy": "hmrc"
},
{
"id": "cf63c46a-1a4f-3c56-b9ea-9a82551d27bb",
"calculationTimestamp": "2019-06-17T18:45:59Z",
"type": "crystallisation",
"requestedBy": "customer"
}
]
}
| Name | Description |
|---|---|
|
calculations
array
required
|
An array of calculation objects. An empty array will never be returned. In the instance that no calculations exist for the supplied NINO and tax year, a MATCHING_RESOURCE_NOT_FOUND error will be returned. |
|
id
string
required
|
The unique identifier of the calculation.
Must conform to the regular expression
For example: |
|
calculationTimestamp
string
required
|
The timestamp of when the calculation was performed in ISO8601 UTC format: YYYY-MM-DDThh:mm:ssZ.
For example: |
|
type
string
required
|
The type of calculation performed. Limited to the following possible values: inYear
crystallisation
|
|
requestedBy
string
optional
|
The requestor of the calculation. Currently agent will default to customer until it can be supported. Limited to the following possible values: customer
hmrc
agent
|
Error scenarios
| Scenario | HTTP status | Code |
|---|---|---|
|
The format of the supplied NINO is not valid |
400 (Bad Request) |
FORMAT_NINO |
|
The format of the supplied tax year field is not valid |
400 (Bad Request) |
FORMAT_TAX_YEAR |
|
The specified tax year is not supported. That is, the tax year specified is before the minimum tax year value. |
400 (Bad Request) |
RULE_TAX_YEAR_NOT_SUPPORTED |
|
Tax year range exceeded. A tax year range of one year is required. |
400 (Bad Request) |
RULE_TAX_YEAR_RANGE_EXCEEDED |
|
The client and/or agent is not authorised. This is normally because: the client is not subscribed to MTD, the agent is not subscribed to Agent Services, or the client has not authorised the agent to act on their behalf. |
403 (Forbidden) |
CLIENT_OR_AGENT_NOT_AUTHORISED |
|
No tax calculations can be found for the supplied NINO and tax year. |
404 (Not Found) |
MATCHING_RESOURCE_NOT_FOUND |
For error scenarios that are common across all APIs, and for error formats, see our reference guide.
Test data
Scenario simulations using Gov-Test-Scenario headers is only available in the sandbox environment.
| Header Value (Gov-Test-Scenario) | Scenario |
|---|---|
N/A - DEFAULT |
Simulate success scenario for self-employment |
CRYSTALLISATION |
Simulate success scenario where a crystallisation calculation is found |
MULTIPLE_CALCULATIONS |
Simulate success scenario where multiple tax calculations are found |
NOT_FOUND |
Simulates the scenario where no tax calculations could be found for the supplied NINO and tax year |
This endpoint allows the user to trigger a self assessment tax calculation for a supplied tax year. The result of the calculation can be explored via the “Retrieve a self assessment tax calculation metadata” endpoint.
Authorisation
This endpoint is
user-restricted
- it requires an Authorization header containing an OAuth 2.0 Bearer Token with the write:self-assessment scope.
Path parameters
| Name | Description |
|---|---|
|
nino
string
required
|
National Insurance number, in the format AA999999A.
For example: |
Request headers
| Name | Description |
|---|---|
|
Accept
required
|
Specifies the response format and the version of the API to be used. For example: application/vnd.hmrc.1.0+json
|
|
Content-Type
required
|
Specifies the format of the request body, which must be JSON. For example: application/json
|
|
Gov-Test-Scenario
optional
|
Only in sandbox environment. See Test Data table for all header values. For example: -
|
|
Authorization
required
|
An
OAuth 2.0 Bearer Token
with the write:self-assessment scope.
For example: Bearer bb7fed3fe10dd235a2ccda3d50fb
|
See also fraud prevention for other request headers which will become mandatory.
Request
{
"taxYear": "2017-18"
}
| Name | Description |
|---|---|
|
taxYear
string
required
|
The tax year that the calculation is being triggered for. The start year and end year must not span two tax years. No gaps are allowed, for example, 2019-21 is not valid. The minimum tax year is 2017-18.
For example: |
Response headers
| Name | Description |
|---|---|
|
X-CorrelationId
required
|
Unique ID for operation tracking For example: c75f40a6-a3df-4429-a697-471eeec46435
|
See also fraud prevention for other request headers which will become mandatory.
Response
HTTP status: 202 (Accepted)
{
"id": "f2fb30e5-4ab6-4a29-b3c1-c7264259ff1c"
}
| Name | Description |
|---|---|
|
id
string
required
|
The unique identifier of the calculation.
Must conform to the regular expression
For example: |
Error scenarios
| Scenario | HTTP status | Code |
|---|---|---|
|
The format of the supplied NINO is not valid |
400 (Bad Request) |
FORMAT_NINO |
|
The format of the supplied tax year field is not valid |
400 (Bad Request) |
FORMAT_TAX_YEAR |
|
The specified tax year is not supported. That is, the tax year specified is before the minimum tax year value. |
400 (Bad Request) |
RULE_TAX_YEAR_NOT_SUPPORTED |
|
Tax year range exceeded. A tax year range of one year is required. |
400 (Bad Request) |
RULE_TAX_YEAR_RANGE_EXCEEDED |
|
An empty or non-matching body was submitted, this could be caused by a missing mandatory field |
400 (Bad Request) |
RULE_INCORRECT_OR_EMPTY_BODY_SUBMITTED |
|
The client and/or agent is not authorised. This is normally because: the client is not subscribed to MTD, the agent is not subscribed to Agent Services, or the client has not authorised the agent to act on their behalf. |
403 (Forbidden) |
CLIENT_OR_AGENT_NOT_AUTHORISED |
|
A calculation could not be performed because no income data has been submitted against the tax year |
403 (Forbidden) |
RULE_NO_INCOME_SUBMISSIONS_EXIST |
For error scenarios that are common across all APIs, and for error formats, see our reference guide.
Test data
Scenario simulations using Gov-Test-Scenario headers is only available in the sandbox environment.
| Header Value (Gov-Test-Scenario) | Scenario |
|---|---|
N/A - DEFAULT |
Simulates a successful response |
NO_INCOME_SUBMISSIONS_EXIST |
Simulates the scenario where no income submissions exist for the tax year |
/individuals/calculations/{nino}/self-assessment/{calculationId}
The “Retrieve Self Assessment tax calculation metadata” endpoint allows users to retrieve high-level calculation metadata for a given Calculation ID. There will always be calculation metadata associated to a Calculation ID that exists within HMRC. Calculation metadata is mutable and can be updated after a calculation has been run, an example scenario being when a crystallisation declaration has been accepted by HMRC.
Authorisation
This endpoint is
user-restricted
- it requires an Authorization header containing an OAuth 2.0 Bearer Token with the read:self-assessment scope.
Path parameters
| Name | Description |
|---|---|
|
nino
string
required
|
National Insurance number, in the format AA999999A.
For example: |
|
calculationId
string
required
|
The unique identifier of the calculation. Must conform the regular expression:
For example: |
Request headers
| Name | Description |
|---|---|
|
Accept
required
|
Specifies the response format and the version of the API to be used. For example: application/vnd.hmrc.1.0+json
|
|
Gov-Test-Scenario
optional
|
Only in sandbox environment. See Test Data table for all header values. For example: -
|
|
Authorization
required
|
An
OAuth 2.0 Bearer Token
with the read:self-assessment scope.
For example: Bearer bb7fed3fe10dd235a2ccda3d50fb
|
See also fraud prevention for other request headers which will become mandatory.
Response headers
| Name | Description |
|---|---|
|
X-CorrelationId
required
|
Unique ID for operation tracking For example: c75f40a6-a3df-4429-a697-471eeec46435
|
See also fraud prevention for other request headers which will become mandatory.
Response
HTTP status: 200 (OK)
{
"id": "f2fb30e5-4ab6-4a29-b3c1-c7264259ff1c",
"taxYear": "2018-19",
"requestedBy": "customer",
"calculationReason": "customerRequest",
"calculationTimestamp": "2019-11-15T09:35:15.094Z",
"calculationType": "crystallisation",
"intentToCrystallise": true,
"crystallised": true,
"totalIncomeTaxAndNicsDue": 5010.34
}
{
"id": "b03921dc-8e23-5e8a-bf0e-55a8e3904673",
"taxYear": "2018-19",
"requestedBy": "customer",
"calculationReason": "customerRequest",
"calculationTimestamp": "2019-02-15T08:22:15.094Z",
"calculationType": "inYear",
"intentToCrystallise": false,
"crystallised": false,
"totalIncomeTaxAndNicsDue": 2000.98
}
{
"id": "17d6876e-620e-4059-96ef-50adf5422d27",
"taxYear": "2018-19",
"requestedBy": "hmrc",
"calculationReason": "newClaimEvent",
"calculationTimestamp": "2019-07-04T13:37:35.094Z",
"calculationType": "inYear",
"intentToCrystallise": false,
"crystallised": false,
"calculationErrorCount": 8
}
| Name | Description |
|---|---|
|
id
string
required
|
The unique identifier of the calculation.
Must conform to the regular expression
For example: |
|
taxYear
string
required
|
The Tax year in which the calculation was performed in the format YYYY-YY
For example: |
|
requestedBy
string
required
|
The requestor of the calculation. Currently agent will default to customer until it can be supported. Limited to the following possible values: customer
hmrc
agent
|
|
calculationReason
string
required
|
The reason why the calculation was triggered Limited to the following possible values: customerRequest
- The calculation was triggered by the customer via software.
class2NICEvent
- The calculation was triggered internally by HMRC once the actual Class 2 NIC amount is available. This event is only applicable for an in-year "crystallisation" calculation type.
newLossEvent
- The calculation was triggered internally by HMRC on receipt of a new pre-MTD brought forward loss made by the customer. This event is only applicable for a "crystallisation" calculation type. This event is not currently supported and will be supported in the future.
newClaimEvent
- The calculation was triggered internally by HMRC on receipt of a new loss claim made by the customer. This event is only applicable for a "crystallisation" calculation type. This event is not currently supported and will be supported in the future.
updatedClaimEvent
- The calculation was triggered internally by HMRC on receipt of an updated loss claim made by the customer. This event is only applicable for a "crystallisation" calculation type. This event is not currently supported and will be supported in the future.
updatedLossEvent
- The calculation was triggered internally by HMRC on receipt of an updated pre-MTD brought forward loss made by the customer. This event is only applicable for a "crystallisation" calculation type. This event is not currently supported and will be supported in the future.
newAnnualAdjustmentEvent
- The calculation was triggered internally by HMRC on receipt of a request for a new adjustable summary calculation by the customer. This event is not currently supported.
updatedAnnualAdjustmentEvent
- The calculation was triggered internally by HMRC on receipt of an adjustment to an adjustable summary calculation made by the customer. This event is not currently supported.
|
|
calculationTimestamp
string
optional
|
The timestamp of when the calculation was performed in ISO8601 UTC format: YYYY-MM-DDThh:mm:ssZ.
For example: |
|
calculationType
string
required
|
The type of calculation performed. A "crystallisation" calculation is a calculation triggered via the "Intent to crystallise" endpoint under the "Self Assessment (MTD)" API. Limited to the following possible values: inYear
crystallisation
|
|
intentToCrystallise
boolean
required
|
Boolean value showing whether the calculation is intended to be crystallised against. Valid values are true or false
For example: |
|
crystallised
boolean
required
|
Boolean value showing whether the calculation is intended to be crystallised against. Valid values are true or false
For example: |
|
totalIncomeTaxAndNicsDue
number
optional
|
The total amount of Income Tax and National Insurance Contributions due. This field is not present if the calculationErrorCount value is greater than zero. This value must be between -99999999999.99 and 99999999999.99.
For example: |
|
calculationErrorCount
number
optional
|
A count of error messages generated during the calculation. If the field is present it indicates a calculation has not been performed. Further detail can be found in the "Retrieve Self Assessment tax calculation messages" endpoint about the errors.
For example: |
Error scenarios
| Scenario | HTTP status | Code |
|---|---|---|
|
The format of the supplied NINO is not valid |
400 (Bad Request) |
FORMAT_NINO |
|
The format of the supplied Calculation ID is not valid |
400 (Bad Request) |
FORMAT_CALC_ID |
|
The client and/or agent is not authorised. This is normally because: the client is not subscribed to MTD, the agent is not subscribed to Agent Services, or the client has not authorised the agent to act on their behalf. |
403 (Forbidden) |
CLIENT_OR_AGENT_NOT_AUTHORISED |
|
No tax calculation data exists for the supplied NINO and calculation ID. |
404 (Not Found) |
MATCHING_RESOURCE_NOT_FOUND |
For error scenarios that are common across all APIs, and for error formats, see our reference guide.
Test data
Scenario simulations using Gov-Test-Scenario headers is only available in the sandbox environment.
| Header Value (Gov-Test-Scenario) | Scenario |
|---|---|
N/A - DEFAULT |
Simulates returning an in year tax calculation with all fields. |
CRYSTALLISATION_METADATA |
Simulates returning a crystallisation tax calculation with all fields. |
ERROR_MESSAGES_EXIST |
Simulates the scenario where errors exist and no calculation has been generated. |
NOT_FOUND |
Simulates the scenario where no data can be found. |
UK_MULTIPLE_INCOMES_EXAMPLE |
Simulates an example tax calculation with realistic data values, for a UK FHL Property business with Savings and Dividends. |
UK_PROP_DIVIDENDS_EXAMPLE |
Simulates an example tax calculation with realistic data values, for a UK Non-FHL Property business with Dividends. |
UK_PROP_GIFTAID_EXAMPLE |
Simulates an example tax calculation with realistic data values, for a UK Non-FHL Property business with Gift Aid. |
UK_PROP_SAVINGS_EXAMPLE |
Simulates an example tax calculation with realistic data values, for a UK Non-FHL Property business with Savings. |
UK_SE_GIFTAID_EXAMPLE |
Simulates an example tax calculation with realistic data values, for a UK Self-Employment business with Gift Aid. |
UK_SE_SAVINGS_EXAMPLE |
Simulates an example tax calculation with realistic data values, for a UK Self-Employment business with Savings. |
SCOT_SE_DIVIDENDS_EXAMPLE |
Simulates an example tax calculation with realistic data values, for a Scottish Self-Employment business with Dividends. |
/individuals/calculations/{nino}/self-assessment/{calculationId}/income-tax-nics-calculated
This endpoint allows you to retrieve the calculated Income Tax and National Insurance Contributions for a given NINO and Calculation ID.
An error will occur if your calculation has one or more error messages. You can use the Retrieve Self Assessment Tax Calculation Messages endpoint to retrieve these messages.
Authorisation
This endpoint is
user-restricted
- it requires an Authorization header containing an OAuth 2.0 Bearer Token with the read:self-assessment scope.
Path parameters
| Name | Description |
|---|---|
|
nino
string
required
|
National Insurance number, in the format AA999999A.
For example: |
|
calculationId
string
required
|
The unique identifier of the calculation. Must conform the regular expression:
For example: |
Request headers
| Name | Description |
|---|---|
|
Accept
required
|
Specifies the response format and the version of the API to be used. For example: application/vnd.hmrc.1.0+json
|
|
Gov-Test-Scenario
optional
|
Only in sandbox environment. See Test Data table for all header values. For example: -
|
|
Authorization
required
|
An
OAuth 2.0 Bearer Token
with the read:self-assessment scope.
For example: Bearer bb7fed3fe10dd235a2ccda3d50fb
|
See also fraud prevention for other request headers which will become mandatory.
Response headers
| Name | Description |
|---|---|
|
X-CorrelationId
required
|
Unique ID for operation tracking For example: c75f40a6-a3df-4429-a697-471eeec46435
|
See also fraud prevention for other request headers which will become mandatory.
Response
HTTP status: 200 (OK)
{
"summary": {
"incomeTax": {
"incomeTaxCharged": 1000.12,
"incomeTaxDueAfterReliefs": 1000.12,
"incomeTaxDueAfterGiftAid": 1000.12
},
"nics": {
"class2NicsAmount": 1000.12,
"class4NicsAmount": 1000.12,
"totalNic": 1000.12
},
"totalIncomeTaxNicsCharged": 1000.12,
"totalTaxDeducted": 1000,
"totalIncomeTaxAndNicsDue": 1000.12,
"taxRegime": "UK"
},
"detail": {
"incomeTax": {
"payPensionsProfit": {
"allowancesAllocated": 1000,
"incomeTaxAmount": 1000,
"taxBands": [
{
"name": "SRT",
"rate": 10.12,
"bandLimit": 1000,
"apportionedBandLimit": 1000,
"income": 1000,
"taxAmount": 1000.12
}
]
},
"savingsAndGains": {
"allowancesAllocated": 1000,
"incomeTaxAmount": 1000,
"taxBands": [
{
"name": "SSR",
"rate": 10.12,
"bandLimit": 1000,
"apportionedBandLimit": 1000,
"income": 1000,
"taxAmount": 1000.12
}
]
},
"dividends": {
"allowancesAllocated": 1000,
"incomeTaxAmount": 1000,
"taxBands": [
{
"name": "BRT",
"rate": 10.12,
"bandLimit": 1000,
"apportionedBandLimit": 1000,
"income": 1000,
"taxAmount": 1000.12
}
]
},
"giftAid": {
"grossGiftAidPayments": 1000,
"rate": 10.12,
"giftAidTax": 1000.12
}
},
"nics": {
"class2Nics": {
"weeklyRate": 1000.12,
"weeks": 10,
"limit": 1000,
"apportionedLimit": 1000,
"underSmallProfitThreshold": true,
"actualClass2Nic": true
},
"class4Nics": {
"class4Losses": {
"totalClass4LossesAvailable": 1000,
"totalClass4LossesUsed": 1000
},
"totalIncomeLiableToClass4Charge": 1000,
"totalIncomeChargeableToClass4": 1000,
"class4NicBands": [
{
"name": "ZRT",
"rate": 10.12,
"threshold": 1000,
"apportionedThreshold": 1000,
"income": 1000,
"amount": 1000.12
}
]
}
},
"taxDeductedAtSource": {
"savings": 1000,
"ukLandAndProperty": 1000
}
}
}
| Name | Description |
|---|---|
|
summary
object
required
|
Details the high-level Income Tax and National Insurance Contributions due. |
|
incomeTax
object
required
|
Details the high-level Income Tax due. |
|
incomeTaxCharged
number
required
|
The total amount of Income Tax charged. This value must be between 0 and 99999999999.99 up to 2 decimal places.
For example: |
|
incomeTaxDueAfterReliefs
number
optional
|
The total amount of Income Tax due after reliefs have been applied. This value must be between -99999999999.99 and 99999999999.99 up to 2 decimal places.
For example: |
|
incomeTaxDueAfterGiftAid
number
optional
|
The total amount of tax due after Gift Aid donations have been considered. This value must be between 0 and 99999999999.99 up to 2 decimal places.
For example: |
|
nics
object
optional
|
Details the high-level National Insurance contributions due. |
|
class2NicsAmount
number
optional
|
The calculated amount of Class 2 National Insurance contributions. This value must be between 0 and 99999999999.99 up to 2 decimal places.
For example: |
|
class4NicsAmount
number
optional
|
The calculated amount of Class 4 National Insurance contributions. This value must be between 0 and 99999999999.99 up to 2 decimal places.
For example: |
|
totalNic
number
optional
|
The total amount of Class 2 and Class 4 National Insurance Contributions due. This value must be between -99999999999.99 and 99999999999.99
For example: |
|
totalIncomeTaxNicsCharged
number
optional
|
The total amount of Income Tax and National Insurance contributions charged. This field is returned if totalTaxDeducted is present. This value must be between -99999999999.99 and 99999999999.99 up to 2 decimal places.
For example: |
|
totalTaxDeducted
number
optional
|
Total Income Tax deducted from your income, set against total Income Tax and National Insurance charged. This value must be between 0 and 99999999999. No decimals.
For example: |
|
totalIncomeTaxAndNicsDue
number
required
|
The total amount of Income Tax and National Insurance Contributions due. If the totalTaxDeducted field is present then the totalIncomeTaxNicsDue figure is totalIncomeTaxNicsCharged minus totalTaxDeducted. This value must be between -99999999999.99 and 99999999999.99 up to 2 decimal places.
For example: |
|
taxRegime
string
required
|
The national tax rates and rules that apply to the calculation. Limited to the following possible values: UK
Scotland
Wales
|
|
detail
object
required
|
Details the low-level summary amounts for Income Tax and National Insurance Contributions due. |
|
incomeTax
object
required
|
Details the low-level summary amounts for Income Tax due. |
|
payPensionsProfit
object
optional
|
|
|
allowancesAllocated
number
required
|
The allowances allocated to pay, pensions and profit Income Tax calculation. This value must be between 0 and 99999999999. No decimals.
For example: |
|
incomeTaxAmount
number
required
|
The calculated amount of Income Tax for the tax band. This value must be between 0 and 99999999999.99 up to 2 decimal places.
For example: |
|
taxBands
array
optional
|
|
|
name
string
required
|
The name of the tax band threshold. Limited to the following possible values: SRT
- Scottish starter rate threshold
BRT
- basic rate threshold
IRT
- intermediary rate threshold (Scottish only)
HRT
- higher rate threshold
ART
- additional rate threshold
|
|
rate
number
required
|
The rate associated with the tax band. This value must be between 0 and 99.99 up to 2 decimal places.
For example: |
|
bandLimit
number
required
|
The upper threshold for the tax band excluding personal allowance. This value must be between 0 and 99999999999. No decimals.
For example: |
|
apportionedBandLimit
number
required
|
The apportioned threshold for the tax band, excluding personal allowance. This value must be between 0 and 99999999999. No decimals.
For example: |
|
income
number
required
|
The amount of taxable income for the tax band. This value must be between 0 and 99999999999. No decimals.
For example: |
|
taxAmount
number
required
|
The calculated amount of Income Tax for the tax band. This value must be between 0 and 99999999999.99 up to 2 decimal places.
For example: |
|
savingsAndGains
object
optional
|
Details the low-level income tax for savings and gains income |
|
allowancesAllocated
number
required
|
The allowances allocated to the savings and gains Income Tax calculation. This value must be between 0 and 99999999999. No decimals.
For example: |
|
incomeTaxAmount
number
required
|
The total amount of Income Tax associated with savings and gains. This value must be between 0 and 99999999999.99 up to 2 decimal places.
For example: |
|
taxBands
array
optional
|
|
|
name
string
required
|
The name of the tax band. Limited to the following possible values: SSR
- savings starter rate threshold
BRT
- basic rate threshold
HRT
- higher rate threshold
ART
- additional rate threshold
ZRTBR
- personal savings allowance awarded at basic rate
ZRTHR
- personal savings allowance awarded at higher rate
|
|
rate
number
required
|
The rate associated with the tax band. This value must be between 0 and 99.99 up to 2 decimal places.
For example: |
|
bandLimit
number
required
|
The upper threshold for the tax band excluding personal allowance. This value must be between 0 and 99999999999. No decimals.
For example: |
|
apportionedBandLimit
number
required
|
The apportioned threshold for the tax band, excluding personal allowance. This value must be between 0 and 99999999999. No decimals.
For example: |
|
income
number
required
|
The amount of taxable income for the tax band. This value must be between 0 and 99999999999. No decimals.
For example: |
|
taxAmount
number
required
|
The calculated amount of Income Tax for the tax band. This value must be between 0 and 99999999999.99 up to 2 decimal places.
For example: |
|
dividends
object
optional
|
Details the low-level income tax for dividends income |
|
allowancesAllocated
number
required
|
The allowances allocated to the dividends Income Tax calculation. This value must be between 0 and 99999999999. No decimals.
For example: |
|
incomeTaxAmount
number
required
|
The total amount of Income Tax associated with dividends. This value must be between 0 and 99999999999.99 up to 2 decimal places.
For example: |
|
taxBands
array
optional
|
|
|
name
string
required
|
The name of the tax band. Limited to the following possible values: BRT
- basic rate threshold
HRT
- higher rate threshold
ART
- additional rate threshold
ZRTBR
- dividend allowance awarded at basic rate
ZRTHR
- dividend allowance awarded at higher rate
ZRTAR
- dividend allowance awarded at additional rate
|
|
rate
number
required
|
The rate associated with the tax band. This value must be between 0 and 99.99 up to 2 decimal places.
For example: |
|
bandLimit
number
required
|
The upper threshold for the tax band excluding personal allowance. This value must be between 0 and 99999999999. No decimals.
For example: |
|
apportionedBandLimit
number
required
|
The apportioned threshold for the tax band, excluding personal allowance. This value must be between 0 and 99999999999. No decimals.
For example: |
|
income
number
required
|
The amount of taxable income for the tax band. This value must be between 0 and 99999999999. No decimals.
For example: |
|
taxAmount
number
required
|
The calculated amount of Income Tax for the tax band. This value must be between 0 and 99999999999.99 up to 2 decimal places.
For example: |
|
giftAid
object
optional
|
Details the low-level income tax for Gift Aid |
|
grossGiftAidPayments
number
required
|
The total amount of Gift Aid payments made for the tax year. This value must be between 0 and 99999999999. No decimals.
For example: |
|
rate
number
required
|
The basic rate of tax that applies to Gift Aid payments made. This value must be between 0 and 99.99 up to 2 decimal places.
For example: |
|
giftAidTax
number
required
|
The amount of Gift Aid tax charged when insufficient Income Tax has been paid. This value must be between 0 and 99999999999.99 up to 2 decimal places.
For example: |
|
nics
object
optional
|
Details the low-level National Insurance Contributions |
|
class2Nics
object
optional
|
Details the low-level Class 2 National Insurance Contributions |
|
weeklyRate
number
optional
|
The weekly rate for Class 2 National Insurance contributions. This value must be between 0 and 99999999999.99 up to 2 decimal places.
For example: |
|
weeks
number
optional
|
The number of weeks applied to calculate Class 2 National Insurance contributions. This value is a whole number in the range 0 to 52.
For example: |
|
limit
number
optional
|
The annual limit of Class 2 National Insurance contributions. This value must be between 0 and 99999999999. No decimals.
For example: |
|
apportionedLimit
number
optional
|
The apportioned amount of annual Class 2 National Insurance contributions. This value must be between 0 and 99999999999. No decimals.
For example: |
|
underSmallProfitThreshold
boolean
required
|
Boolean showing whether the self employment profits are under the Class 2 NIC small profits threshold.
For example: |
|
actualClass2Nic
boolean
optional
|
Boolean showing whether the class 2 NIC charge is an actual charge or estimated charge in this calculation.
For example: |
|
class4Nics
object
optional
|
Details the low-level Class 4 National Insurance Contributions |
|
class4Losses
object
optional
|
Details the class 4 losses in relation to the Class 4 National Insurance Contributions |
|
totalClass4LossesAvailable
number
optional
|
Total class 4 losses that are available to the calculation. This value must be between 0 and 99999999999. No decimals.
For example: |
|
totalClass4LossesUsed
number
optional
|
Total class 4 losses that have been used in the calculation. This value must be between 0 and 99999999999. No decimals.
For example: |
|
totalIncomeLiableToClass4Charge
number
optional
|
Total income that is liable to Class 4 National Insurance Contributions. This value must be between 0 and 99999999999. No decimals.
For example: |
|
totalIncomeChargeableToClass4
number
optional
|
Total income that is chargeable to Class 4 National Insurance Contributions. This value must be between 0 and 99999999999. No decimals.
For example: |
|
class4NicBands
array
optional
|
Details the low-level Class 4 National Insurance Contributions |
|
name
string
required
|
The name of the tax band threshold. Limited to the following possible values: ZRT
- zero rate threshold
BRT
- basic rate threshold
HRT
- higher rate threshold
|
|
rate
number
required
|
The rate associated with the tax band. This value must be between 0 and 99.99 up to 2 decimal places.
For example: |
|
threshold
number
optional
|
The upper threshold for the tax band. This value must be between 0 and 99999999999. No decimals.
For example: |
|
apportionedThreshold
number
optional
|
The amount of the upper threshold that has been apportioned. This value must be between 0 and 99999999999.
For example: |
|
income
number
required
|
The income within the Class 4 National Insurance Contribution band threshold applicable for contributions. This value must be between 0 and 99999999999. No decimals.
For example: |
|
amount
number
required
|
The amount of Class 4 National Insurance Contributions due on the income within the band. This value must be between 0 and 99999999999.99 up to 2 decimal places.
For example: |
|
taxDeductedAtSource
object
optional
|
Summarises income received that has already been tax deducted. |
|
savings
number
optional
|
Tax deducted at source from interest received from UK banks and building societies. This value must be between 0 and 99999999999. No decimals.
For example: |
|
ukLandAndProperty
number
optional
|
Tax that has been deducted at source for UK land and property. This value must be between 0 and 99999999999. No decimals.
For example: |
Error scenarios
| Scenario | HTTP status | Code |
|---|---|---|
|
The format of the supplied NINO is not valid |
400 (Bad Request) |
FORMAT_NINO |
|
The format of the supplied Calculation ID is not valid |
400 (Bad Request) |
FORMAT_CALC_ID |
|
The client and/or agent is not authorised. This is normally because: the client is not subscribed to MTD, the agent is not subscribed to Agent Services, or the client has not authorised the agent to act on their behalf. |
403 (Forbidden) |
CLIENT_OR_AGENT_NOT_AUTHORISED |
|
No Income Tax and National Insurance Contributions data exists for the supplied calculation ID and NINO because error messages were generated while performing the calculation. These error messages can be viewed using the "Retrieve self assessment tax calculation messages" endpoint. |
403 (Forbidden) |
RULE_CALCULATION_ERROR_MESSAGES_EXIST |
|
No tax calculation data exists for the supplied NINO and calculation ID. |
404 (Not Found) |
MATCHING_RESOURCE_NOT_FOUND |
For error scenarios that are common across all APIs, and for error formats, see our reference guide.
Test data
Scenario simulations using Gov-Test-Scenario headers is only available in the sandbox environment.
| Header Value (Gov-Test-Scenario) | Scenario |
|---|---|
N/A - DEFAULT |
Simulates returning a tax calculation with all fields. |
ERROR_MESSAGES_EXIST |
Simulates the scenario where errors exist and no calculation has been generated. |
NOT_FOUND |
Simulates the scenario where no data can be found. |
UK_MULTIPLE_INCOMES_EXAMPLE |
Simulates an example tax calculation with realistic data values, for a UK FHL Property business with Savings and Dividends. |
UK_PROP_DIVIDENDS_EXAMPLE |
Simulates an example tax calculation with realistic data values, for a UK Non-FHL Property business with Dividends. |
UK_PROP_GIFTAID_EXAMPLE |
Simulates an example tax calculation with realistic data values, for a UK Non-FHL Property business with Gift Aid. |
UK_PROP_SAVINGS_EXAMPLE |
Simulates an example tax calculation with realistic data values, for a UK Non-FHL Property business with Savings. |
UK_SE_GIFTAID_EXAMPLE |
Simulates an example tax calculation with realistic data values, for a UK Self-Employment business with Gift Aid. |
UK_SE_SAVINGS_EXAMPLE |
Simulates an example tax calculation with realistic data values, for a UK Self-Employment business with Savings. |
SCOT_SE_DIVIDENDS_EXAMPLE |
Simulates an example tax calculation with realistic data values, for a Scottish Self-Employment business with Dividends. |
/individuals/calculations/{nino}/self-assessment/{calculationId}/taxable-income
This endpoint allows you to retrieve the taxable income that has been used in the self assessment tax calculation for a given NINO and Calculation ID.
An error will occur if your calculation has one or more error messages. You can use the Retrieve Self Assessment Tax Calculation Messages endpoint to retrieve these messages.
Authorisation
This endpoint is
user-restricted
- it requires an Authorization header containing an OAuth 2.0 Bearer Token with the read:self-assessment scope.
Path parameters
| Name | Description |
|---|---|
|
nino
string
required
|
National Insurance number, in the format AA999999A.
For example: |
|
calculationId
string
required
|
The unique identifier of the calculation. Must conform the regular expression:
For example: |
Request headers
| Name | Description |
|---|---|
|
Accept
required
|
Specifies the response format and the version of the API to be used. For example: application/vnd.hmrc.1.0+json
|
|
Gov-Test-Scenario
optional
|
Only in sandbox environment. See Test Data table for all header values. For example: -
|
|
Authorization
required
|
An
OAuth 2.0 Bearer Token
with the read:self-assessment scope.
For example: Bearer bb7fed3fe10dd235a2ccda3d50fb
|
See also fraud prevention for other request headers which will become mandatory.
Response headers
| Name | Description |
|---|---|
|
X-CorrelationId
required
|
Unique ID for operation tracking For example: c75f40a6-a3df-4429-a697-471eeec46435
|
See also fraud prevention for other request headers which will become mandatory.
Response
HTTP status: 200 (OK)
{
"summary": {
"totalIncomeReceivedFromAllSources": 1000,
"totalTaxableIncome": 1000
},
"detail": {
"payPensionsProfit": {
"incomeReceived": 1000,
"taxableIncome": 1000,
"totalSelfEmploymentProfit": 1000,
"totalPropertyProfit": 1000,
"totalFHLPropertyProfit": 1000,
"totalUKOtherPropertyProfit": 1000,
"businessProfitAndLoss": {
"selfEmployments": [
{
"selfEmploymentId": "XGIS00000001319",
"totalIncome": 1000.12,
"totalExpenses": 1000.12,
"netProfit": 1000.12,
"netLoss": 1000.12,
"class4Loss": 1000,
"totalAdditions": 1000.12,
"totalDeductions": 1000.12,
"accountingAdjustments": 1000.12,
"adjustedIncomeTaxLoss": 1000,
"taxableProfit": 1000,
"taxableProfitAfterIncomeTaxLossesDeduction": 1000,
"lossClaimsSummary": {
"totalBroughtForwardIncomeTaxLosses": 1000,
"broughtForwardIncomeTaxLossesUsed": 1000,
"totalIncomeTaxLossesCarriedForward": 1000,
"totalBroughtForwardClass4Losses": 1000,
"broughtForwardClass4LossesUsed": 1000,
"carrySidewaysClass4LossesUsed": 1000,
"totalClass4LossesCarriedForward": 1000
},
"lossClaimsDetail": {
"lossesBroughtForward": [
{
"lossType": "income",
"taxYearLossIncurred": "2018-19",
"currentLossValue": 1000,
"mtdLoss": false
}
],
"resultOfClaimsApplied": [
{
"claimId": "XGIS00000001319",
"taxYearClaimMade": "2018-19",
"claimType": "carry-forward",
"mtdLoss": false,
"taxYearLossIncurred": "2018-19",
"lossAmountUsed": 1000,
"remainingLossValue": 1000,
"lossType": "class4-nics"
}
],
"unclaimedLosses": [
{
"taxYearLossIncurred": "2018-19",
"currentLossValue": 1000,
"expires": "2018-19",
"lossType": "class4-nics"
}
],
"carriedForwardLosses": [
{
"claimId": "XGIS00000001319",
"claimType": "carry-forward",
"taxYearClaimMade": "2018-19",
"taxYearLossIncurred": "2018-19",
"currentLossValue": 1000,
"lossType": "class4-nics"
}
],
"claimsNotApplied": [
{
"claimId": "XGIS00000001319",
"taxYearClaimMade": "2018-19",
"claimType": "carry-forward"
}
]
}
}
],
"ukPropertyFhl": {
"totalIncome": 1000.12,
"totalExpenses": 1000.12,
"netProfit": 1000.12,
"netLoss": 1000.12,
"totalAdditions": 1000.12,
"totalDeductions": 1000.12,
"accountingAdjustments": 1000.12,
"adjustedIncomeTaxLoss": 1000,
"taxableProfit": 1000,
"taxableProfitAfterIncomeTaxLossesDeduction": 1000,
"lossClaimsSummary": {
"lossForCSFHL": 1000,
"totalBroughtForwardIncomeTaxLosses": 1000,
"broughtForwardIncomeTaxLossesUsed": 1000,
"totalIncomeTaxLossesCarriedForward": 1000
},
"lossClaimsDetail": {
"lossesBroughtForward": [
{
"taxYearLossIncurred": "2018-19",
"currentLossValue": 1000,
"mtdLoss": false
}
],
"resultOfClaimsApplied": [
{
"claimId": "EzluDU2ObK02SdA",
"taxYearClaimMade": "2018-19",
"claimType": "carry-forward",
"mtdLoss": false,
"taxYearLossIncurred": "2018-19",
"lossAmountUsed": 1000,
"remainingLossValue": 1000
}
],
"defaultCarriedForwardLosses": [
{
"taxYearLossIncurred": "2018-19",
"currentLossValue": 1000
}
]
}
},
"ukPropertyNonFhl": {
"totalIncome": 1000.12,
"totalExpenses": 1000.12,
"netProfit": 1000.12,
"netLoss": 1000.12,
"totalAdditions": 1000.12,
"totalDeductions": 1000.12,
"accountingAdjustments": -1000.12,
"adjustedIncomeTaxLoss": 1000,
"taxableProfit": 1000,
"taxableProfitAfterIncomeTaxLossesDeduction": 1000,
"lossClaimsSummary": {
"totalBroughtForwardIncomeTaxLosses": 1000,
"broughtForwardIncomeTaxLossesUsed": 1000,
"totalIncomeTaxLossesCarriedForward": 1000
},
"lossClaimsDetail": {
"lossesBroughtForward": [
{
"taxYearLossIncurred": "2018-19",
"currentLossValue": 1000,
"mtdLoss": false
}
],
"resultOfClaimsApplied": [
{
"claimId": "XGIS00000001319",
"originatingClaimId": "XGIS00000001319",
"taxYearClaimMade": "2018-19",
"claimType": "carry-forward",
"mtdLoss": false,
"taxYearLossIncurred": "2018-19",
"lossAmountUsed": 1000,
"remainingLossValue": 1000
}
],
"defaultCarriedForwardLosses": [
{
"taxYearLossIncurred": "2018-19",
"currentLossValue": 1000
}
],
"claimsNotApplied": [
{
"claimId": "XGIS00000001319",
"taxYearClaimMade": "2018-19",
"claimType": "carry-sideways"
}
]
}
}
}
},
"savingsAndGains": {
"incomeReceived": 1000,
"taxableIncome": 1000,
"savings": [
{
"savingsAccountId": "SAVKB2UVwUTBQGJ",
"savingsAccountName": "friendly name",
"grossIncome": 1000.12,
"netIncome": 1000.12,
"taxDeducted": 1000.12
}
]
},
"dividends": {
"incomeReceived": 1000,
"taxableIncome": 1000
}
}
}
| Name | Description |
|---|---|
|
summary
object
required
|
Details the high-level taxable income for the calculation. |
|
totalIncomeReceivedFromAllSources
number
required
|
The total income received from all income sources. This value must be between 0 and 99999999999. No decimals.
For example: |
|
totalTaxableIncome
number
required
|
The total income that is taxable across all income sources after allowances and deductions have been applied. This value must be between 0 and 99999999999. No decimals.
For example: |
|
detail
object
required
|
Details the low-level taxable income for the calculation. |
|
payPensionsProfit
object
optional
|
Details the low-level pay, pensions and profit taxable income. |
|
incomeReceived
number
required
|
The income received across all pay, pensions and profit sources. This value must be between 0 and 99999999999. No decimals.
For example: |
|
taxableIncome
number
required
|
The taxable income across all pay, pensions and profit sources after allowances and deductions have been applied. This value must be between 0 and 99999999999. No decimals.
For example: |
|
totalSelfEmploymentProfit
number
optional
|
The total self-employment profit for all self-employment businesses. This value must be between 0 and 99999999999. No decimals.
For example: |
|
totalPropertyProfit
number
optional
|
The total property profit. This value must be between 0 and 99999999999. No decimals.
For example: |
|
totalFHLPropertyProfit
number
optional
|
The total FHL profit. This value must be between 0 and 99999999999. No decimals.
For example: |
|
totalUKOtherPropertyProfit
number
optional
|
The total UK Property Non-FHL profit. This value must be between 0 and 99999999999. No decimals.
For example: |
|
businessProfitAndLoss
object
optional
|
Details the low-level profit and loss position for business income sources. |
|
selfEmployments
array
optional
|
A list that shows the low-level profit and loss position for each self-employment business |
|
selfEmploymentId
string
required
|
An identifier for the self-employment business, unique to the customer.
Must conform to the regular expression
For example: |
|
totalIncome
number
optional
|
The total income for the self-employment business. This value must be between 0 and 99999999999.99 up to 2 decimal places.
For example: |
|
totalExpenses
number
optional
|
The total expenses for the self-employment business. This value must be between 0 and 99999999999.99 up to 2 decimal places.
For example: |
|
netProfit
number
optional
|
If the total income is greater than the total expenses the result will be displayed in this field. This value must be between 0 and 99999999999.99 up to 2 decimal places.
For example: |
|
netLoss
number
optional
|
If the total income is less than the total expenses the result will be displayed in this field. This value must be between 0 and 99999999999.99 up to 2 decimal places.
For example: |
|
class4Loss
number
optional
|
The class 4 loss for the tax year of the calculation. This value must be between 0 and 99999999999. No decimals.
For example: |
|
totalAdditions
number
optional
|
The total additions for the self-employment business. The additions relate to the additions mentioned in the Business Income Source Summary. This value must be between 0 and 99999999999.99 up to 2 decimal places.
For example: |
|
totalDeductions
number
optional
|
The total deductions for the self-employment business. The deductions relate to the deductions mentioned in the Business Income Source Summary. This value must be between 0 and 99999999999.99 up to 2 decimal places.
For example: |
|
accountingAdjustments
number
optional
|
The accounting adjustments for the self-employment business. The accounting adjustments relate to the accounting adjustments mentioned in the Business Income Source Summary. This value must be between -999999999999.99 and 999999999999.99 up to 2 decimal places.
For example: |
|
adjustedIncomeTaxLoss
number
optional
|
The adjusted Income Tax loss for the self-employment business after all additions and deductions have been applied. This value must be between 0 and 99999999999. No decimals.
For example: |
|
taxableProfit
number
optional
|
The taxable profit for the self-employment business after all additions and deductions have been applied. This value must be between 0 and 99999999999. No decimals.
For example: |
|
taxableProfitAfterIncomeTaxLossesDeduction
number
optional
|
The taxable profit after income tax losses have been deducted. This value must be between 0 and 99999999999. No decimals.
For example: |
|
lossClaimsSummary
object
optional
|
Details high-level loss brought forward amounts and claims that were or were not applied in the calculation for the self-employment business. This section will only be present for a crystallisation calculation |
|
totalBroughtForwardIncomeTaxLosses
number
optional
|
The total brought forward Income Tax losses for the self-employment business. It is the sum of the current loss value for each Income Tax loss in the losses brought forward array. This value must be between 0 and 99999999999. No decimals.
For example: |
|
broughtForwardIncomeTaxLossesUsed
number
optional
|
The brought forward Income Tax losses from previous tax years that have been used against the self-employment business profit for the tax year of the calculation. This value must be between 0 and 99999999999. No decimals.
For example: |
|
totalIncomeTaxLossesCarriedForward
number
optional
|
The total Income Tax losses carried forward where a carry-forward claim has been made for the tax year of the calculation and/or the total losses brought forward from previous years that cannot be fully used against profits for the tax year of the calculation. This value must be between 0 and 99999999999. No decimals.
For example: |
|
totalBroughtForwardClass4Losses
number
optional
|
The total brought forward Class 4 National Insurance contribution losses for the self-employment business. It is the sum of the current loss value for each Class 4 loss in the losses brought forward array. This value must be between 0 and 99999999999. No decimals.
For example: |
|
broughtForwardClass4LossesUsed
number
optional
|
The brought forward Class 4 National Insurance contribution losses from previous tax years that have been used against the Class 4 National Insurance contributions for the tax year of the calculation. This value must be between 0 and 99999999999. No decimals.
For example: |
|
carrySidewaysClass4LossesUsed
number
optional
|
The Class 4 National Insurance losses carried sideways that have been used in this calculation. This value must be between 0 and 99999999999. No decimals.
For example: |
|
totalClass4LossesCarriedForward
number
optional
|
The total Class 4 losses carried forward where a carry-forward claim has been made for the tax year of the calculation and/or the total Class 4 losses brought forward from previous years that cannot be fully used against the National Insurance contributions for the tax year of the calculation. This value must be between 0 and 99999999999. No decimals.
For example: |
|
lossClaimsDetail
object
optional
|
Details low-level loss brought forward amounts and claims that were or were not applied in the calculation for the self-employment business. This section will only be present for a crystallisation calculation |
|
lossesBroughtForward
array
optional
|
A list of losses brought forward into this calculation for the self-employment business. |
|
lossType
string
required
|
The type of loss brought forward. Limited to the following possible values: income
class4-nics
|
|
taxYearLossIncurred
string
required
|
The tax year in which the loss was first incurred. Format: YYYY-YY
For example: |
|
currentLossValue
number
required
|
The current loss value. This value must be between 0 and 99999999999. No decimals.
For example: |
|
mtdLoss
boolean
required
|
Indicates the loss was registered by the taxpayer on joining MTD.
For example: |
|
resultOfClaimsApplied
array
optional
|
A list of loss claims factored into this calculation for the self-employment business. |
|
claimId
string
optional
|
The ID of the loss claim.
Must conform to the regular expression
For example: |
|
taxYearClaimMade
string
required
|
The tax year in which the loss claim was first made. Format: YYYY-YY
For example: |
|
claimType
string
required
|
The type of loss claim that was made. Limited to the following possible values: carry-forward
carry-sideways
|
|
mtdLoss
boolean
required
|
Indicates whether the loss was registered by the taxpayer on joining MTD.
For example: |
|
taxYearLossIncurred
string
required
|
The tax year in which the loss was first incurred. Format: YYYY-YY
For example: |
|
lossAmountUsed
number
required
|
The amount of loss used in the tax year of the calculation. This value must be between 0 and 99999999999. No decimals.
For example: |
|
remainingLossValue
number
required
|
The amount of loss remaining that could be not be used in the tax year of the calculation. This value must be between 0 and 99999999999. No decimals.
For example: |
|
lossType
string
required
|
The type of loss. Limited to the following possible values: income
class4-nics
|
|
unclaimedLosses
array
optional
|
An array of losses that have arisen out of this calculation for the self-employment business and available to claim in the next calculation where a 'default' carry forward claim could not be applied. |
|
taxYearLossIncurred
string
required
|
The tax year in which the loss was initially incurred. Format: YYYY-YY
For example: |
|
currentLossValue
number
required
|
The current loss value. This value must be between 0 and 99999999999. No decimals.
For example: |
|
expires
string
required
|
The tax year in which the loss expires. Format: YYYY-YY
For example: |
|
lossType
string
required
|
The type of loss. Limited to the following possible values: income
class4-nics
|
|
carriedForwardLosses
array
optional
|
Losses arising in this calculation for the self-employment business carried forward to the next calculation where a claim has been made. |
|
claimId
string
optional
|
The unique ID of the claim made by the taxpayer.
Must conform to the regular expression
For example: |
|
claimType
string
required
|
The type of claim that was made. Limited to the following possible values: carry-forward
|
|
taxYearClaimMade
string
optional
|
The tax year in which the claim was made. Format: YYYY-YY
For example: |
|
taxYearLossIncurred
string
required
|
The tax year in which the loss was initially incurred Format: YYYY-YY
For example: |
|
currentLossValue
number
required
|
The current loss value. This value must be between 0 and 99999999999. No decimals.
For example: |
|
lossType
string
required
|
The type of loss brought forward. Limited to the following possible values: income
class4-nics
|
|
claimsNotApplied
array
optional
|
A list of loss claims that could not be applied in this calculation for the self-employment business |
|
claimId
string
required
|
The ID of the claim made by the taxpayer.
Must conform to the regular expression
For example: |
|
taxYearClaimMade
string
required
|
The tax year in which the claim was initially made. Format: YYYY-YY
For example: |
|
claimType
string
required
|
The type of claim that was made. Limited to the following possible values: carry-sideways
carry-forward
|
|
ukPropertyFhl
object
optional
|
Details the low-level profit and loss position for UK Property FHL. |
|
totalIncome
number
optional
|
The total income for UK Property FHL. The value must be between 0 and 999999999999.99 up to 2 decimal places.
For example: |
|
totalExpenses
number
optional
|
The total expenses for UK Property FHL. The value must be between 0 and 999999999999.99 up to 2 decimal places.
For example: |
|
netProfit
number
optional
|
If the total income is greater than the total expenses then the result will be displayed in this field. The value must be between 0 and 999999999999.99 up to 2 decimal places.
For example: |
|
netLoss
number
optional
|
If the total income is less than the total expenses than the result will be displayed in this field. The value must be between 0 and 999999999999.99 up to 2 decimal places.
For example: |
|
totalAdditions
number
optional
|
The total additions for UK Property FHL. The additions relate to the additions mentioned in the Business Income Source Summary. The value must be between 0 and 999999999999.99 up to 2 decimal places.
For example: |
|
totalDeductions
number
optional
|
The total deductions for UK Property FHL. The deductions relate to the deductions mentioned in the Business Income Source Summary. The value must be between 0 and 999999999999.99 up to 2 decimal places.
For example: |
|
accountingAdjustments
number
optional
|
The accounting adjustments for UK Property FHL. The accounting adjustments relate to the accounting adjustments mentioned in the Business Income Source Summary. This value must be between -999999999999.99 and 999999999999.99 up to 2 decimal places.
For example: |
|
adjustedIncomeTaxLoss
number
optional
|
The adjusted Income Tax loss for UK Property FHL after all additions and deductions have been applied. This value must be between 0 and 99999999999. No decimals.
For example: |
|
taxableProfit
number
optional
|
The taxable profit for UK Property FHL after all additions and deductions have been applied. This value must be between 0 and 99999999999. No decimals.
For example: |
|
taxableProfitAfterIncomeTaxLossesDeduction
number
optional
|
The taxable profit after income tax losses have been deducted. This value must be between 0 and 99999999999. No decimals.
For example: |
|
lossClaimsSummary
object
optional
|
Details high-level loss brought forward amounts and claims that were or were not applied in the calculation for UK Property FHL. This will only be present for a crystallisation calculation |
|
lossForCSFHL
number
optional
|
The losses from UK Property Non-FHL that have been carried sideways to UK Property FHL. This value must be between 0 and 99999999999. No decimals.
For example: |
|
totalBroughtForwardIncomeTaxLosses
number
optional
|
The total brought forward Income Tax losses for UK Property FHL. It is the sum of the current loss value for each Income Tax loss in the losses brought forward array. This value must be between 0 and 99999999999. No decimals.
For example: |
|
broughtForwardIncomeTaxLossesUsed
number
optional
|
The brought forward Income Tax losses from previous tax years that have been used against the UK Property FHL profit for the tax year of the calculation. This value must be between 0 and 99999999999. No decimals.
For example: |
|
totalIncomeTaxLossesCarriedForward
number
optional
|
The total Income Tax losses carried forward where a carry-forward claim has been made for the tax year of the calculation and/or the total losses brought forward from previous years that cannot be fully used against profits for the tax year of the calculation. This value must be between 0 and 99999999999. No decimals.
For example: |
|
lossClaimsDetail
object
optional
|
Details low-level loss brought forward amounts and claims that were or were not applied in the calculation for UK Property FHL. This section will only be present for a crystallisation calculation. |
|
lossesBroughtForward
array
optional
|
A list of losses brought forward into this calculation for UK Property FHL. |
|
taxYearLossIncurred
string
required
|
The tax year in which the loss was first incurred. Format: YYYY-YY
For example: |
|
currentLossValue
number
required
|
The current loss value. This value must be between 0 and 99999999999. No decimals.
For example: |
|
mtdLoss
boolean
required
|
Indicates the loss was registered by the taxpayer on joining MTD.
For example: |
|
resultOfClaimsApplied
array
optional
|
A list of loss claims factored into this calculation for UK Property FHL. |
|
claimId
string
optional
|
The ID of the loss claim.
Must conform to the regular expression
For example: |
|
taxYearClaimMade
string
required
|
The tax year in which the loss claim was first made. Format: YYYY-YY
For example: |
|
claimType
string
required
|
The type of claim that was made. Limited to the following possible values: carry-forward
|
|
mtdLoss
boolean
required
|
Indicates the loss was registered by the taxpayer on joining MTD.
For example: |
|
taxYearLossIncurred
string
required
|
The tax year in which the loss was first incurred. Format: YYYY-YY
For example: |
|
lossAmountUsed
number
required
|
The amount of the loss that could be used in the tax year of the calculation. This value must be between 0 and 99999999999. No decimals.
For example: |
|
remainingLossValue
number
required
|
The amount of loss remaining that could be not be used in the tax year of the calculation. This value must be between 0 and 99999999999. No decimals.
For example: |
|
defaultCarriedForwardLosses
array
optional
|
A list of losses arising in this calculation that have been carried forward to the next calculation by default for UK Property FHL. |
|
taxYearLossIncurred
string
required
|
The tax year in which the loss was first incurred. Format: YYYY-YY
For example: |
|
currentLossValue
number
required
|
The current loss value. This value must be between 0 and 99999999999. No decimals.
For example: |
|
ukPropertyNonFhl
object
optional
|
Details the low-level profit and loss position for UK Property Non-FHL |
|
totalIncome
number
optional
|
The total income for UK Property Non-FHL. The value must be between 0 and 999999999999.99 up to 2 decimal places.
For example: |
|
totalExpenses
number
optional
|
The total expenses for UK property Non-FHL. The value must be between 0 and 999999999999.99 up to 2 decimal places.
For example: |
|
netProfit
number
optional
|
If the total income is greater than the total expenses then the result will be displayed in this field. The value must be between 0 and 999999999999.99 up to 2 decimal places.
For example: |
|
netLoss
number
optional
|
If the total income is less than the total expenses the result will be displayed in this field. The value must be between 0 and 999999999999.99 up to 2 decimal places.
For example: |
|
totalAdditions
number
optional
|
The total additions for UK Property Non-FHL. The additions relate to the additions mentioned in the Business Income Source Summary. The value must be between 0 and 999999999999.99 up to 2 decimal places.
For example: |
|
totalDeductions
number
optional
|
The total deductions for UK Property Non-FHL. The deductions relate to the deductions mentioned in the Business Income Source Summary. The value must be between 0 and 999999999999.99 up to 2 decimal places.
For example: |
|
accountingAdjustments
number
optional
|
The accounting adjustments for UK Property Non-FHL. The accounting adjustments relate to the accounting adjustments mentioned in the Business Income Source Summary. This value must be between -999999999999.99 and 999999999999.99 up to 2 decimal places.
For example: |
|
adjustedIncomeTaxLoss
number
optional
|
The adjusted Income Tax loss for the UK Property Non-FHL after all additions and deductions have been applied. This value must be between 0 and 99999999999. No decimals.
For example: |
|
taxableProfit
number
optional
|
The taxable profit for UK Property Non-FHL after all additions and deductions have been applied. This value must be between 0 and 99999999999. No decimals.
For example: |
|
taxableProfitAfterIncomeTaxLossesDeduction
number
optional
|
The taxable profit after any carry sideways or brought forward losses have been deducted. This value must be between 0 and 99999999999. No decimals.
For example: |
|
lossClaimsSummary
object
optional
|
Details high-level loss brought forward amounts and claims that were or were not applied in the calculation for UK Property Non-FHL. This will only be present for a crystallisation calculation. |
|
totalBroughtForwardIncomeTaxLosses
number
optional
|
The total brought forward Income Tax losses for UK Property Non-FHL. It is the sum of the current loss value for each Income Tax loss in the losses brought forward array. This value must be between 0 and 99999999999. No decimals.
For example: |
|
broughtForwardIncomeTaxLossesUsed
number
optional
|
The brought forward Income Tax losses from previous tax years that have been used against the UK Property Non-FHL profit for the tax year of the calculation. This value must be between 0 and 99999999999. No decimals.
For example: |
|
totalIncomeTaxLossesCarriedForward
number
optional
|
The total Income Tax losses carried forward where a carry-forward claim has been made for the tax year of the calculation and/or the total losses brought forward from previous years that cannot be fully used against profits for the tax year of the calculation. This value must be between 0 and 99999999999. No decimals.
For example: |
|
lossClaimsDetail
object
optional
|
Details low-level loss brought forward amounts and claims that were or were not applied in the calculation for UK Property Non-FHL. This section will only be present for a crystallisation calculation |
|
lossesBroughtForward
array
optional
|
A list of losses brought forward into this calculation for the UK Property Non-FHL business. |
|
taxYearLossIncurred
string
required
|
The tax year in which the loss was first incurred. Format: YYYY-YY
For example: |
|
currentLossValue
number
required
|
The current loss value. This value must be between 0 and 99999999999. No decimals.
For example: |
|
mtdLoss
boolean
required
|
Indicates the loss was registered by the taxpayer on joining MTD.
For example: |
|
resultOfClaimsApplied
array
optional
|
A list of loss claims factored into this calculation for UK Property Non-FHL |
|
claimId
string
optional
|
The ID of the loss claim.
Must conform to the regular expression
For example: |
|
originatingClaimId
string
optional
|
The ID of an original carry-sideways-fhl/carry-sideways claim where not all of the loss in the calculation year could be carried sideways and the resulting loss balance was carried forwards. Where a resulting carry sideways loss balance is carried forwards there will not be a new claim ID for the carried forward portion of the loss.
Must conform to the regular expression
For example: |
|
taxYearClaimMade
string
required
|
The tax year in which the loss claim was first made. Format: YYYY-YY
For example: |
|
claimType
string
required
|
The type of claim that was made. Limited to the following possible values: carry-forward
carry-sideways
carry-forward-to-carry-sideways
carry-sideways-fhl
|
|
mtdLoss
boolean
required
|
Indicates the loss was registered by the taxpayer on joining MTD.
For example: |
|
taxYearLossIncurred
string
optional
|
The tax year in which the loss was first incurred. Format: YYYY-YY
For example: |
|
lossAmountUsed
number
required
|
The amount of the loss that could be used in the tax year of the calculation. This value must be between 0 and 99999999999. No decimals.
For example: |
|
remainingLossValue
number
required
|
The amount of loss remaining that could be not be used in the tax year of the calculation. This value must be between 0 and 99999999999. No decimals.
For example: |
|
defaultCarriedForwardLosses
array
optional
|
A list of losses arising in this calculation that have been carried forward to the next calculation by default for UK Property Non-FHL. |
|
taxYearLossIncurred
string
required
|
The tax year in which the loss was first incurred. Format: YYYY-YY
For example: |
|
currentLossValue
number
required
|
The current loss value. This value must be between 0 and 99999999999. No decimals.
For example: |
|
claimsNotApplied
array
optional
|
A list of loss claims that could not be applied in this calculation for UK Property Non-FHL. |
|
claimId
string
required
|
The ID of the claim made by the taxpayer.
Must conform to the regular expression
For example: |
|
taxYearClaimMade
string
required
|
The tax year in which the claim was initially made. Format: YYYY-YY
For example: |
|
claimType
string
required
|
The type of claim that was made. Limited to the following possible values: carry-sideways
carry-forward-to-carry-sideways
|
|
savingsAndGains
object
optional
|
Details the low-level savings and gains taxable income |
|
incomeReceived
number
required
|
The savings and gains income received. This value must be between 0 and 99999999999. No decimals.
For example: |
|
taxableIncome
number
required
|
The savings and gains taxable income. This value must be between 0 and 99999999999. No decimals.
For example: |
|
savings
array
optional
|
A list of the savings income for each savings account. |
|
savingsAccountId
string
required
|
The unique identifier of the savings account.
Must conform to the regular expression
For example: |
|
savingsAccountName
string
required
|
Friendly account name. Each account name will be unique for that National Insurance number. The account name will be between 1 and 32 characters in length. Allowed characters, including spaces are: mixed case alphanumeric characters and the characters; &'()*,-./@£.
Must conform to the regular expression
For example: |
|
grossIncome
number
required
|
The gross interest for the savings account. The value must be between 0 and 999999999999.99 up to 2 decimal places.
For example: |
|
netIncome
number
optional
|
The net interest for the savings account. The value must be between 0 and 999999999999.99 up to 2 decimal places.
For example: |
|
taxDeducted
number
optional
|
The tax deducted from the savings account (gross minus net). The value must be between 0 and 999999999999.99 up to 2 decimal places.
For example: |
|
dividends
object
optional
|
Details the dividends taxable income. |
|
incomeReceived
number
required
|
The dividends income received. This value must be between 0 and 99999999999. No decimals.
For example: |
|
taxableIncome
number
required
|
The dividends taxable income. This value must be between 0 and 99999999999. No decimals.
For example: |
Error scenarios
| Scenario | HTTP status | Code |
|---|---|---|
|
The format of the supplied NINO is not valid |
400 (Bad Request) |
FORMAT_NINO |
|
The format of the supplied Calculation ID is not valid |
400 (Bad Request) |
FORMAT_CALC_ID |
|
The client and/or agent is not authorised. This is normally because: the client is not subscribed to MTD, the agent is not subscribed to Agent Services, or the client has not authorised the agent to act on their behalf. |
403 (Forbidden) |
CLIENT_OR_AGENT_NOT_AUTHORISED |
|
No Income Tax and National Insurance Contributions data exists for the supplied calculation ID and NINO because error messages were generated while performing the calculation. These error messages can be viewed using the "Retrieve self assessment tax calculation messages" endpoint. |
403 (Forbidden) |
RULE_CALCULATION_ERROR_MESSAGES_EXIST |
|
No tax calculation data exists for the supplied NINO and calculation ID. |
404 (Not Found) |
MATCHING_RESOURCE_NOT_FOUND |
For error scenarios that are common across all APIs, and for error formats, see our reference guide.
Test data
Scenario simulations using Gov-Test-Scenario headers is only available in the sandbox environment.
| Header Value (Gov-Test-Scenario) | Scenario |
|---|---|
N/A - DEFAULT |
Simulates returning a tax calculation with all fields. |
ERROR_MESSAGES_EXIST |
Simulates the scenario where errors exist and no calculation has been generated. |
NOT_FOUND |
Simulates the scenario where no data can be found. |
UK_MULTIPLE_INCOMES_EXAMPLE |
Simulates an example tax calculation with realistic data values, for a UK FHL Property business with Savings and Dividends. |
UK_PROP_DIVIDENDS_EXAMPLE |
Simulates an example tax calculation with realistic data values, for a UK Non-FHL Property business with Dividends. |
UK_PROP_GIFTAID_EXAMPLE |
Simulates an example tax calculation with realistic data values, for a UK Non-FHL Property business with Gift Aid. |
UK_PROP_SAVINGS_EXAMPLE |
Simulates an example tax calculation with realistic data values, for a UK Non-FHL Property business with Savings. |
UK_SE_GIFTAID_EXAMPLE |
Simulates an example tax calculation with realistic data values, for a UK Self-Employment business with Gift Aid. |
UK_SE_SAVINGS_EXAMPLE |
Simulates an example tax calculation with realistic data values, for a UK Self-Employment business with Savings. |
SCOT_SE_DIVIDENDS_EXAMPLE |
Simulates an example tax calculation with realistic data values, for a Scottish Self-Employment business with Dividends. |
/individuals/calculations/{nino}/self-assessment/{calculationId}/allowances-deductions-reliefs
This endpoint allows you to retrieve the allowances, deductions and reliefs that have been used in the self assessment tax calculation for a given NINO and Calculation ID.
An error will occur if your calculation has one or more error messages. You can use the Retrieve Self Assessment Tax Calculation Messages endpoint to retrieve these messages.
Authorisation
This endpoint is
user-restricted
- it requires an Authorization header containing an OAuth 2.0 Bearer Token with the read:self-assessment scope.
Path parameters
| Name | Description |
|---|---|
|
nino
string
required
|
National Insurance number, in the format AA999999A.
For example: |
|
calculationId
string
required
|
The unique identifier of the calculation. Must conform the regular expression:
For example: |
Request headers
| Name | Description |
|---|---|
|
Accept
required
|
Specifies the response format and the version of the API to be used. For example: application/vnd.hmrc.1.0+json
|
|
Gov-Test-Scenario
optional
|
Only in sandbox environment. See Test Data table for all header values. For example: -
|
|
Authorization
required
|
An
OAuth 2.0 Bearer Token
with the read:self-assessment scope.
For example: Bearer bb7fed3fe10dd235a2ccda3d50fb
|
See also fraud prevention for other request headers which will become mandatory.
Response headers
| Name | Description |
|---|---|
|
X-CorrelationId
required
|
Unique ID for operation tracking For example: c75f40a6-a3df-4429-a697-471eeec46435
|
See also fraud prevention for other request headers which will become mandatory.
Response
HTTP status: 200 (OK)
{
"summary": {
"totalAllowancesAndDeductions": 1000,
"totalReliefs": 1000
},
"detail": {
"allowancesAndDeductions": {
"personalAllowance": 1000,
"reducedPersonalAllowance": 1000,
"giftOfInvestmentsAndPropertyToCharity": 1000,
"blindPersonsAllowance": 1000,
"lossesAppliedToGeneralIncome": 1000
},
"reliefs": {
"residentialFinanceCosts": {
"amountClaimed": 1000,
"allowableAmount": 1000,
"rate": 10.25,
"propertyFinanceRelief": 1000
}
}
}
}
| Name | Description |
|---|---|
|
summary
object
required
|
Details the high-level allowances, deductions and reliefs for the calculation. |
|
totalAllowancesAndDeductions
number
optional
|
The total allowances and deductions available to the calculation. This value must be between 0 and 99999999999. No decimals.
For example: |
|
totalReliefs
number
optional
|
The total reliefs available to the calculation. This value must be between 0 and 99999999999. No decimals.
For example: |
|
detail
object
required
|
Details the low-level allowances, deductions and reliefs for the calculation. |
|
allowancesAndDeductions
object
optional
|
Details the low-level allowances and deductions for the calculation. |
|
personalAllowance
number
optional
|
The annual amount of personal allowance available for the tax year. This value must be between 0 and 99999999999. No decimals.
For example: |
|
reducedPersonalAllowance
number
optional
|
The annual amount that the personal allowance has been reduced to. This value must be between 0 and 99999999999. No decimals.
For example: |
|
giftOfInvestmentsAndPropertyToCharity
number
optional
|
Investments and/or property gifts made to charity. This value must be between 0 and 99999999999. No decimals.
For example: |
|
blindPersonsAllowance
number
optional
|
Blind persons allowance. This value must be between 0 and 99999999999. No decimals.
For example: |
|
lossesAppliedToGeneralIncome
number
optional
|
Losses that have been applied to general income. This value must be between 0 and 99999999999. No decimals.
For example: |
|
reliefs
object
optional
|
Details the low-level reliefs for the calculation. |
|
residentialFinanceCosts
object
optional
|
Details the residential finance cost reliefs for the calculation. |
|
amountClaimed
number
required
|
The amount being claimed including any carry forward amounts. This value must be between 0 and 99999999999. No decimals.
For example: |
|
allowableAmount
number
optional
|
The lower of: finance costs not deducted, property business profits, adjusted total income (exceeding Personal Allowance). This value must be between 0 and 99999999999. No decimals.
For example: |
|
rate
number
required
|
The tax rate used for the calculation. The value must be between 0 and 99.99 up to 2 decimal places.
For example: |
|
propertyFinanceRelief
number
required
|
Property finance relief. This value must be between 0 and 99999999999. No decimals.
For example: |
Error scenarios
| Scenario | HTTP status | Code |
|---|---|---|
|
The format of the supplied NINO is not valid |
400 (Bad Request) |
FORMAT_NINO |
|
The format of the supplied Calculation ID is not valid |
400 (Bad Request) |
FORMAT_CALC_ID |
|
The client and/or agent is not authorised. This is normally because: the client is not subscribed to MTD, the agent is not subscribed to Agent Services, or the client has not authorised the agent to act on their behalf. |
403 (Forbidden) |
CLIENT_OR_AGENT_NOT_AUTHORISED |
|
No Income Tax and National Insurance Contributions data exists for the supplied calculation ID and NINO because error messages were generated while performing the calculation. These error messages can be viewed using the "Retrieve self assessment tax calculation messages" endpoint. |
403 (Forbidden) |
RULE_CALCULATION_ERROR_MESSAGES_EXIST |
|
No allowances, deductions and reliefs data exists for the supplied calculation ID and NINO. |
404 (Not Found) |
NO_ALLOWANCES_DEDUCTIONS_RELIEFS_EXIST |
|
No tax calculation data exists for the supplied NINO and calculation ID. |
404 (Not Found) |
MATCHING_RESOURCE_NOT_FOUND |
For error scenarios that are common across all APIs, and for error formats, see our reference guide.
Test data
Scenario simulations using Gov-Test-Scenario headers is only available in the sandbox environment.
| Header Value (Gov-Test-Scenario) | Scenario |
|---|---|
N/A - DEFAULT |
Simulates returning a tax calculation with all fields. |
ERROR_MESSAGES_EXIST |
Simulates the scenario where errors exist and no calculation has been generated. |
NO_ALLOWANCES_DEDUCTIONS_RELIEFS_EXIST |
Simulates the scenario where no allowances, deductions and reliefs data exists. |
NOT_FOUND |
Simulates the scenario where no data can be found. |
UK_MULTIPLE_INCOMES_EXAMPLE |
Simulates an example tax calculation with realistic data values, for a UK FHL Property business with Savings and Dividends. |
UK_PROP_DIVIDENDS_EXAMPLE |
Simulates an example tax calculation with realistic data values, for a UK Non-FHL Property business with Dividends. |
UK_PROP_GIFTAID_EXAMPLE |
Simulates an example tax calculation with realistic data values, for a UK Non-FHL Property business with Gift Aid. |
UK_PROP_SAVINGS_EXAMPLE |
Simulates an example tax calculation with realistic data values, for a UK Non-FHL Property business with Savings. |
UK_SE_SAVINGS_EXAMPLE |
Simulates an example tax calculation with realistic data values, for a UK Self-Employment business with Savings. |
SCOT_SE_DIVIDENDS_EXAMPLE |
Simulates an example tax calculation with realistic data values, for a Scottish Self-Employment business with Dividends. |
/individuals/calculations/{nino}/self-assessment/{calculationId}/end-of-year-estimate
This endpoint allows you to retrieve the end of year Income Tax and National Insurance contribution estimates for a given NINO and Calculation ID. Only applicable for an In-year calculation.
An error will occur if your calculation has one or more error messages. You can use the Retrieve Self Assessment Tax Calculation Messages endpoint to retrieve these messages.
Authorisation
This endpoint is
user-restricted
- it requires an Authorization header containing an OAuth 2.0 Bearer Token with the read:self-assessment scope.
Path parameters
| Name | Description |
|---|---|
|
nino
string
required
|
National Insurance number, in the format AA999999A.
For example: |
|
calculationId
string
required
|
The unique identifier of the calculation. Must conform the regular expression:
For example: |
Request headers
| Name | Description |
|---|---|
|
Accept
required
|
Specifies the response format and the version of the API to be used. For example: application/vnd.hmrc.1.0+json
|
|
Gov-Test-Scenario
optional
|
Only in sandbox environment. See Test Data table for all header values. For example: -
|
|
Authorization
required
|
An
OAuth 2.0 Bearer Token
with the read:self-assessment scope.
For example: Bearer bb7fed3fe10dd235a2ccda3d50fb
|
See also fraud prevention for other request headers which will become mandatory.
Response headers
| Name | Description |
|---|---|
|
X-CorrelationId
required
|
Unique ID for operation tracking For example: c75f40a6-a3df-4429-a697-471eeec46435
|
See also fraud prevention for other request headers which will become mandatory.
Response
HTTP status: 200 (OK)
{
"summary": {
"totalEstimatedIncome": 20000,
"totalTaxableIncome": 12000,
"incomeTaxAmount": 99999999.99,
"nic2": 2000.33,
"nic4": 2000.33,
"totalNicAmount": 4000.66,
"incomeTaxNicAmount": 6000.83
},
"detail": {
"selfEmployments": [
{
"selfEmploymentId": "XKIS00000000988",
"taxableIncome": 99999999,
"finalised": true
}
],
"ukPropertyFhl": {
"taxableIncome": 99999999,
"finalised": true
},
"ukPropertyNonFhl": {
"taxableIncome": 99999999,
"finalised": true
},
"ukSavings": [
{
"savingsAccountId": "SAVKB2UVwUTBQGJ",
"savingsAccountName": "UK Prime Bank Account 1",
"taxableIncome": 1000
}
],
"ukDividends": {
"taxableIncome": 99999999
}
}
}
| Name | Description |
|---|---|
|
summary
object
optional
|
Details the high-level Income Tax and National Insurance Contributions due |
|
totalEstimatedIncome
number
optional
|
The total estimated end of year income. This value must be between 0 and 99999999999.
For example: |
|
totalTaxableIncome
number
optional
|
The total taxable end of year income. This value must be between 0 and 99999999999. No Decimals.
For example: |
|
incomeTaxAmount
number
optional
|
The estimated end of year Income Tax amount. This value must be between 0 and 99999999999.99 up to 2 decimal places.
For example: |
|
nic2
number
optional
|
The estimated end of year Class 2 National Insurance contributions amount. This value must be between 0 and 99999999999.99 up to 2 decimal places.
For example: |
|
nic4
number
optional
|
The estimated end of year Class 4 National Insurance contributions amount. This value must be between 0 and 99999999999.99 up to 2 decimal places.
For example: |
|
totalNicAmount
number
optional
|
The estimated end of year combined Class 2 and Class 4 National Insurance contributions amount. This value must be between 0 and 99999999999.99 up to 2 decimal places.
For example: |
|
incomeTaxNicAmount
number
optional
|
The estimated end of year combined Class 2 and Class 4 National Insurance contributions amount. This value must be between 0 and 99999999999.99 up to 2 decimal places.
For example: |
|
detail
object
optional
|
Details the low-level taxable income amounts of each income source |
|
selfEmployments
array
optional
|
A list of self-employment business detailing the taxable income estimate for each business |
|
selfEmploymentId
string
required
|
An identifier for the self-employment business, unique to the customer.
Must conform to the regular expression
For example: |
|
taxableIncome
number
required
|
The estimated end of year income. This value must be between 0 and 99999999999. No decimals.
For example: |
|
finalised
boolean
optional
|
Shows whether the self-employment income has been finalised.
For example: |
|
ukPropertyFhl
object
optional
|
Details the taxable income estimate for UK Property FHL |
|
taxableIncome
number
required
|
The estimated end of year income. This value must be between 0 and 99999999999. No decimals.
For example: |
|
finalised
boolean
optional
|
Shows whether the UK Property FHL income has been finalised.
For example: |
|
ukPropertyNonFhl
object
optional
|
Details the taxable income estimate for UK Property Non-FHL |
|
taxableIncome
number
required
|
The estimated end of year taxable income. This value must be between 0 and 99999999999. No decimals.
For example: |
|
finalised
boolean
optional
|
Shows whether the UK Property Non-FHL income has been finalised.
For example: |
|
ukSavings
array
optional
|
Details the taxable income estimate for UK savings |
|
savingsAccountId
string
required
|
The unique identifier of the savings account.
Must conform to the regular expression
For example: |
|
savingsAccountName
string
required
|
Friendly account name. Each account name will be unique for that National Insurance number. The account name will be between 1 and 32 characters in length. Allowed characters, including spaces are: mixed case alphanumeric characters and the characters; &'()*,-./@£.
Must conform to the regular expression
For example: |
|
taxableIncome
number
required
|
The estimated end of year taxable income. This value must be between 0 and 99999999999. No decimals.
For example: |
|
ukDividends
object
optional
|
Details the taxable income estimate for UK dividends |
|
taxableIncome
number
required
|
The estimated end of year taxable income. This value must be between 0 and 99999999999. No decimals.
For example: |
Error scenarios
| Scenario | HTTP status | Code |
|---|---|---|
|
The format of the supplied NINO is not valid |
400 (Bad Request) |
FORMAT_NINO |
|
The format of the supplied Calculation ID is not valid |
400 (Bad Request) |
FORMAT_CALC_ID |
|
The client and/or agent is not authorised. This is normally because: the client is not subscribed to MTD, the agent is not subscribed to Agent Services, or the client has not authorised the agent to act on their behalf. |
403 (Forbidden) |
CLIENT_OR_AGENT_NOT_AUTHORISED |
|
No Income Tax and National Insurance Contributions data exists for the supplied calculation ID and NINO because error messages were generated while performing the calculation. These error messages can be viewed using the "Retrieve self assessment tax calculation messages" endpoint. |
403 (Forbidden) |
RULE_CALCULATION_ERROR_MESSAGES_EXIST |
|
No tax calculation data exists for the supplied NINO and calculation ID. |
404 (Not Found) |
MATCHING_RESOURCE_NOT_FOUND |
|
End of year estimate data will only be returned for an in-year calculation |
404 (Not Found) |
END_OF_YEAR_ESTIMATE_NOT_PRESENT |
For error scenarios that are common across all APIs, and for error formats, see our reference guide.
Test data
Scenario simulations using Gov-Test-Scenario headers is only available in the sandbox environment.
| Header Value (Gov-Test-Scenario) | Scenario |
|---|---|
N/A - DEFAULT |
Simulates returning a tax calculation with all fields. |
ERROR_MESSAGES_EXIST |
Simulates the scenario where errors exist and no calculation has been generated. |
NOT_FOUND |
Simulates the scenario where no data can be found. |
EOY_ESTIMATE_NOT_PRESENT |
Simulates the error returned when a tax calculation is not in year. |
UK_MULTIPLE_INCOMES_EXAMPLE |
Simulates an example tax calculation with realistic data values, for a UK FHL Property business with Savings and Dividends. |
UK_PROP_DIVIDENDS_EXAMPLE |
Simulates an example tax calculation with realistic data values, for a UK Non-FHL Property business with Dividends. |
UK_PROP_GIFTAID_EXAMPLE |
Simulates an example tax calculation with realistic data values, for a UK Non-FHL Property business with Gift Aid. |
UK_PROP_SAVINGS_EXAMPLE |
Simulates an example tax calculation with realistic data values, for a UK Non-FHL Property business with Savings. |
UK_SE_GIFTAID_EXAMPLE |
Simulates an example tax calculation with realistic data values, for a UK Self-Employment business with Gift Aid. |
UK_SE_SAVINGS_EXAMPLE |
Simulates an example tax calculation with realistic data values, for a UK Self-Employment business with Savings. |
SCOT_SE_DIVIDENDS_EXAMPLE |
Simulates an example tax calculation with realistic data values, for a Scottish Self-Employment business with Dividends. |
/individuals/calculations/{nino}/self-assessment/{calculationId}/messages
This endpoint allows you to retrieve 'info', 'warning' and 'error' level messages linked to a Calculation ID. One or more error messages for a Calculation ID means a calculation could not be performed. Vendor software should surface these messages to the end user.
Authorisation
This endpoint is
user-restricted
- it requires an Authorization header containing an OAuth 2.0 Bearer Token with the read:self-assessment scope.
Path parameters
| Name | Description |
|---|---|
|
nino
string
required
|
National Insurance number, in the format AA999999A.
For example: |
|
calculationId
string
required
|
The unique identifier of the calculation. Must conform the regular expression:
For example: |
Query parameters
| Name | Description |
|---|---|
|
type
string
optional
|
The 'type' query parameter allows the messages output to be filtered by type. The type parameter can be supplied more than once; e.g. Limited to the following possible values: infowarningerror |
Request headers
| Name | Description |
|---|---|
|
Accept
required
|
Specifies the response format and the version of the API to be used. For example: application/vnd.hmrc.1.0+json
|
|
Gov-Test-Scenario
optional
|
Only in sandbox environment. See Test Data table for all header values. For example: -
|
|
Authorization
required
|
An
OAuth 2.0 Bearer Token
with the read:self-assessment scope.
For example: Bearer bb7fed3fe10dd235a2ccda3d50fb
|
See also fraud prevention for other request headers which will become mandatory.
Response headers
| Name | Description |
|---|---|
|
X-CorrelationId
required
|
Unique ID for operation tracking For example: c75f40a6-a3df-4429-a697-471eeec46435
|
See also fraud prevention for other request headers which will become mandatory.
Response
HTTP status: 200 (OK)
{
"info": [
{
"id": "C22203",
"text": "Class 2 National Insurance has not been charged as your self-employed profits are under the small profit threshold."
},
{
"id": "C11101",
"text": "You have entered a large amount in total Gift Aid payments. Please check"
}
]
}
{
"info": [
{
"id": "C22201",
"text": "Your BRT limit has been increased by 3000 to 35000 for Gift Aid payments."
}
],
"warnings": [
{
"id": "C11317",
"text": "Class 4 exemption - calculation has been adjusted Individual’s age is equal to or greater than 16 years old on the 6th April of current tax year."
},
{
"id": "C11509",
"text": "Property Income Allowance has been claimed and therefore no further expenses can be claimed."
}
]
}
{
"warnings": [
{
"id": "C11009",
"text": "Period submissions include gaps"
},
{
"id": "C11010",
"text": "Period submissions include overlaps"
},
{
"id": "C11101",
"text": "Please check you have entered the correct amount of total gift aid payments"
}
],
"errors": [
{
"id": "C95005",
"text": "Final confirmation of income and expenses for all business sources has not been provided"
}
]
}
{
"errors": [
{
"id": "C11103",
"text": "Gift aid payments made this year treated as paid in the previous year cannot exceed the total gift aid payments. Please check."
}
]
}
| Name | Description |
|---|---|
|
info
array
optional
|
A list of info messages relating to the calculation ID. |
|
id
string
required
|
The ID of the message. |
|
text
string
required
|
The message text. |
|
warnings
array
optional
|
A list of warning messages relating to the calculation ID. |
|
id
string
required
|
The ID of the message. |
|
text
string
required
|
The message text. |
|
errors
array
optional
|
A list of error messages relating to the calculation ID. |
|
id
string
required
|
The ID of the message. |
|
text
string
required
|
The message text. |
Error scenarios
| Scenario | HTTP status | Code |
|---|---|---|
|
The format of the supplied NINO is not valid |
400 (Bad Request) |
FORMAT_NINO |
|
The format of the supplied Calculation ID is not valid |
400 (Bad Request) |
FORMAT_CALC_ID |
|
The format of the type query parameter is not valid |
400 (Bad Request) |
FORMAT_TYPE |
|
The client and/or agent is not authorised. This is normally because: the client is not subscribed to MTD, the agent is not subscribed to Agent Services, or the client has not authorised the agent to act on their behalf. |
403 (Forbidden) |
CLIENT_OR_AGENT_NOT_AUTHORISED |
|
No tax calculation data exists for the supplied NINO and calculation ID. |
404 (Not Found) |
MATCHING_RESOURCE_NOT_FOUND |
|
No messages are present for the supplied types or no messages exist for that calculation ID. |
404 (Not Found) |
NO_MESSAGES_PRESENT |
For error scenarios that are common across all APIs, and for error formats, see our reference guide.
Test data
Scenario simulations using Gov-Test-Scenario headers is only available in the sandbox environment.
| Header Value (Gov-Test-Scenario) | Scenario |
|---|---|
N/A - DEFAULT |
Simulates returning a tax calculation with info and warning messages. |
NOT_FOUND |
Simulates the scenario where no data can be found for this calculations ID. |
NO_MESSAGES_PRESENT |
Simulates the scenario where a tax calculation is found, but no messages exist. This error can also be returned by the use of filters. |
MESSAGES_INFO |
Simulates returning a tax calculation with info messages. |
MESSAGES_INFO_WARNINGS |
Simulates returning a tax calculation with info and warning messages. |
MESSAGES_WARNINGS |
Simulates returning a tax calculation with warning messages. |
MESSAGES_WARNINGS_ERRORS |
Simulates returning a tax calculation with warning and error messages. |
MESSAGES_ERRORS |
Simulates returning a tax calculation with error messages. |