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
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",
"links": [
{
"href": "/individuals/calculations/RW399019B/self-assessment/f2fb30e5-4ab6-4a29-b3c1-c7264259ff1c",
"rel": "self",
"method": "GET"
}
]
},
{
"id": "cf63c46a-1a4f-3c56-b9ea-9a82551d27bb",
"calculationTimestamp": "2019-06-17T18:45:59Z",
"type": "crystallisation",
"requestedBy": "customer",
"links": [
{
"href": "/individuals/calculations/RW399019B/self-assessment/cf63c46a-1a4f-3c56-b9ea-9a82551d27bb",
"rel": "self",
"method": "GET"
}
]
}
],
"links": [
{
"href": "/individuals/calculations/RW399019B/self-assessment",
"rel": "self",
"method": "GET"
},
{
"href": "/individuals/calculations/RW399019B/self-assessment",
"rel": "trigger",
"method": "POST"
}
]
}
| 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
|
|
links
array
optional
|
A list of endpoint links that indicate possible actions related to the current resource |
|
href
string
required
|
The relative url of the endpoint
For example: |
|
rel
string
required
|
A label for the endpoint, which describes how it is related to the current resource The rel will be self where the action is retrieval of the same resource Limited to the following possible values: self
|
|
method
string
required
|
The HTTP method type for the endpoint Limited to the following possible values: GET
|
|
links
array
optional
|
A list of endpoint links that indicate possible actions related to the current resource |
|
href
string
required
|
The relative url of the endpoint
For example: |
|
rel
string
required
|
A label for the endpoint, which describes how it is related to the current resource The rel will be self where the action is retrieval of the same resource Limited to the following possible values: self
trigger
|
|
method
string
required
|
The HTTP method type for the endpoint Limited to the following possible values: GET
POST
|
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 invalid. A tax year range of one year is required. |
400 (Bad Request) |
RULE_TAX_YEAR_RANGE_INVALID |
|
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 given tax year. It should be called whenever income data is updated through a periodic or annual endpoint. It can take up to 5 seconds for a Calculation ID to be returned when triggering a tax calculation. The result of the calculation can be seen using the “Retrieve 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",
"links": [
{
"href": "/individuals/calculations/RW399019B/self-assessment/f2fb30e5-4ab6-4a29-b3c1-c7264259ff1c",
"rel": "self",
"method": "GET"
}
]
}
| Name | Description |
|---|---|
|
id
string
required
|
The unique identifier of the calculation.
Must conform to the regular expression
For example: |
|
links
array
optional
|
A list of endpoint links that indicate possible actions related to the current resource |
|
href
string
required
|
The relative url of the endpoint
For example: |
|
rel
string
required
|
A label for the endpoint, which describes how it is related to the current resource The rel will be self where the action is retrieval of the same resource Limited to the following possible values: self
|
|
method
string
required
|
The HTTP method type for the endpoint Limited to the following possible values: GET
|
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 invalid. A tax year range of one year is required. |
400 (Bad Request) |
RULE_TAX_YEAR_RANGE_INVALID |
|
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,
"links": [
{
"href": "/individuals/calculations/RW399019B/self-assessment/f2fb30e5-4ab6-4a29-b3c1-c7264259ff1c",
"rel": "self",
"method": "GET"
},
{
"href": "/individuals/calculations/RW399019B/self-assessment/f2fb30e5-4ab6-4a29-b3c1-c7264259ff1c/income-tax-nics-calculated",
"rel": "income-tax-and-nics-calculated",
"method": "GET"
},
{
"href": "/individuals/calculations/RW399019B/self-assessment/f2fb30e5-4ab6-4a29-b3c1-c7264259ff1c/taxable-income",
"rel": "taxable-income",
"method": "GET"
},
{
"href": "/individuals/calculations/RW399019B/self-assessment/f2fb30e5-4ab6-4a29-b3c1-c7264259ff1c/allowances-deductions-reliefs",
"rel": "allowances-deductions-reliefs",
"method": "GET"
},
{
"href": "/individuals/calculations/RW399019B/self-assessment/f2fb30e5-4ab6-4a29-b3c1-c7264259ff1c/end-of-year-estimate",
"rel": "end-of-year-estimate",
"method": "GET"
},
{
"href": "/individuals/calculations/RW399019B/self-assessment/f2fb30e5-4ab6-4a29-b3c1-c7264259ff1c/messages",
"rel": "messages",
"method": "GET"
}
]
}
{
"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,
"links": [
{
"href": "/individuals/calculations/RW399019B/self-assessment/f2fb30e5-4ab6-4a29-b3c1-c7264259ff1c",
"rel": "self",
"method": "GET"
},
{
"href": "/individuals/calculations/RW399019B/self-assessment/f2fb30e5-4ab6-4a29-b3c1-c7264259ff1c/income-tax-nics-calculated",
"rel": "income-tax-and-nics-calculated",
"method": "GET"
},
{
"href": "/individuals/calculations/RW399019B/self-assessment/f2fb30e5-4ab6-4a29-b3c1-c7264259ff1c/taxable-income",
"rel": "taxable-income",
"method": "GET"
},
{
"href": "/individuals/calculations/RW399019B/self-assessment/f2fb30e5-4ab6-4a29-b3c1-c7264259ff1c/allowances-deductions-reliefs",
"rel": "allowances-deductions-reliefs",
"method": "GET"
},
{
"href": "/individuals/calculations/RW399019B/self-assessment/f2fb30e5-4ab6-4a29-b3c1-c7264259ff1c/end-of-year-estimate",
"rel": "end-of-year-estimate",
"method": "GET"
},
{
"href": "/individuals/calculations/RW399019B/self-assessment/f2fb30e5-4ab6-4a29-b3c1-c7264259ff1c/messages",
"rel": "messages",
"method": "GET"
}
]
}
{
"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,
"links": [
{
"href": "/individuals/calculations/RW399019B/self-assessment/f2fb30e5-4ab6-4a29-b3c1-c7264259ff1c",
"rel": "self",
"method": "GET"
},
{
"href": "/individuals/calculations/RW399019B/self-assessment/f2fb30e5-4ab6-4a29-b3c1-c7264259ff1c/messages",
"rel": "messages",
"method": "GET"
}
]
}
| 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: |
|
links
array
optional
|
A list of endpoint links that indicate possible actions related to the current resource |
|
href
string
required
|
The relative url of the endpoint
For example: |
|
rel
string
required
|
A label for the endpoint, which describes how it is related to the current resource The rel will be self where the action is retrieval of the same resource Limited to the following possible values: self
income-tax-and-nics-calculated
taxable-income
allowances-deductions-reliefs
end-of-year-estimate
messages
|
|
method
string
required
|
The HTTP method type for the endpoint Limited to the following possible values: GET
|
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": {
"totalIncomeChargeableToClass4": 1000,
"class4Losses": {
"totalClass4LossesAvailable": 1000,
"totalClass4LossesUsed": 1000,
"totalClass4LossesCarriedForward": 1000
},
"totalIncomeLiableToClass4Charge": 1000,
"class4NicBands": [
{
"name": "ZRT",
"rate": 10.12,
"threshold": 1000,
"apportionedThreshold": 1000,
"income": 1000,
"amount": 1000.12
}
]
}
},
"taxDeductedAtSource": {
"savings": 1000,
"ukLandAndProperty": 1000
}
},
"links": [
{
"href": "/individuals/calculations/RW399019B/self-assessment/f2fb30e5-4ab6-4a29-b3c1-c7264259ff1c/income-tax-nics-calculated",
"rel": "self",
"method": "GET"
},
{
"href": "/individuals/calculations/RW399019B/self-assessment/f2fb30e5-4ab6-4a29-b3c1-c7264259ff1c",
"rel": "metadata",
"method": "GET"
}
]
}
| Name | Description |
|---|---|
|
summary
object
required
|
Summarises the Income Tax and National Insurance Contributions due. |
|
incomeTax
object
required
|
Summarises the 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 Income Tax due on Gift Aid payments. This value must be between 0 and 99999999999.99 up to 2 decimal places.
For example: |
|
nics
object
optional
|
Summarises the 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 amount of tax deducted from all income that has had tax deducted at source (reducing your Income Tax and National Insurance contributions 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 breakdown of Income Tax and National Insurance Contributions due. |
|
incomeTax
object
required
|
Details the breakdown of Income Tax due. |
|
payPensionsProfit
object
optional
|
Details the breakdown of Income Tax due for pay, pensions and profit income |
|
allowancesAllocated
number
required
|
The allowances allocated to the 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
|
Details the relevant tax bands for the taxable income |
|
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 breakdown of Income Tax due for savings and gains. |
|
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
|
Details the relevant tax bands for the taxable income |
|
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 breakdown of Income Tax due 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
|
Details the relevant tax bands for the taxable income |
|
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 breakdown of Income Tax due for Gift Aid donations. Only visible if Income Tax is owed on Gift Aid donations. |
|
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 breakdown of National Insurance Contributions. |
|
class2Nics
object
optional
|
Details the breakdown of Class 2 National Insurance Contributions charged. |
|
weeklyRate
number
optional
|
The weekly rate used to estimate the 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 used to calculate the estimated Class 2 National Insurance contributions. This value is a whole number in the range 0 to 52.
For example: |
|
limit
number
optional
|
The annual small profits threshold limit for Class 2 National Insurance contributions. This value must be between 0 and 99999999999. No decimals.
For example: |
|
apportionedLimit
number
optional
|
The apportioned small profits threshold limit for 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 estimate in this calculation.
For example: |
|
class4Nics
object
optional
|
Details the breakdown of Class 4 National Insurance Contributions charged. |
|
totalIncomeLiableToClass4Charge
number
optional
|
Total income that is liable to Class 4 National Insurance Contributions before Class 4 National Insurance Contributions losses have been applied. This value must be between 0 and 99999999999. No decimals.
For example: |
|
class4Losses
object
optional
|
Details the Class 4 National Insurance Contribution losses in relation to the Class 4 National Insurance Contributions. |
|
totalClass4LossesAvailable
number
optional
|
Total Class 4 National Insurance Contributions losses that are available to the Class 4 National Insurance Contributions calculation. This value must be between 0 and 99999999999. No decimals.
For example: |
|
totalClass4LossesUsed
number
optional
|
Total Class 4 National Insurance Contributions losses that have been used in the Class 4 National Insurance Contributions calculation. This value must be between 0 and 99999999999. No decimals.
For example: |
|
totalClass4LossesCarriedForward
number
optional
|
Total Class 4 National Insurance Contributions losses that have not been used in the Class 4 National Insurance Contributions calculation. 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 relevant Class 4 National Insurance bands |
|
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
|
Details all types of income that have had tax deducted at source. |
|
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: |
|
links
array
optional
|
A list of endpoint links that indicate possible actions related to the current resource |
|
href
string
required
|
The relative url of the endpoint
For example: |
|
rel
string
required
|
A label for the endpoint, which describes how it is related to the current resource The rel will be self where the action is retrieval of the same resource Limited to the following possible values: self
metadata
|
|
method
string
required
|
The HTTP method type for the endpoint Limited to the following possible values: GET
|
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,
"totalAdditions": 1000.12,
"totalDeductions": 1000.12,
"accountingAdjustments": 1000.12,
"taxableProfit": 1000,
"adjustedIncomeTaxLoss": 1000,
"class4Loss": 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,
"taxableProfit": 1000,
"adjustedIncomeTaxLoss": 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,
"taxableProfit": 1000,
"adjustedIncomeTaxLoss": 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,
"ukSavings": [
{
"savingsAccountId": "SAVKB2UVwUTBQGJ",
"savingsAccountName": "friendly name",
"grossIncome": 1000.12,
"netIncome": 1000.12,
"taxDeducted": 1000.12
}
]
},
"dividends": {
"incomeReceived": 1000,
"taxableIncome": 1000
}
},
"links": [
{
"href": "/individuals/calculations/RW399019B/self-assessment/f2fb30e5-4ab6-4a29-b3c1-c7264259ff1c/taxable-income",
"rel": "self",
"method": "GET"
},
{
"href": "/individuals/calculations/RW399019B/self-assessment/f2fb30e5-4ab6-4a29-b3c1-c7264259ff1c",
"rel": "metadata",
"method": "GET"
}
]
}
| Name | Description |
|---|---|
|
summary
object
required
|
Details the high-level 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 income breakdown for the calculation. |
|
payPensionsProfit
object
optional
|
Details the income breakdown of pay, pensions and profit. |
|
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 total taxable income from 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 of the UK Property FHL and UK Property Non-FHL profits. This value must be between 0 and 99999999999. No decimals.
For example: |
|
totalFHLPropertyProfit
number
optional
|
The total UK Property 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 profit and loss position for business income sources. |
|
selfEmployments
array
optional
|
A list that shows the profit and loss position for each self-employment business. |
|
selfEmploymentId
string
required
|
A unique identifier for the self-employment business income source.
Must conform to the regular expression
For example: |
|
totalIncome
number
optional
|
The total income received 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 is displayed in this field. This value is 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 is displayed in this field. This value is between 0 and 99999999999.99 up to 2 decimal places.
For example: |
|
totalAdditions
number
optional
|
The total additions to the net profit (or deductions from the net loss) for the self-employment business. This value must be between 0 and 99999999999.99 up to 2 decimal places.
For example: |
|
totalDeductions
number
optional
|
The total deductions from the net loss (or additions to the net profit) for the self-employment business. This value must be between 0 and 99999999999.99 up to 2 decimal places.
For example: |
|
accountingAdjustments
number
optional
|
Accounting adjustments applied to the profit or loss calculation for the self-employment business. This value must be between -999999999999.99 and 999999999999.99 up to 2 decimal places.
For example: |
|
taxableProfit
number
optional
|
The taxable profit after all additions and deductions have been applied for the self-employment business. This value must be between 0 and 99999999999. No decimals.
For example: |
|
adjustedIncomeTaxLoss
number
optional
|
The adjusted Income Tax loss after all additions and deductions have been applied for the self-employment business. This value must be between 0 and 99999999999. No decimals.
For example: |
|
class4Loss
number
optional
|
The Class 4 National Insurance Contributions loss for the tax year of the calculation. 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 for the self-employment business. This value must be between 0 and 99999999999. No decimals.
For example: |
|
lossClaimsSummary
object
optional
|
Summarises losses and claims for the self-employment business. This will only be present for a crystallisation calculation. |
|
totalBroughtForwardIncomeTaxLosses
number
optional
|
The total sum of Income Tax losses brought forward from earlier years for the self-employment business. This value must be between 0 and 99999999999. No decimals.
For example: |
|
broughtForwardIncomeTaxLossesUsed
number
optional
|
This is the total sum of losses brought forward from previous years used against the taxable profit for the self-employment business for the tax year of the calculation. This value must be between 0 and 99999999999. No decimals.
For example: |
|
totalIncomeTaxLossesCarriedForward
number
optional
|
The total sum of Income Tax losses to be carried forward that have not been used against the self-employment business 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 sum of Class 4 National Insurance Contributions losses brought forward from earlier years for the self-employment business. This value must be between 0 and 99999999999. No decimals.
For example: |
|
broughtForwardClass4LossesUsed
number
optional
|
The total sum of Class 4 National Insurance Contributions losses brought forward from earlier years that have been used against the Class 4 National Insurance Contributions for the self-employment business 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 Contributions losses for the self-employment business that have been carried sideways in this calculation. This value must be between 0 and 99999999999. No decimals.
For example: |
|
totalClass4LossesCarriedForward
number
optional
|
The total sum of Class 4 National Insurance Contributions losses to be carried forward that have not been used against the self-employment business profits for the tax year of the calculation. This value must be between 0 and 99999999999. No decimals.
For example: |
|
lossClaimsDetail
object
optional
|
Details individual loss claims and how they have been used 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. Limited to the following possible values: income
class4-nics
|
|
taxYearLossIncurred
string
required
|
The tax year of the loss. 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
|
Flag indicating the loss was registered by the taxpayer on joining MTD.
For example: |
|
resultOfClaimsApplied
array
optional
|
A list of loss claims in this calculation for the self-employment business. |
|
claimId
string
optional
|
The Claim ID of the loss.
Must conform to the regular expression
For example: |
|
taxYearClaimMade
string
required
|
The tax year in which the claim was 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
|
Flag indicating the loss was registered by the taxpayer on joining MTD.
For example: |
|
taxYearLossIncurred
string
required
|
The tax year the loss arose. 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 remaining loss not 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
|
Losses from the self-employment business from this calculation where no carry forward claim has been made |
|
taxYearLossIncurred
string
required
|
The tax year the loss arose. 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 from the self-employment business from this calculation where a carry forward claim has been made |
|
claimId
string
optional
|
The Claim ID of the loss.
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 of the loss. 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. Limited to the following possible values: income
class4-nics
|
|
claimsNotApplied
array
optional
|
Loss claims that could not be applied in this calculation for the self-employment business |
|
claimId
string
required
|
The Claim ID of the loss.
Must conform to the regular expression
For example: |
|
taxYearClaimMade
string
required
|
The tax year in which the claim was 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 profit and loss position for UK Property FHL. |
|
totalIncome
number
optional
|
The total income received for UK Property FHL. This value must be between 0 and 99999999999.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 the result will be displayed in this field. This value is 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 is between 0 and 99999999999.99 up to 2 decimal places.
For example: |
|
totalAdditions
number
optional
|
The total additions to the net profit (or deductions from the net loss) for UK Property FHL. This value must be between 0 and 99999999999.99 up to 2 decimal places.
For example: |
|
totalDeductions
number
optional
|
The total deductions from the net loss (or additions to the net profit) for the UK Property FHL. This value must be between 0 and 99999999999.99 up to 2 decimal places.
For example: |
|
accountingAdjustments
number
optional
|
Accounting adjustments applied to the profit or loss calculation for UK Property FHL. This value must be between -999999999999.99 and 999999999999.99 up to 2 decimal places.
For example: |
|
taxableProfit
number
optional
|
The taxable profit after all additions and deductions have been applied for UK Property FHL. This value must be between 0 and 99999999999. No decimals.
For example: |
|
adjustedIncomeTaxLoss
number
optional
|
The adjusted Income Tax loss after all additions and deductions have been applied for UK property FHL. 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 for UK Property FHL. This value must be between 0 and 99999999999. No decimals.
For example: |
|
lossClaimsSummary
object
optional
|
Summarises losses and claims for the UK Property FHL. This section 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 sum of Income Tax losses brought forward from earlier years for UK Property FHL. This value must be between 0 and 99999999999. No decimals.
For example: |
|
broughtForwardIncomeTaxLossesUsed
number
optional
|
This is the total sum of losses brought forward from previous years used against the taxable profit for UK Property FHL for the tax year of the calculation. This value must be between 0 and 99999999999. No decimals.
For example: |
|
totalIncomeTaxLossesCarriedForward
number
optional
|
The total sum of Income Tax losses to be carried forward that have not been used against the UK Property FHL profits for the tax year of the calculation. This value must be between 0 and 99999999999. No decimals.
For example: |
|
lossClaimsDetail
object
optional
|
Details individual loss claims and how they have been used in the calculation for the 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 of the loss. 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
|
Flag indicating the loss was registered by the taxpayer on joining MTD.
For example: |
|
resultOfClaimsApplied
array
optional
|
A list of loss claims in this calculation for UK Property FHL |
|
claimId
string
optional
|
The Claim ID of the loss.
Must conform to the regular expression
For example: |
|
taxYearClaimMade
string
required
|
The tax year in which the claim was made. Format: YYYY-YY
For example: |
|
claimType
string
required
|
The type of claim made. Limited to the following possible values: carry-forward
|
|
mtdLoss
boolean
required
|
Flag indicating whether the loss was registered by the taxpayer on joining MTD.
For example: |
|
taxYearLossIncurred
string
required
|
The tax year the loss. 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 remaining loss not used in the tax year of the calculation. This value must be between 0 and 99999999999. No decimals.
For example: |
|
defaultCarriedForwardLosses
array
optional
|
UK Property FHL losses from this calculation that will be carried forward to the next tax year. |
|
taxYearLossIncurred
string
required
|
The tax year of the loss. 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 profit and loss position for UK Property Non-FHL. |
|
totalIncome
number
optional
|
TThe total income received for UK Property Non-FHL. This value must be between 0 and 99999999999.99 up to 2 decimal places.
For example: |
|
totalExpenses
number
optional
|
The total expenses for UK property Non-FHL. 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 is displayed in this field. This value is 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 is displayed in this field. This value is between 0 and 99999999999.99 up to 2 decimal places.
For example: |
|
totalAdditions
number
optional
|
The total additions to the net profit (or deductions from the net loss) for UK Property Non-FHL. This value must be between 0 and 99999999999.99 up to 2 decimal places.
For example: |
|
totalDeductions
number
optional
|
The total deductions from the net loss (or additions to the net profit) for UK Property Non-FHL. This value must be between 0 and 99999999999.99 up to 2 decimal places.
For example: |
|
accountingAdjustments
number
optional
|
Accounting adjustments applied to the profit or loss calculation for UK Property Non-FHL. This value must be between -999999999999.99 and 999999999999.99 up to 2 decimal places.
For example: |
|
taxableProfit
number
optional
|
The taxable profit after all additions and deductions have been applied for UK Property Non-FHL. This value must be between 0 and 99999999999. No decimals.
For example: |
|
adjustedIncomeTaxLoss
number
optional
|
The adjusted Income Tax loss after all additions and deductions have been applied for UK property Non-FHL. 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 for UK Property Non-FHL. This value must be between 0 and 99999999999. No decimals.
For example: |
|
lossClaimsSummary
object
optional
|
Summarises losses and claims for UK Property Non-FHL This will only be present for a crystallisation calculation. |
|
totalBroughtForwardIncomeTaxLosses
number
optional
|
The total sum of Income Tax losses brought forward from earlier years for UK Property Non-FHL. This value must be between 0 and 99999999999. No decimals.
For example: |
|
broughtForwardIncomeTaxLossesUsed
number
optional
|
This is the total sum of losses brought forward from previous years used against the taxable profit for UK Property Non-FHL for the tax year of the calculation. This value must be between 0 and 99999999999. No decimals.
For example: |
|
totalIncomeTaxLossesCarriedForward
number
optional
|
The total sum of Income Tax losses to be carried forward that have not been utilised against the UK Property Non-FHL profits for the tax year of the calculation. This value must be between 0 and 99999999999. No decimals.
For example: |
|
lossClaimsDetail
object
optional
|
Details individual loss claims and how they have been used in the calculation for the 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 UK Property Non-FHL. |
|
taxYearLossIncurred
string
required
|
The tax year of the loss. 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
|
Flag indicating the loss was registered by the taxpayer on joining MTD.
For example: |
|
resultOfClaimsApplied
array
optional
|
A list of loss claims in this calculation for UK Property Non-FHL |
|
claimId
string
optional
|
The Claim ID of the loss.
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 claim was 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
|
Flag indicating the loss was registered by the taxpayer on joining MTD.
For example: |
|
taxYearLossIncurred
string
optional
|
The tax year of the loss. 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 remaining loss not used in the tax year of the calculation. This value must be between 0 and 99999999999. No decimals.
For example: |
|
defaultCarriedForwardLosses
array
optional
|
UK Property Non-FHL losses from this calculation that will be carried forward to the next tax year. |
|
taxYearLossIncurred
string
required
|
The tax year of the loss. 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
|
Loss claims that could not be applied in this calculation for UK Property Non-FHL. |
|
claimId
string
required
|
The Claim ID of the loss.
Must conform to the regular expression
For example: |
|
taxYearClaimMade
string
required
|
The tax year in which the claim was 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-sideways-fhl
carry-forward
carry-forward-to-carry-sideways
|
|
savingsAndGains
object
optional
|
Details the breakdown of taxable savings income. |
|
incomeReceived
number
required
|
The total taxed and untaxed savings income received. This value must be between 0 and 99999999999. No decimals.
For example: |
|
taxableIncome
number
required
|
The taxable savings income. This value must be between 0 and 99999999999. No decimals.
For example: |
|
ukSavings
array
optional
|
Details of 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 received from 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 received from 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 figure minus the net figure). The value must be between 0 and 999999999999.99 up to 2 decimal places.
For example: |
|
dividends
object
optional
|
Details of dividend income. |
|
incomeReceived
number
required
|
The dividends income received. This value must be between 0 and 99999999999. No decimals.
For example: |
|
taxableIncome
number
required
|
The taxable dividends income. This value must be between 0 and 99999999999. No decimals.
For example: |
|
links
array
optional
|
A list of endpoint links that indicate possible actions related to the current resource |
|
href
string
required
|
The relative url of the endpoint
For example: |
|
rel
string
required
|
A label for the endpoint, which describes how it is related to the current resource. The rel will be self where the action is retrieval of the same resource Limited to the following possible values: self
metadata
|
|
method
string
required
|
The HTTP method type for the endpoint Limited to the following possible values: GET
|
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
}
}
},
"links": [
{
"href": "/individuals/calculations/RW399019B/self-assessment/f2fb30e5-4ab6-4a29-b3c1-c7264259ff1c/allowances-deductions-reliefs",
"rel": "self",
"method": "GET"
},
{
"href": "/individuals/calculations/RW399019B/self-assessment/f2fb30e5-4ab6-4a29-b3c1-c7264259ff1c",
"rel": "metadata",
"method": "GET"
}
]
}
| Name | Description |
|---|---|
|
summary
object
required
|
Details of allowances, deductions and reliefs used in the calculation. |
|
totalAllowancesAndDeductions
number
optional
|
The total allowances and deductions used in the calculation. This value must be between 0 and 99999999999. No decimals.
For example: |
|
totalReliefs
number
optional
|
The total reliefs used in the calculation. This value must be between 0 and 99999999999.99.
For example: |
|
detail
object
required
|
Details the breakdown of allowances, deductions and reliefs used in the calculation. |
|
allowancesAndDeductions
object
optional
|
Details allowances and deductions used in the calculation. |
|
personalAllowance
number
optional
|
The personal allowance available for the tax year. This value must be between 0 and 99999999999. No decimals.
For example: |
|
reducedPersonalAllowance
number
optional
|
The 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 reliefs used in the calculation. |
|
residentialFinanceCosts
object
optional
|
Details the residential finance cost reliefs used in 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 in the calculation. This 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: |
|
links
array
optional
|
A list of endpoint links that indicate possible actions related to the current resource |
|
href
string
required
|
The relative url of the endpoint
For example: |
|
rel
string
required
|
A label for the endpoint, which describes how it is related to the current resource The rel will be self where the action is retrieval of the same resource Limited to the following possible values: self
metadata
|
|
method
string
required
|
The HTTP method type for the endpoint Limited to the following possible values: GET
|
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
}
},
"links": [
{
"href": "/individuals/calculations/RW399019B/self-assessment/f2fb30e5-4ab6-4a29-b3c1-c7264259ff1c/end-of-year-estimate",
"rel": "self",
"method": "GET"
},
{
"href": "/individuals/calculations/RW399019B/self-assessment/f2fb30e5-4ab6-4a29-b3c1-c7264259ff1c",
"rel": "metadata",
"method": "GET"
}
]
}
| 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: |
|
links
array
optional
|
A list of endpoint links that indicate possible actions related to the current resource |
|
href
string
required
|
The relative url of the endpoint
For example: |
|
rel
string
required
|
A label for the endpoint, which describes how it is related to the current resource The rel will be self where the action is retrieval of the same resource Limited to the following possible values: self
metadata
|
|
method
string
required
|
The HTTP method type for the endpoint Limited to the following possible values: GET
|
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"
}
],
"links": [
{
"href": "/individuals/calculations/RW399019B/self-assessment/f2fb30e5-4ab6-4a29-b3c1-c7264259ff1c/messages",
"rel": "self",
"method": "GET"
},
{
"href": "/individuals/calculations/RW399019B/self-assessment/f2fb30e5-4ab6-4a29-b3c1-c7264259ff1c",
"rel": "metadata",
"method": "GET"
}
]
}
{
"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."
}
],
"links": [
{
"href": "/individuals/calculations/RW399019B/self-assessment/f2fb30e5-4ab6-4a29-b3c1-c7264259ff1c/messages",
"rel": "self",
"method": "GET"
},
{
"href": "/individuals/calculations/RW399019B/self-assessment/f2fb30e5-4ab6-4a29-b3c1-c7264259ff1c",
"rel": "metadata",
"method": "GET"
}
]
}
{
"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"
}
],
"links": [
{
"href": "/individuals/calculations/RW399019B/self-assessment/f2fb30e5-4ab6-4a29-b3c1-c7264259ff1c/messages",
"rel": "self",
"method": "GET"
},
{
"href": "/individuals/calculations/RW399019B/self-assessment/f2fb30e5-4ab6-4a29-b3c1-c7264259ff1c",
"rel": "metadata",
"method": "GET"
}
]
}
{
"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."
}
],
"links": [
{
"href": "/individuals/calculations/RW399019B/self-assessment/f2fb30e5-4ab6-4a29-b3c1-c7264259ff1c/messages",
"rel": "self",
"method": "GET"
},
{
"href": "/individuals/calculations/RW399019B/self-assessment/f2fb30e5-4ab6-4a29-b3c1-c7264259ff1c",
"rel": "metadata",
"method": "GET"
}
]
}
| 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. |
|
links
array
optional
|
A list of endpoint links that indicate possible actions related to the current resource |
|
href
string
required
|
The relative url of the endpoint
For example: |
|
rel
string
required
|
A label for the endpoint, which describes how it is related to the current resource The rel will be self where the action is retrieval of the same resource Limited to the following possible values: self
metadata
|
|
method
string
required
|
The HTTP method type for the endpoint Limited to the following possible values: GET
|
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. |