This version is in beta  expect some breaking changes.
Individual Calculations (MTD) API
Available in Sandbox  Yes 

Sandbox base URL  https://testapi.service.hmrc.gov.uk 
Available in Production  No 
Overview
This API allows a selfassessment taxpayer to:
 trigger a selfassessment tax calculation
 list all their selfassessment tax calculations for a tax year
 retrieve their selfassessment tax calculation result using multiple endpoints
Versioning
When an API changes in a way that is backwardsincompatible, 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.
Single errors will be returned in the following format:
{
"code": "FORMAT_FIELD_NAME",
"message": "The provided FieldName is invalid"
}
Where possible, multiple errors will be returned with INVALID_REQUEST
in the following format:
{
"code": "INVALID_REQUEST",
"message": "Invalid request",
"errors": [
{
"code": "RULE_FIELD_NAME",
"message": "The provided FieldName is not allowed"
},
{
"code": "FORMAT_FIELD_NAME",
"message": "The provided FieldName is invalid"
}
]
}
Changelog
You can find the changelog in the individualcalculationsapi GitHub wiki.
Support
 Raise nontechnical or platformrelated issues with the Software Development Support Team (SDST).
 Raise technical issues on the individualcalculationsapi 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 GovTestScenario header. Documentation for each endpoint includes a Test data section, which explains the scenarios that you can simulate using the GovTestScenario 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.
Endpoints
Self Assessment
Here a developer can:
 List selfassessment tax calculations for a given National Insurance number (NINO) and tax year
 Trigger a selfassessment tax calculation for a given tax year. The result of the calculation can be explored via the “Retrieve a selfassessment tax calculation metadata” endpoint
 Retrieve highlevel 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 selfassessment 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 endofyear 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}/selfassessment
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
userrestricted
and requires an Authorization
header containing an OAuth 2.0 Bearer Token with the read:selfassessment
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, 201920. 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.2.0+json

GovTestScenario
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:selfassessment scope.
For example: Bearer bb7fed3fe10dd235a2ccda3d50fb

See also fraud prevention.
Response headers
Name  Description 

XCorrelationId
required

Unique ID for operation tracking For example: c75f40a6a3df4429a697471eeec46435

See also fraud prevention.
Response
HTTP status: 200 (OK)
{ "calculations": [ { "id": "f2fb30e54ab64a29b3c1c7264259ff1c", "calculationTimestamp": "20190317T09:22:59Z", "type": "inYear", "requestedBy": "hmrc", "links": [ { "href": "/individuals/calculations/RW399019B/selfassessment/f2fb30e54ab64a29b3c1c7264259ff1c", "rel": "self", "method": "GET" } ] }, { "id": "cf63c46a1a4f3c56b9ea9a82551d27bb", "calculationTimestamp": "20190617T18:45:59Z", "type": "crystallisation", "requestedBy": "customer", "links": [ { "href": "/individuals/calculations/RW399019B/selfassessment/cf63c46a1a4f3c56b9ea9a82551d27bb", "rel": "self", "method": "GET" } ] } ], "links": [ { "href": "/individuals/calculations/RW399019B/selfassessment", "rel": "self", "method": "GET" }, { "href": "/individuals/calculations/RW399019B/selfassessment", "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: YYYYMMDDThh: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 GovTestScenario headers is only available in the sandbox environment.
Header Value (GovTestScenario)  Scenario 

N/A  DEFAULT 
Simulate success scenario for selfemployment 
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 selfassessment tax calculation for a given tax year. It should be called whenever income data is updated through a periodic or annual endpoint. The tax calculation can take up to 5 seconds to process. We recommend you wait 5 seconds before calling retrieval endpoints. The result of the calculation can be seen using the “Retrieve Self Assessment Tax Calculation Metadata” endpoint.
Authorisation
This endpoint is
userrestricted
and requires an Authorization
header containing an OAuth 2.0 Bearer Token with the write:selfassessment
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.2.0+json

ContentType
required

Specifies the format of the request body, which must be JSON. For example: application/json

GovTestScenario
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:selfassessment scope.
For example: Bearer bb7fed3fe10dd235a2ccda3d50fb

See also fraud prevention.
Request
{ "taxYear": "201718" }
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, 201921 is not valid. The minimum tax year is 201718.
For example: 
Response headers
Name  Description 

XCorrelationId
required

Unique ID for operation tracking For example: c75f40a6a3df4429a697471eeec46435

See also fraud prevention.
Response
HTTP status: 202 (Accepted)
{ "id": "f2fb30e54ab64a29b3c1c7264259ff1c", "links": [ { "href": "/individuals/calculations/RW399019B/selfassessment/f2fb30e54ab64a29b3c1c7264259ff1c", "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 nonmatching 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 GovTestScenario headers is only available in the sandbox environment.
Header Value (GovTestScenario)  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}/selfassessment/{calculationId}
The “Retrieve Self Assessment tax calculation metadata” endpoint allows users to retrieve highlevel 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
userrestricted
and requires an Authorization
header containing an OAuth 2.0 Bearer Token with the read:selfassessment
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.2.0+json

GovTestScenario
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:selfassessment scope.
For example: Bearer bb7fed3fe10dd235a2ccda3d50fb

See also fraud prevention.
Response headers
Name  Description 

XCorrelationId
required

Unique ID for operation tracking For example: c75f40a6a3df4429a697471eeec46435

See also fraud prevention.
Response
HTTP status: 200 (OK)
{ "id": "f2fb30e54ab64a29b3c1c7264259ff1c", "taxYear": "201819", "requestedBy": "customer", "calculationReason": "customerRequest", "calculationTimestamp": "20191115T09:35:15.094Z", "calculationType": "crystallisation", "intentToCrystallise": true, "crystallised": true, "totalIncomeTaxAndNicsDue": 5010.34, "links": [ { "href": "/individuals/calculations/RW399019B/selfassessment/f2fb30e54ab64a29b3c1c7264259ff1c", "rel": "self", "method": "GET" }, { "href": "/individuals/calculations/RW399019B/selfassessment/f2fb30e54ab64a29b3c1c7264259ff1c/incometaxnicscalculated", "rel": "incometaxandnicscalculated", "method": "GET" }, { "href": "/individuals/calculations/RW399019B/selfassessment/f2fb30e54ab64a29b3c1c7264259ff1c/taxableincome", "rel": "taxableincome", "method": "GET" }, { "href": "/individuals/calculations/RW399019B/selfassessment/f2fb30e54ab64a29b3c1c7264259ff1c/allowancesdeductionsreliefs", "rel": "allowancesdeductionsreliefs", "method": "GET" }, { "href": "/individuals/calculations/RW399019B/selfassessment/f2fb30e54ab64a29b3c1c7264259ff1c/endofyearestimate", "rel": "endofyearestimate", "method": "GET" }, { "href": "/individuals/calculations/RW399019B/selfassessment/f2fb30e54ab64a29b3c1c7264259ff1c/messages", "rel": "messages", "method": "GET" } ] }
{ "id": "b03921dc8e235e8abf0e55a8e3904673", "taxYear": "201819", "requestedBy": "customer", "calculationReason": "customerRequest", "calculationTimestamp": "20190215T08:22:15.094Z", "calculationType": "inYear", "intentToCrystallise": false, "crystallised": false, "totalIncomeTaxAndNicsDue": 2000.98, "links": [ { "href": "/individuals/calculations/RW399019B/selfassessment/f2fb30e54ab64a29b3c1c7264259ff1c", "rel": "self", "method": "GET" }, { "href": "/individuals/calculations/RW399019B/selfassessment/f2fb30e54ab64a29b3c1c7264259ff1c/incometaxnicscalculated", "rel": "incometaxandnicscalculated", "method": "GET" }, { "href": "/individuals/calculations/RW399019B/selfassessment/f2fb30e54ab64a29b3c1c7264259ff1c/taxableincome", "rel": "taxableincome", "method": "GET" }, { "href": "/individuals/calculations/RW399019B/selfassessment/f2fb30e54ab64a29b3c1c7264259ff1c/allowancesdeductionsreliefs", "rel": "allowancesdeductionsreliefs", "method": "GET" }, { "href": "/individuals/calculations/RW399019B/selfassessment/f2fb30e54ab64a29b3c1c7264259ff1c/endofyearestimate", "rel": "endofyearestimate", "method": "GET" }, { "href": "/individuals/calculations/RW399019B/selfassessment/f2fb30e54ab64a29b3c1c7264259ff1c/messages", "rel": "messages", "method": "GET" } ] }
{ "id": "17d6876e620e405996ef50adf5422d27", "taxYear": "201819", "requestedBy": "hmrc", "calculationReason": "newClaimEvent", "calculationTimestamp": "20190704T13:37:35.094Z", "calculationType": "inYear", "intentToCrystallise": false, "crystallised": false, "calculationErrorCount": 8, "links": [ { "href": "/individuals/calculations/RW399019B/selfassessment/f2fb30e54ab64a29b3c1c7264259ff1c", "rel": "self", "method": "GET" }, { "href": "/individuals/calculations/RW399019B/selfassessment/f2fb30e54ab64a29b3c1c7264259ff1c/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 YYYYYY
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 inyear "crystallisation" calculation type.
newLossEvent
 The calculation was triggered internally by HMRC on receipt of a new preMTD 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 preMTD 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: YYYYMMDDThh: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
incometaxandnicscalculated
taxableincome
allowancesdeductionsreliefs
endofyearestimate
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 GovTestScenario headers is only available in the sandbox environment.
Header Value (GovTestScenario)  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 NonFHL Property business with Dividends. 
UK_PROP_GIFTAID_EXAMPLE 
Simulates an example tax calculation with realistic data values, for a UK NonFHL Property business with Gift Aid. 
UK_PROP_SAVINGS_EXAMPLE 
Simulates an example tax calculation with realistic data values, for a UK NonFHL Property business with Savings. 
UK_SE_GIFTAID_EXAMPLE 
Simulates an example tax calculation with realistic data values, for a UK SelfEmployment business with Gift Aid. 
UK_SE_SAVINGS_EXAMPLE 
Simulates an example tax calculation with realistic data values, for a UK SelfEmployment business with Savings. 
SCOT_SE_DIVIDENDS_EXAMPLE 
Simulates an example tax calculation with realistic data values, for a Scottish SelfEmployment business with Dividends. 
/individuals/calculations/{nino}/selfassessment/{calculationId}/incometaxnicscalculated
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
userrestricted
and requires an Authorization
header containing an OAuth 2.0 Bearer Token with the read:selfassessment
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.2.0+json

GovTestScenario
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:selfassessment scope.
For example: Bearer bb7fed3fe10dd235a2ccda3d50fb

See also fraud prevention.
Response headers
Name  Description 

XCorrelationId
required

Unique ID for operation tracking For example: c75f40a6a3df4429a697471eeec46435

See also fraud prevention.
Response
HTTP status: 200 (OK)
{ "summary": { "incomeTax": { "incomeTaxCharged": 5000, "incomeTaxDueAfterReliefs": 99999999999.99, "incomeTaxDueAfterGiftAid": 5000, "totalNotionalTax": 5000.99, "incomeTaxDueAfterTaxReductions": 5000.99, "totalPensionSavingsTaxCharges": 5000.99, "statePensionLumpSumCharges": 5000.99, "totalIncomeTaxDue": 5000.99 }, "nics": { "class2NicsAmount": 5000, "class4NicsAmount": 5000, "totalNic": 5000 }, "totalStudentLoansRepaymentAmount": 5000.99, "totalAnnualPaymentsTaxCharged": 12500, "totalRoyaltyPaymentsTaxCharged": 5000.99, "totalIncomeTaxNicsCharged": 5000, "totalTaxDeducted": 12500, "totalIncomeTaxAndNicsDue": 99999999999.99, "taxRegime": "UK" }, "detail": { "incomeTax": { "payPensionsProfit": { "allowancesAllocated": 12500, "incomeTaxAmount": 5000, "taxBands": [ { "name": "IRT", "rate": 20, "bandLimit": 12500, "apportionedBandLimit": 12500, "income": 12500, "taxAmount": 5000 } ] }, "savingsAndGains": { "allowancesAllocated": 12500, "incomeTaxAmount": 5000, "taxBands": [ { "name": "SSR", "rate": 20, "bandLimit": 12500, "apportionedBandLimit": 12500, "income": 12500, "taxAmount": 5000 } ] }, "lumpSums": { "allowancesAllocated": 12500, "incomeTaxAmount": 5000.99, "taxBands": [ { "name": "HRT", "rate": 20, "bandLimit": 12500, "apportionedBandLimit": 12500, "income": 12500, "taxAmount": 5000.99 } ] }, "gainsOnLifePolicies": { "allowancesAllocated": 12500, "incomeTaxAmount": 5000.99, "taxBands": [ { "name": "ART", "rate": 20, "bandLimit": 12500, "apportionedBandLimit": 12500, "income": 12500, "taxAmount": 5000.99 } ] }, "dividends": { "allowancesAllocated": 12500, "incomeTaxAmount": 5000, "taxBands": [ { "name": "BRT", "rate": 20, "bandLimit": 12500, "apportionedBandLimit": 12500, "income": 12500, "taxAmount": 5000 } ] }, "giftAid": { "grossGiftAidPayments": 12500, "rate": 20.99, "giftAidTax": 2000.99, "giftAidTaxReductions": 5000.99, "incomeTaxChargedAfterGiftAidTaxReductions": 5000.99, "giftAidCharge": 5000.99 } }, "studentLoans": [ { "planType": "01", "studentLoanTotalIncomeAmount": 5000.99, "studentLoanChargeableIncomeAmount": 5000.99, "studentLoanRepaymentAmount": 5000.99, "studentLoanDeductionsFromEmployment": 5000.99, "studentLoanRepaymentAmountNetOfDeductions": 5000.99, "studentLoanApportionedIncomeThreshold": 12500, "studentLoanRate": 20 } ], "pensionSavingsTaxCharges": { "totalPensionCharges": 5000.99, "totalTaxPaid": 5000.99, "totalPensionChargesDue": 5000.99, "pensionSavingsTaxChargesDetail": { "excessOfLifetimeAllowance": { "totalChargeableAmount": 5000.99, "totalTaxPaid": 5000.99, "lumpSumBenefitTakenInExcessOfLifetimeAllowance": { "amount": 5000.99, "taxPaid": 5000.99, "rate": 20, "chargeableAmount": 5000.99 }, "benefitInExcessOfLifetimeAllowance": { "amount": 5000.99, "taxPaid": 5000.99, "rate": 20.99, "chargeableAmount": 5000.99 } }, "pensionSchemeUnauthorisedPayments": { "totalChargeableAmount": 5000.99, "totalTaxPaid": 5000.99, "pensionSchemeUnauthorisedPaymentsSurcharge": { "amount": 5000.99, "taxPaid": 5000.99, "rate": 20.99, "chargeableAmount": 5000.99 }, "pensionSchemeUnauthorisedPaymentsNonSurcharge": { "amount": 5000.99, "taxPaid": 5000.99, "rate": 20.99, "chargeableAmount": 5000.99 } }, "pensionSchemeOverseasTransfers": { "transferCharge": 5000.99, "transferChargeTaxPaid": 5000.99, "rate": 20.99, "chargeableAmount": 5000.99 }, "pensionContributionsInExcessOfTheAnnualAllowance": { "totalContributions": 5000.99, "totalPensionCharge": 5000.99, "annualAllowanceTaxPaid": 5000.99, "totalPensionChargeDue": 5000.99, "pensionBands": [ { "name": "BRT", "rate": 20, "bandLimit": 12500, "apportionedBandLimit": 12500, "contributionAmount": 5000.99, "pensionCharge": 5000.99 } ] }, "overseasPensionContributions": { "totalShortServiceRefund": 5000.99, "totalShortServiceRefundCharge": 5000.99, "shortServiceRefundTaxPaid": 5000.99, "totalShortServiceRefundChargeDue": 5000.99, "shortServiceRefundBands": [ { "name": "lowerBand", "rate": 20, "bandLimit": 12500, "apportionedBandLimit": 12500, "shortServiceRefundAmount": 5000.99, "shortServiceRefundCharge": 5000.99 } ] } } }, "nics": { "class2Nics": { "weeklyRate": 5000, "weeks": 0, "limit": 12500, "apportionedLimit": 12500, "underSmallProfitThreshold": true, "actualClass2Nic": true, "class2VoluntaryContributions": true }, "class4Nic": { "totalIncomeLiableToClass4Charge": 200, "class4Losses": { "totalClass4LossesAvailable": 2000, "totalClass4LossesUsed": 1000, "totalClass4LossesCarriedForward": 2000 }, "totalIncomeChargeableToClass4": 200, "class4NicBands": [ { "name": "ZRT", "rate": 20, "threshold": 12500, "apportionedThreshold": 12500, "income": 5000, "amount": 5000 } ] } }, "taxDeductedAtSource": { "savings": 12500.99, "ukLandAndProperty": 12500.99, "cis": 12500, "securities": 5000.99, "voidedIsa": 5000.99, "payeEmployments": 5000.99, "occupationalPensions": 5000.99, "stateBenefits": 99999999999.99, "specialWithholdingTaxOrUkTaxPaid": 5000.99 } }, "links": [ { "href": "/individuals/calculations/RW399019B/selfassessment/f2fb30e54ab64a29b3c1c7264259ff1c/incometaxnicscalculated", "rel": "self", "method": "GET" }, { "href": "/individuals/calculations/RW399019B/selfassessment/f2fb30e54ab64a29b3c1c7264259ff1c", "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: 
totalNotionalTax
number
optional

The total amount of Notional Tax. This value must be between 0 and 99999999999.99 up to 2 decimal places.
For example: 
totalPensionSavingsTaxCharges
number
optional

The total amount of tax charges on pension savings. This value must be between 0 and 99999999999.99 up to 2 decimal places.
For example: 
statePensionLumpSumCharges
number
optional

The total amount of tax charges on state pension lumps sums. This value must be between 0 and 99999999999.99 up to 2 decimal places.
For example: 
incomeTaxDueAfterTaxReductions
number
optional

The total amount of Income Tax due after tax reductions. This value must be between 0 and 99999999999.99 up to 2 decimal places.
For example: 
totalIncomeTaxDue
number
optional

The total amount of Income Tax due. 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: 
totalStudentLoansRepaymentAmount
number
optional

The total amount of student loan repayments. This value must be between 0 and 99999999999.99 up to 2 decimal places.
For example: 
totalAnnualPaymentsTaxCharged
number
optional

The total amount of tax charged on annual payments. This value must be between 0 and 99999999999. No decimals.
For example: 
totalRoyaltyPaymentsTaxCharged
number
optional

The total amount of tax charged on royalty payments. This value must be between 0 and 99999999999.99 up to 2 decimal places.
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 99999999999.99 and 99999999999.99 up to 2 decimal places.
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: 
lumpSums
object
optional

Details the breakdown of Income Tax due for lump sums. 
allowancesAllocated
number
required

The allowances allocated to the lump sums 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 lump sums. 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: 
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: 
gainsOnLifePolicies
object
optional

Details the breakdown of Income Tax due for gains on life policies. 
allowancesAllocated
number
required

The allowances allocated to the gains on life policies 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 gains on life policies. 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
 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 if no reliefs or deductions apply. This value must be between 0 and 99999999999.99 up to 2 decimal places.
For example: 
giftAidTaxReductions
number
optional

The amount of Gift Aid tax reductions. This value must be between 0 and 99999999999.99 up to 2 decimal places.
For example: 
incomeTaxChargedAfterGiftAidTaxReductions
number
optional

The income tax charged after Gift Aid tax reductions have been applied. This value must be between 0 and 99999999999.99 up to 2 decimal places.
For example: 
giftAidCharge
number
optional

The amount of Gift Aid tax charged after appropriate reliefs and deductions have been applied. This value must be between 0 and 99999999999.99 up to 2 decimal places.
For example: 
studentLoans
array
optional

Details the breakdown of student loan charges. 
planType
string
required

The type of student loan plan. Limited to the following possible values: 01
02
03
04

studentLoanTotalIncomeAmount
number
required

The total income used in the student loan calculation. This value must be between 0 and 99999999999.99 up to 2 decimal places.
For example: 
studentLoanChargeableIncomeAmount
number
required

The total student loan income less the threshold. This value must be between 0 and 99999999999.99 up to 2 decimal places.
For example: 
studentLoanRepaymentAmount
number
required

The student loan repayment before deductions. This value must be between 0 and 99999999999.99 up to 2 decimal places.
For example: 
studentLoanDeductionsFromEmployment
number
optional

The student loan deduction collected by the employer. This value must be between 0 and 99999999999.99 up to 2 decimal places.
For example: 
studentLoanRepaymentAmountNetOfDeductions
number
required

The student loan repayment after deductions. This value must be between 0 and 99999999999.99 up to 2 decimal places.
For example: 
studentLoanApportionedIncomeThreshold
number
required

The student loan threshold. This value must be between 0 and 99999999999. No decimals.
For example: 
studentLoanRate
number
required

The rate income is charged at. This value must be between 0 and 99.99 up to 2 decimal places.
For example: 
pensionSavingsTaxCharges
object
optional

Details of pension savings tax charges. 
totalPensionCharges
number
optional

Total of pension charges. This value must be between 0 and 99999999999.99 up to 2 decimal places.
For example: 
totalTaxPaid
number
optional

Total tax paid. This value must be between 0 and 99999999999.99 up to 2 decimal places.
For example: 
totalPensionChargesDue
number
optional

Total pension charges due after tax paid. This value must be between 0 and 99999999999.99 up to 2 decimal places.
For example: 
pensionSavingsTaxChargesDetail
object
optional

Breakdown of pension savings tax charges. 
excessOfLifetimeAllowance
object
optional

Details of chargeable amounts in excess of lifetime allowance. 
totalChargeableAmount
number
optional

Total chargeable amount for Lump Sum Benefit Taken In Excess Of Lifetime Allowance and Benefit In Excess Of Lifetime Allowance. This value must be between 0 and 99999999999.99 up to 2 decimal places.
For example: 
totalTaxPaid
number
optional

Total tax paid for Lump Sum Benefit Taken In Excess Of Lifetime Allowance and Benefit In Excess Of Lifetime Allowance. This value must be between 0 and 99999999999.99 up to 2 decimal places.
For example: 
lumpSumBenefitTakenInExcessOfLifetimeAllowance
object
optional

Details of lump sum benefit taken in excess of lifetime allowance. 
amount
number
optional

The amount of lump sum benefit taken in excess of lifetime allowance. This value must be between 0 and 99999999999.99 up to 2 decimal places.
For example: 
taxPaid
number
optional

Tax paid on lump sum benefit taken in excess of the lifetime allowance. This value must be between 0 and 99999999999.99 up to 2 decimal places.
For example: 
rate
number
optional

The rate used to determine the amount chargeable. This value must be between 0 and 99.99 up to 2 decimal places.
For example: 
chargeableAmount
number
optional

The amount chargeable on the lump sum benefit taken in excess of lifetime allowance. This value must be between 0 and 99999999999.99 up to 2 decimal places.
For example: 
benefitInExcessOfLifetimeAllowance
object
optional

Details of benefits taken in excess of lifetime allowance. 
amount
number
optional

The amount of benefit taken in excess of lifetime allowance. This value must be between 0 and 99999999999.99 up to 2 decimal places.
For example: 
taxPaid
number
optional

Tax paid on benefit taken in excess of the lifetime allowance. This value must be between 0 and 99999999999.99 up to 2 decimal places.
For example: 
rate
number
optional

The rate used to determine the amount chargeable. This value must be between 0 and 99.99 up to 2 decimal places.
For example: 
chargeableAmount
number
optional

The amount chargeable on benefit taken in excess of lifetime allowance. This value must be between 0 and 99999999999.99 up to 2 decimal places.
For example: 
pensionSchemeUnauthorisedPayments
object
optional

Details of pension scheme unauthorised payments. 
totalChargeableAmount
number
optional

Total chargeable amount for Pension Scheme Unauthorised Payments Surcharge and Pension Scheme Unauthorised Payments Non Surcharge. This value must be between 0 and 99999999999.99 up to 2 decimal places.
For example: 
totalTaxPaid
number
optional

Total tax paid for Pension Scheme Unauthorised Payments Surcharge and Pension Scheme Unauthorised Payments Non Surcharge. This value must be between 0 and 99999999999.99 up to 2 decimal places.
For example: 
pensionSchemeUnauthorisedPaymentsSurcharge
object
optional

Details of pension scheme unauthorised payments surcharge. 
amount
number
optional

The amount of unauthorised payments surcharge. This value must be between 0 and 99999999999.99 up to 2 decimal places.
For example: 
taxPaid
number
optional

Tax paid on unauthorised payments surcharge. This value must be between 0 and 99999999999.99 up to 2 decimal places.
For example: 
rate
number
optional

The rate used to determine the amount chargeable. This value must be between 0 and 99.99 up to 2 decimal places.
For example: 
chargeableAmount
number
optional

The amount chargeable on unauthorised payments surcharges. This value must be between 0 and 99999999999.99 up to 2 decimal places.
For example: 
pensionSchemeUnauthorisedPaymentsNonSurcharge
object
optional

Details of pension scheme unauthorised payments non surcharge. 
amount
number
optional

The amount of unauthorised payments non surcharge. This value must be between 0 and 99999999999.99 up to 2 decimal places.
For example: 
taxPaid
number
optional

Tax paid on unauthorised payments non surcharge. This value must be between 0 and 99999999999.99 up to 2 decimal places.
For example: 
rate
number
optional

The rate used to determine the amount chargeable. This value must be between 0 and 99.99 up to 2 decimal places.
For example: 
chargeableAmount
number
optional

The amount chargeable on unauthorised payments non surcharge. This value must be between 0 and 99999999999.99 up to 2 decimal places.
For example: 
pensionSchemeOverseasTransfers
object
optional

Details of pension scheme overseas transfers. 
transferCharge
number
optional

The amount of overseas pension scheme transfer charges. This value must be between 0 and 99999999999.99 up to 2 decimal places.
For example: 
transferChargeTaxPaid
number
optional

Tax paid on overseas pension scheme transfer charges. This value must be between 0 and 99999999999.99 up to 2 decimal places.
For example: 
rate
number
optional

The rate used to determine the amount chargeable. This value must be between 0 and 99.99 up to 2 decimal places.
For example: 
chargeableAmount
number
optional

The amount chargeable on overseas pension scheme transfer charges. This value must be between 0 and 99999999999.99 up to 2 decimal places.
For example: 
pensionContributionsInExcessOfTheAnnualAllowance
object
optional

Details of pension contributions in excess of the annual allowance. 
totalContributions
number
required

The total amount of pension contributions in excess of the annual allowance. This value must be between 0 and 99999999999.99 up to 2 decimal places.
For example: 
totalPensionCharge
number
required

The total amount of pension charges on contributions in excess of the annual allowance. This value must be between 0 and 99999999999.99 up to 2 decimal places.
For example: 
annualAllowanceTaxPaid
number
optional

The amount of annual allowance tax paid on pension contributions in excess of the annual allowance. This value must be between 0 and 99999999999.99 up to 2 decimal places.
For example: 
totalPensionChargeDue
number
required

The amount chargeable on pension contributions in excess of the annual allowance. This value must be between 0 and 99999999999.99 up to 2 decimal places.
For example: 
pensionBands
array
optional

Details the relevant tax bands for the pension charges. 
name
string
required

The name of the tax band. Limited to the following possible values: BRT
 basic rate threshold
IRT
 intermediary rate threshold (Scottish only)
HRT
 higher rate threshold
ART
 additional rate threshold

rate
number
required

The rate used to determine the amount chargeable. This value must be between 0 and 99.99 up to 2 decimal places.
For example: 
bandLimit
number
required

The tax band limit. This value must be between 0 and 99999999999. No decimals.
For example: 
apportionedBandLimit
number
required

The apportioned tax band limit. This value must be between 0 and 99999999999. No decimals.
For example: 
contributionAmount
number
required

The amount of pension contributions in excess of the annual allowance. This value must be between 0 and 99999999999.99 up to 2 decimal places.
For example: 
pensionCharge
number
required

The amount chargeable on pension contributions in excess of the annual allowance. This value must be between 0 and 99999999999.99 up to 2 decimal places.
For example: 
overseasPensionContributions
object
optional

Details of overseas pensions contributions 
totalShortServiceRefund
number
required

The total amount of short service refunds. This value must be between 0 and 99999999999.99 up to 2 decimal places.
For example: 
totalShortServiceRefundCharge
number
required

The total amount of charges due on short service refunds. This value must be between 0 and 99999999999.99 up to 2 decimal places.
For example: 
shortServiceRefundTaxPaid
number
optional

The amount of tax paid on short service refunds. This value must be between 0 and 99999999999.99 up to 2 decimal places.
For example: 
totalShortServiceRefundChargeDue
number
required

The amount chargeable on short service refunds. This value must be between 0 and 99999999999.99 up to 2 decimal places.
For example: 
shortServiceRefundBands
array
optional

Details the relevant refund bands for overseas pension contributions. 
name
string
required

The name of the tax band. Limited to the following possible values: lowerBand
upperBand

rate
number
required

The rate used to determine the amount chargeable. This value must be between 0 and 99.99 up to 2 decimal places.
For example: 
bandLimit
number
required

The total band limit. This value must be between 0 and 99999999999. No decimals.
For example: 
apportionedBandLimit
number
required

The apportioned band limit. This value must be between 0 and 99999999999. No decimals.
For example: 
shortServiceRefundAmount
number
required

The amount of short service refunds. This value must be between 0 and 99999999999.99 up to 2 decimal places.
For example: 
shortServiceRefundCharge
number
required

The amount chargeable. 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: 
class2VoluntaryContributions
boolean
optional

Boolean showing the customer has requested to make voluntary Class 2 NICs contributions.
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.99 up to 2 decimal places.
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.99 up to 2 decimal places.
For example: 
cis
number
optional

Tax that has been deducted at source under CIS. This value must be between 0 and 99999999999.99 up to 2 decimal places.
For example: 
securities
number
optional

Tax that has been deducted at source for securities. This value must be between 0 and 99999999999.99 up to 2 decimal places.
For example: 
voidedIsa
number
optional

Tax that has been deducted at source for voided ISAs. This value must be between 0 and 99999999999.99 up to 2 decimal places.
For example: 
payeEmployments
number
optional

Tax that has been deducted at source for PAYE Employments. This value must be between 0 and 99999999999.99 up to 2 decimal places.
For example: 
occupationalPensions
number
optional

Tax that has been deducted at source for occupational pensions. This value must be between 0 and 99999999999.99 up to 2 decimal places.
For example: 
stateBenefits
number
optional

Tax that has been deducted at source for state benefits. This value must be between 99999999999.99 and 99999999999.99 up to 2 decimal places.
For example: 
specialWithholdingTaxOrUkTaxPaid
number
optional

Tax that has been deducted at source on foreign income. This value must be between 0 and 99999999999.99 up to 2 decimal places.
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 GovTestScenario headers is only available in the sandbox environment.
Header Value (GovTestScenario)  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 NonFHL Property business with Dividends. 
UK_PROP_GIFTAID_EXAMPLE 
Simulates an example tax calculation with realistic data values, for a UK NonFHL Property business with Gift Aid. 
UK_PROP_SAVINGS_EXAMPLE 
Simulates an example tax calculation with realistic data values, for a UK NonFHL Property business with Savings. 
UK_SE_GIFTAID_EXAMPLE 
Simulates an example tax calculation with realistic data values, for a UK SelfEmployment business with Gift Aid. 
UK_SE_SAVINGS_EXAMPLE 
Simulates an example tax calculation with realistic data values, for a UK SelfEmployment business with Savings. 
SCOT_SE_DIVIDENDS_EXAMPLE 
Simulates an example tax calculation with realistic data values, for a Scottish SelfEmployment business with Dividends. 
/individuals/calculations/{nino}/selfassessment/{calculationId}/taxableincome
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
userrestricted
and requires an Authorization
header containing an OAuth 2.0 Bearer Token with the read:selfassessment
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.2.0+json

GovTestScenario
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:selfassessment scope.
For example: Bearer bb7fed3fe10dd235a2ccda3d50fb

See also fraud prevention.
Response headers
Name  Description 

XCorrelationId
required

Unique ID for operation tracking For example: c75f40a6a3df4429a697471eeec46435

See also fraud prevention.
Response
HTTP status: 200 (OK)
{ "summary": { "totalIncomeReceivedFromAllSources": 12500, "totalTaxableIncome": 12500 }, "detail": { "payPensionsProfit": { "incomeReceived": 12500, "taxableIncome": 12500, "totalSelfEmploymentProfit": 2000, "totalPropertyProfit": 2000, "totalFHLPropertyProfit": 2000, "totalUKOtherPropertyProfit": 2000, "totalForeignPropertyProfit": 12500, "totalEeaFhlProfit": 12500, "totalOccupationalPensionIncome": 200.99, "totalStateBenefitsIncome": 5000.99, "totalBenefitsInKind": 500.5, "totalPayeEmploymentAndLumpSumIncome": 5000.99, "totalEmploymentExpenses": 1000.99, "totalSeafarersDeduction": 2000.99, "totalForeignTaxOnForeignEmployment": 2000.99, "totalEmploymentIncome": 12500, "totalShareSchemesIncome": 2000.99, "totalOverseasPensionsStateBenefitsRoyalties": 2000.99, "totalAllOtherIncomeReceivedWhilstAbroad": 2000.99, "totalOverseasIncomeAndGains": 2000.99, "totalForeignBenefitsAndGifts": 2000.99, "businessProfitAndLoss": { "selfEmployments": [ { "selfEmploymentId": "XAIS59366683016", "totalIncome": 5000, "totalExpenses": 5000, "netProfit": 5000, "netLoss": 5000, "totalAdditions": 5000, "totalDeductions": 5000, "accountingAdjustments": 99999999999.99, "taxableProfit": 12500, "adjustedIncomeTaxLoss": 12500, "class4Loss": 5000, "taxableProfitAfterIncomeTaxLossesDeduction": 12500, "bsas": { "bsasId": "717f3a7adb8e11e98a342a2ae2dbcce4", "applied": true, "links": [ { "href": "/individuals/selfassessment/adjustablesummary/AA123456A/selfemployment/717f3a7adb8e11e98a342a2ae2dbcce4/adjust", "rel": "retrieveselfemploymentaccountingadjustments", "method": "GET" } ] }, "lossClaimsSummary": { "carrySidewaysIncomeTaxLossesUsed": 1000, "totalBroughtForwardIncomeTaxLosses": 12500, "broughtForwardIncomeTaxLossesUsed": 12500, "totalIncomeTaxLossesCarriedForward": 12000, "totalBroughtForwardClass4Losses": 2000, "broughtForwardClass4LossesUsed": 2000, "carrySidewaysClass4LossesUsed": 2000, "totalClass4LossesCarriedForward": 2000 }, "lossClaimsDetail": { "lossesBroughtForward": [ { "lossType": "income", "taxYearLossIncurred": "201920", "currentLossValue": 12500, "mtdLoss": true } ], "resultOfClaimsApplied": [ { "claimId": "EzluDU2ObK02SdA", "taxYearClaimMade": "201920", "claimType": "carryforward", "mtdLoss": true, "taxYearLossIncurred": "201920", "lossAmountUsed": 12500, "remainingLossValue": 12500, "lossType": "income" } ], "unclaimedLosses": [ { "taxYearLossIncurred": "201920", "currentLossValue": 5000, "lossType": "income" } ], "carriedForwardLosses": [ { "claimId": "EzluDU2ObK02SdA", "claimType": "carryforward", "taxYearClaimMade": "201819", "taxYearLossIncurred": "201920", "currentLossValue": 12500, "lossType": "income" } ], "claimsNotApplied": [ { "claimId": "EzluDU2ObK02SdA", "taxYearClaimMade": "201920", "claimType": "carrysideways" } ] } } ], "ukPropertyFhl": { "totalIncome": 5000.25, "totalExpenses": 5000.25, "netProfit": 5000.25, "netLoss": 5000.25, "totalAdditions": 5000.25, "totalDeductions": 5000.25, "taxableProfit": 12500, "adjustedIncomeTaxLoss": 12500, "taxableProfitAfterIncomeTaxLossesDeduction": 12500, "bsas": { "bsasId": "818f3a7adb8e11e98a342a2ae2dbdde4", "applied": true, "links": [ { "href": "/individuals/selfassessment/adjustablesummary/AA123456A/property/818f3a7adb8e11e98a342a2ae2dbdde4/adjust", "rel": "retrieveukpropertyaccountingadjustments", "method": "GET" } ] }, "lossClaimsSummary": { "lossForCSFHL": 12500, "totalBroughtForwardIncomeTaxLosses": 12500, "broughtForwardIncomeTaxLossesUsed": 12500, "totalIncomeTaxLossesCarriedForward": 12000 }, "lossClaimsDetail": { "lossesBroughtForward": [ { "taxYearLossIncurred": "201920", "currentLossValue": 12500, "mtdLoss": true } ], "resultOfClaimsApplied": [ { "claimId": "EzluDU2ObK02SdA", "taxYearClaimMade": "201920", "claimType": "carryforward", "mtdLoss": true, "taxYearLossIncurred": "201920", "lossAmountUsed": 12500, "remainingLossValue": 12500 } ], "defaultCarriedForwardLosses": [ { "taxYearLossIncurred": "201920", "currentLossValue": 12500 } ] } }, "ukPropertyNonFhl": { "totalIncome": 5000.25, "totalExpenses": 5000.25, "netProfit": 5000.25, "netLoss": 5000.25, "totalAdditions": 5000.25, "totalDeductions": 5000.25, "accountingAdjustments": 99999999999.99, "taxableProfit": 12500, "adjustedIncomeTaxLoss": 12500, "taxableProfitAfterIncomeTaxLossesDeduction": 12500, "bsas": { "bsasId": "a54ba7825ef447f4ab72495406665ca9", "applied": true, "links": [ { "href": "/individuals/selfassessment/adjustablesummary/AA123456A/property/a54ba7825ef447f4ab72495406665ca9/adjust", "rel": "retrieveukpropertyaccountingadjustments", "method": "GET" } ] }, "lossClaimsSummary": { "totalBroughtForwardIncomeTaxLosses": 12500, "broughtForwardIncomeTaxLossesUsed": 12500, "carrySidewaysIncomeTaxLossesUsed": 12500, "totalIncomeTaxLossesCarriedForward": 12000, "broughtForwardCarrySidewaysIncomeTaxLossesUsed": 12500 }, "lossClaimsDetail": { "lossesBroughtForward": [ { "taxYearLossIncurred": "201920", "currentLossValue": 12500, "mtdLoss": true } ], "resultOfClaimsApplied": [ { "claimId": "EzluDU2ObK02SdA", "originatingClaimId": "EzluDU2ObK02SdA", "taxYearClaimMade": "201920", "claimType": "carryforwardtocarrysideways", "mtdLoss": true, "taxYearLossIncurred": "201920", "lossAmountUsed": 12500, "remainingLossValue": 12500 } ], "defaultCarriedForwardLosses": [ { "taxYearLossIncurred": "201920", "currentLossValue": 12500 } ], "claimsNotApplied": [ { "claimId": "0vayS9JrW2jTa6n", "taxYearClaimMade": "201920", "claimType": "carrysidewaysfhl" } ] } }, "eeaPropertyFhl": { "totalIncome": 5000.25, "totalExpenses": 5000.25, "netProfit": 5000.25, "netLoss": 5000.25, "totalAdditions": 5000.25, "totalDeductions": 5000.25, "taxableProfit": 12500, "adjustedIncomeTaxLoss": 12500, "taxableProfitAfterIncomeTaxLossesDeduction": 12500, "bsas": { "bsasId": "818f3a7adb8e11e98a342a2ae2dbdde4", "applied": true, "links": [ { "href": "/individuals/selfassessment/adjustablesummary/AA123456A/foreignproperty/818f3a7adb8e11e98a342a2ae2dbdde4/adjust", "rel": "retrieveforeignpropertyaccountingadjustments", "method": "GET" } ] }, "lossClaimsSummary": { "lossForCSFHL": 12500, "totalBroughtForwardIncomeTaxLosses": 12500, "broughtForwardIncomeTaxLossesUsed": 12500, "totalIncomeTaxLossesCarriedForward": 12000 }, "lossClaimsDetail": { "lossesBroughtForward": [ { "taxYearLossIncurred": "201920", "currentLossValue": 12500, "mtdLoss": true } ], "resultOfClaimsApplied": [ { "claimId": "EzluDU2ObK02SdA", "taxYearClaimMade": "201920", "claimType": "carryforward", "mtdLoss": true, "taxYearLossIncurred": "201920", "lossAmountUsed": 12500, "remainingLossValue": 12500 } ], "defaultCarriedForwardLosses": [ { "taxYearLossIncurred": "201920", "currentLossValue": 12500 } ] } }, "foreignProperty": { "totalIncome": 5000.25, "totalExpenses": 5000.25, "netProfit": 5000.25, "netLoss": 5000.25, "totalAdditions": 5000.25, "totalDeductions": 5000.25, "accountingAdjustments": 99999999999.99, "taxableProfit": 12500, "adjustedIncomeTaxLoss": 12500, "taxableProfitAfterIncomeTaxLossesDeduction": 12500, "bsas": { "bsasId": "a54ba7825ef447f4ab72495406665ca9", "applied": true, "links": [ { "href": "/individuals/selfassessment/adjustablesummary/AA123456A/foreignproperty/a54ba7825ef447f4ab72495406665ca9/adjust", "rel": "retrieveforeignpropertyaccountingadjustments", "method": "GET" } ] }, "lossClaimsSummary": { "totalBroughtForwardIncomeTaxLosses": 12500, "broughtForwardIncomeTaxLossesUsed": 12500, "carrySidewaysIncomeTaxLossesUsed": 12500, "totalIncomeTaxLossesCarriedForward": 12000, "broughtForwardCarrySidewaysIncomeTaxLossesUsed": 12500 }, "lossClaimsDetail": { "lossesBroughtForward": [ { "taxYearLossIncurred": "201920", "currentLossValue": 12500, "mtdLoss": true } ], "resultOfClaimsApplied": [ { "claimId": "EzluDU2ObK02SdA", "originatingClaimId": "EzluDU2ObK02SdA", "taxYearClaimMade": "201920", "claimType": "carryforward", "mtdLoss": true, "taxYearLossIncurred": "201920", "lossAmountUsed": 12500, "remainingLossValue": 12500 } ], "defaultCarriedForwardLosses": [ { "taxYearLossIncurred": "201920", "currentLossValue": 12500 } ], "claimsNotApplied": [ { "claimId": "0vayS9JrW2jTa6n", "taxYearClaimMade": "201920", "claimType": "carryforward" } ] } } } }, "savingsAndGains": { "incomeReceived": 12500, "taxableIncome": 12500, "totalOfAllGains": 2000, "totalUkSavingsAndSecurities": 5000, "ukSavings": [ { "savingsAccountId": "SAVKB2UVwUTBQGJ", "savingsAccountName": "Santander", "grossIncome": 5000, "netIncome": 5000.99, "taxDeducted": 5000.99 } ], "ukSecurities": [ { "ukSecuritiesAccountId": "000000000000210", "ukSecuritiesAccountName": "ukSecuritiesAccountName", "grossIncome": 5000.99, "netIncome": 5000.99, "taxDeducted": 5000.99 } ], "totalGainsWithNoTaxPaidAndVoidedIsa": 5000, "totalForeignGainsOnLifePoliciesNoTaxPaid": 5000, "totalForeignSavingsAndGainsIncome": 5000 }, "dividends": { "incomeReceived": 12500, "taxableIncome": 12500, "totalUkDividends": 2500, "totalForeignDividends": 2500 }, "lumpSums": { "incomeReceived": 12500, "taxableIncome": 5000 }, "gainsOnLifePolicies": { "incomeReceived": 12500, "taxableIncome": 5000, "totalUkGainsWithTaxPaid": 5000, "totalForeignGainsOnLifePoliciesWithTaxPaid": 5000 } }, "links": [ { "href": "/individuals/calculations/AA123456A/selfassessment/a54ba7825ef447f4ab72495406665ca9", "rel": "metadata", "method": "GET" }, { "href": "/individuals/calculations/AA123456A/selfassessment/a54ba7825ef447f4ab72495406665ca9/taxableincome", "rel": "self", "method": "GET" } ] }
Name  Description 

summary
object
required

Details the highlevel 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 selfemployment profit for all selfemployment 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 NonFHL 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 NonFHL profit. This value must be between 0 and 99999999999. No decimals.
For example: 
totalForeignPropertyProfit
number
optional

The total Foreign Property Profit. This value must be between 0 and 99999999999. No decimals.
For example: 
totalEeaFhlProfit
number
optional

The total EEA FHL Profit. This value must be between 0 and 99999999999. No decimals.
For example: 
totalOccupationalPensionIncome
number
optional

The total occupational pension income. This value must be between 0 and 99999999999.99 up to 2 decimal places.
For example: 
totalStateBenefitsIncome
number
optional

The total state benefits income. This value must be between 0 and 99999999999.99 up to 2 decimal places.
For example: 
totalBenefitsInKind
number
optional

The total benefits in kind. This value must be between 0 and 99999999999.99 up to 2 decimal places.
For example: 
totalPayeEmploymentAndLumpSumIncome
number
optional

The total PAYE employment and lump sum income. This value must be between 0 and 99999999999.99 up to 2 decimal places.
For example: 
totalEmploymentExpenses
number
optional

The total employment expenses. This value must be between 0 and 99999999999.99 up to 2 decimal places.
For example: 
totalSeafarersDeduction
number
optional

The total value of any Seafarers Deductions. This value must be between 0 and 99999999999.99 up to 2 decimal places.
For example: 
totalForeignTaxOnForeignEmployment
number
optional

The total value of foreign tax on foreign income. This value must be between 0 and 99999999999.99 up to 2 decimal places.
For example: 
totalEmploymentIncome
number
optional

The total employment and benefit income minus expenses. This value must be between 0 and 99999999999. No decimals.
For example: 
totalShareSchemesIncome
number
optional

The total share schemes income. This value must be between 0 and 99999999999.99 up to 2 decimal places.
For example: 
totalOverseasPensionsStateBenefitsRoyalties
number
optional

The total value of overseas pensions state benefits and royalties. This value must be between 0 and 99999999999.99 up to 2 decimal places.
For example: 
totalAllOtherIncomeReceivedWhilstAbroad
number
optional

The total value of all other income received whilst abroad. This value must be between 0 and 99999999999.99 up to 2 decimal places.
For example: 
totalOverseasIncomeAndGains
number
optional

The total value of overseas income and gains. This value must be between 0 and 99999999999.99 up to 2 decimal places.
For example: 
totalForeignBenefitsAndGifts
number
optional

The total value of foreign benefits and gifts. This value must be between 0 and 99999999999.99 up to 2 decimal places.
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 selfemployment business. 
selfEmploymentId
string
required

A unique identifier for the selfemployment business income source.
Must conform to the regular expression
For example: 
totalIncome
number
optional

The total income received for the selfemployment 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 selfemployment business. This value must be between 99999999999.99 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 selfemployment business. This value must be between 99999999999.99 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 selfemployment 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 selfemployment 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 selfemployment 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 selfemployment 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 selfemployment business. This value must be between 0 and 99999999999. No decimals.
For example: 
lossClaimsSummary
object
optional

Summarises losses and claims for the selfemployment 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 selfemployment 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 selfemployment business for the tax year of the calculation. This value must be between 0 and 99999999999. No decimals.
For example: 
carrySidewaysIncomeTaxLossesUsed
number
optional

The Income Tax losses for the selfemployment business that have been carried sideways in this 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 selfemployment 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 selfemployment 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 selfemployment 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 selfemployment 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 selfemployment 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 selfemployment 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 selfemployment business. 
lossType
string
required

The type of loss. Limited to the following possible values: income
class4nics

taxYearLossIncurred
string
required

The tax year of the loss. Format: YYYYYY
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 selfemployment 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: YYYYYY
For example: 
claimType
string
required

The type of loss claim that was made. Limited to the following possible values: carryforward
carrysideways

mtdLoss
boolean
required

Flag indicating the loss was registered by the taxpayer on joining MTD.
For example: 
taxYearLossIncurred
string
required

The tax year in which the loss was incurred. Date in the format: YYYYYY
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
class4nics

unclaimedLosses
array
optional

Losses from the selfemployment business from this calculation where no carry forward claim has been made 
taxYearLossIncurred
string
required

The tax year the loss arose. Format: YYYYYY
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
class4nics

carriedForwardLosses
array
optional

Losses from the selfemployment 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: carryforward

taxYearClaimMade
string
optional

The tax year in which the claim was made. Format: YYYYYY
For example: 
taxYearLossIncurred
string
required

The tax year of the loss. Format: YYYYYY
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
class4nics

claimsNotApplied
array
optional

Loss claims that could not be applied in this calculation for the selfemployment 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: YYYYYY
For example: 
claimType
string
required

The type of claim that was made. Limited to the following possible values: carrysideways
carryforward

bsas
object
optional

Details if the amounts in a Business Source Adjustable Summary adjustment for this selfemployment business have been used in this calculation. 
bsasId
string
required

The unique identifier of the Business Source Adjustable Summary for this selfemployment business.
Must conform to the regular expression
For example: 
applied
boolean
required

Flag indicating whether the amounts in the Business Source Adjustable Summary adjustment have been used in this calculation.
For example: 
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. This value must be between 99999999999.99 and 99999999999.99 up to 2 decimal places.
For example: 
netProfit
number
optional

If the total income is greater than the total expenses the result will be displayed in this field. This value 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 99999999999.99 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: 
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 NonFHL 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

The total sum of losses brought forward from previous years used against the taxable profit for UK Property NonFHL 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: YYYYYY
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: YYYYYY
For example: 
claimType
string
required

The type of claim made. Limited to the following possible values: carryforward

mtdLoss
boolean
required

Flag indicating whether the loss was registered by the taxpayer on joining MTD.
For example: 
taxYearLossIncurred
string
required

The tax year in which the loss was incurred. Date in the format: YYYYYY
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: YYYYYY
For example: 
currentLossValue
number
required

The current loss value. This value must be between 0 and 99999999999. No decimals.
For example: 
bsas
object
optional

Details if the amounts in a Business Source Adjustable Summary adjustment for UK Property FHL have been used in this calculation. 
bsasId
string
required

The unique identifier of the Business Source Adjustable Summary for UK Property FHL.
Must conform to the regular expression
For example: 
applied
boolean
required

Flag indicating whether the amounts in the Business Source Adjustable Summary adjustment have been used in this calculation.
For example: 
ukPropertyNonFhl
object
optional

Details the profit and loss position for UK Property NonFHL. 
totalIncome
number
optional

The total income received for UK Property NonFHL. 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 NonFHL. This value must be between 99999999999.99 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 NonFHL. This value must be between 99999999999.99 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 NonFHL. 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 NonFHL. 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 NonFHL. 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 NonFHL. 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 NonFHL. This value must be between 0 and 99999999999. No decimals.
For example: 
lossClaimsSummary
object
optional

Summarises losses and claims for UK Property NonFHL 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 NonFHL. This value must be between 0 and 99999999999. No decimals.
For example: 
broughtForwardIncomeTaxLossesUsed
number
optional

The total sum of losses brought forward from previous years used against the taxable profit for UK Property NonFHL for the tax year of the calculation. This value must be between 0 and 99999999999. No decimals.
For example: 
carrySidewaysIncomeTaxLossesUsed
number
optional

The Income Tax losses for UK Property NonFHL that have been carried sideways in this 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 NonFHL profits for the tax year of the calculation. This value must be between 0 and 99999999999. No decimals.
For example: 
broughtForwardCarrySidewaysIncomeTaxLossesUsed
number
optional

The total sum of the carry sideways losses for UK Property NonFHL brought forward from previous tax years. 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 NonFHL. 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 NonFHL. 
taxYearLossIncurred
string
required

The tax year of the loss. Format: YYYYYY
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 NonFHL 
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 carrysidewaysfhl/carrysideways 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: YYYYYY
For example: 
claimType
string
required

The type of claim that was made. Limited to the following possible values: carryforward
carrysideways
carryforwardtocarrysideways
carrysidewaysfhl

mtdLoss
boolean
required

Flag indicating the loss was registered by the taxpayer on joining MTD.
For example: 
taxYearLossIncurred
string
optional

The tax year in which the loss was incurred. Format: YYYYYY
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 NonFHL losses from this calculation that will be carried forward to the next tax year. 
taxYearLossIncurred
string
required

The tax year of the loss. Format: YYYYYY
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 NonFHL. 
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: YYYYYY
For example: 
claimType
string
required

The type of claim that was made. Limited to the following possible values: carrysideways
carrysidewaysfhl
carryforward
carryforwardtocarrysideways

bsas
object
optional

Details if the amounts in a Business Source Adjustable Summary adjustment for UK Property NonFHL have been used in this calculation. 
bsasId
string
required

The unique identifier of the Business Source Adjustable Summary for UK Property NonFHL.
Must conform to the regular expression
For example: 
applied
boolean
required

Flag indicating whether the amounts in the Business Source Adjustable Summary adjustment have been used in this calculation.
For example: 
eeaPropertyFhl
object
optional

Details the profit and loss position for EEA Property FHL. 
totalIncome
number
optional

The total income received for EEA 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 EEA Property FHL. This value must be between 99999999999.99 and 99999999999.99 up to 2 decimal places.
For example: 
netProfit
number
optional

If the total income is greater than the total expenses the result will be displayed in this field. This value 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 EEA Property FHL. This value must be between 99999999999.99 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 EEA Property FHL. This value must be between 0 and 99999999999.99 up to 2 decimal places.
For example: 
taxableProfit
number
optional

The taxable profit after all additions and deductions have been applied for EEA 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 EEA 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 EEA Property FHL. This value must be between 0 and 99999999999. No decimals.
For example: 
bsas
object
optional

Details if the amounts in a Business Source Adjustable Summary adjustment for EEA Property FHL have been used in this calculation 
bsasId
string
required

The unique identifier of the Business Source Adjustable Summary for EEA Property FHL.
Must conform to the regular expression
For example: 
applied
boolean
required

Flag indicating whether the amounts in the Business Source Adjustable Summary adjustment have been used in this calculation.
For example: 
links
array
optional

A list of endpoint links that indicate possible Business Source Adjustable Summary related actions. 
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: retrieveforeignpropertyaccountingadjustments

method
string
required

The HTTP method type for the endpoint Limited to the following possible values: GET

lossClaimsSummary
object
optional

Summarises losses and claims for the EEA Property FHL. This section will only be present for a crystallisation calculation 
lossForCSFHL
number
optional

The losses from Foreign Property that have been carried sideways to EEA 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 EEA 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 EEA 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 EEA 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 EEA 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 EEA Property FHL. 
taxYearLossIncurred
string
required

The tax year of the loss. Format: YYYYYY
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 EEA 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: YYYYYY
For example: 
claimType
string
required

The type of claim made. Limited to the following possible values: carryforward

mtdLoss
boolean
required

Flag indicating the loss was registered by the taxpayer on joining MTD.
For example: 
taxYearLossIncurred
string
required

The tax year in which the loss was incurred. Date in the format: YYYYYY
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

EEA 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: YYYYYY
For example: 
currentLossValue
number
required

The current loss value. This value must be between 0 and 99999999999. No decimals.
For example: 
foreignProperty
object
optional

Details the profit and loss position for Foreign Property. 
totalIncome
number
optional

The total income received for Foreign Property. This value must be between 0 and 99999999999.99 up to 2 decimal places.
For example: 
totalExpenses
number
optional

The total expenses for Foreign Property. This value must be between 99999999999.99 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 Foreign Property. This value must be between 99999999999.99 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 Foreign Property. 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 Foreign Property. 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 Foreign Property. 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 Foreign Property. 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 Foreign Property. This value must be between 0 and 99999999999. No decimals.
For example: 
bsas
object
optional

Details if the amounts in a Business Source Adjustable Summary adjustment for Foreign Property have been used in this calculation 
bsasId
string
required

The unique identifier of the Business Source Adjustable Summary for Foreign Property.
Must conform to the regular expression
For example: 
applied
boolean
required

Flag indicating whether the amounts in the Business Source Adjustable Summary adjustment have been used in this calculation.
For example: 
links
array
optional

A list of endpoint links that indicate possible Business Source Adjustable Summary related actions. 
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: retrieveforeignpropertyaccountingadjustments

method
string
required

The HTTP method type for the endpoint Limited to the following possible values: GET

lossClaimsSummary
object
optional

Summarises losses and claims for Foreign Property. 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 Foreign Property. This value must be between 0 and 99999999999. No decimals.
For example: 
broughtForwardIncomeTaxLossesUsed
number
optional

The total sum of losses brought forward from previous years used against the taxable profit for Foreign Property for the tax year of the calculation. This value must be between 0 and 99999999999. No decimals.
For example: 
carrySidewaysIncomeTaxLossesUsed
number
optional

The Income Tax losses for Foreign Property that have been carried sideways in this calculation and used against general income in this financial year. This value must be between 0 and 99999999999. No decimals.
For example: 
broughtForwardCarrySidewaysIncomeTaxLossesUsed
number
optional

The total sum of the carry sideways losses for Foreign Property brought forward from previous tax years. 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 Foreign Property 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 Foreign Property. This section will only be present for a crystallisation calculation. 
lossesBroughtForward
array
optional

A list of losses brought forward into this calculation for Foreign Property. 
taxYearLossIncurred
string
required

The tax year of the loss. Format: YYYYYY
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 Foreign Property. 
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 carrysidewaysfhl or carrysideways 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: YYYYYY
For example: 
claimType
string
required

The type of claim made. Limited to the following possible values: carryforward
carrysideways
carryforwardtocarrysideways
carrysidewaysfhl

mtdLoss
boolean
required

Flag indicating the loss was registered by the taxpayer on joining MTD.
For example: 
taxYearLossIncurred
string
required

The tax year of the loss. Format: YYYYYY
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

Foreign Property losses from this calculation that will be carried forward to the next tax year. 
taxYearLossIncurred
string
required

The tax year of the loss. Format: YYYYYY
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 Foreign Property. 
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: YYYYYY
For example: 
claimType
string
required

The type of claim that was made. Limited to the following possible values: carryforward
carrysideways
carryforwardtocarrysideways
carrysidewaysfhl

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: 
totalOfAllGains
number
required

The total of all gains without tax paid and gains with tax paid. This value must be between 0 and 99999999999. No decimals.
For example: 
totalUkSavingsAndSecurities
number
optional

The total value of UK Savings and UK Securities. This value must be between 0 and 99999999999. No decimals.
For example: 
totalUkSavingsAndGains
number
optional

The total value of UK Savings and UK Securities. This value must be between 0 and 99999999999. No decimals.
For example: 
ukSavings
array
optional

Details of each savings account. 
savingsAccountId
string
optional

The unique identifier of the savings account.
Must conform to the regular expression
For example: 
savingsAccountName
string
optional

Friendly account name. Each account name added must be unique for that National Insurance number. The account name must be between 1 and 32 characters in length. Valid characters, including spaces are: ; & ' ( ) * ,  . / @ £ and mixed case alphanumeric 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: 
ukSecurities
array
optional

Details of UK Securities accounts. 
ukSecuritiesAccountId
string
optional

The unique identifier of the UK securities account.
Must conform to the regular expression
For example: 
ukSecuritiesAccountName
string
optional

Friendly account name. Each account name added must be unique for that National Insurance number. The account name must be between 1 and 32 characters in length. Valid characters, including spaces are: ; & ' ( ) * ,  . / @ £ and mixed case alphanumeric characters.
Must conform to the regular expression
For example: 
grossIncome
number
required

The gross interest received from UK securities 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 UK securities 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 UK securities account (gross figure minus the net figure). The value must be between 0 and 999999999999.99 up to 2 decimal places.
For example: 
totalGainsWithNoTaxPaidAndVoidedIsa
number
optional

The total gains on life policies where no tax has been paid and voided ISAs. This value must be between 0 and 99999999999. No decimals.
For example: 
totalForeignGainsOnLifePoliciesNoTaxPaid
number
optional

The total gains on foreign life policies where no tax has been paid. This value must be between 0 and 99999999999. No decimals.
For example: 
totalForeignSavingsAndGainsIncome
number
optional

The total value of Foreign Savings and Gains Income. This value must be between 0 and 99999999999. No decimals.
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: 
totalUkDividends
number
optional

The total value of UK Dividends. This value must be between 0 and 99999999999. No decimals.
For example: 
totalForeignDividends
number
optional

The total value of Foreign Dividends. This value must be between 0 and 99999999999. No decimals.
For example: 
lumpSums
object
optional

Details of lump sums income. 
incomeReceived
number
required

The lump sums income received. This value must be between 0 and 99999999999. No decimals.
For example: 
taxableIncome
number
required

The taxable lump sums income. This value must be between 0 and 99999999999. No decimals.
For example: 
gainsOnLifePolicies
object
optional

Details of gains on life policies income. 
incomeReceived
number
required

The gains on life policies income received. This value must be between 0 and 99999999999. No decimals.
For example: 
taxableIncome
number
required

The taxable gains on life policies income. This value must be between 0 and 99999999999. No decimals.
For example: 
totalUkGainsWithTaxPaid
number
optional

The total value of UK gains on life policies with tax paid. This value must be between 0 and 99999999999. No decimals.
For example: 
totalForeignGainsOnLifePoliciesWithTaxPaid
number
optional

The total value of foreign gains on life policies with tax paid. 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 GovTestScenario headers is only available in the sandbox environment.
Header Value (GovTestScenario)  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 NonFHL Property business with Dividends. 
UK_PROP_GIFTAID_EXAMPLE 
Simulates an example tax calculation with realistic data values, for a UK NonFHL Property business with Gift Aid. 
UK_PROP_SAVINGS_EXAMPLE 
Simulates an example tax calculation with realistic data values, for a UK NonFHL Property business with Savings. 
UK_SE_GIFTAID_EXAMPLE 
Simulates an example tax calculation with realistic data values, for a UK SelfEmployment business with Gift Aid. 
UK_SE_SAVINGS_EXAMPLE 
Simulates an example tax calculation with realistic data values, for a UK SelfEmployment business with Savings. 
SCOT_SE_DIVIDENDS_EXAMPLE 
Simulates an example tax calculation with realistic data values, for a Scottish SelfEmployment business with Dividends. 
/individuals/calculations/{nino}/selfassessment/{calculationId}/allowancesdeductionsreliefs
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
userrestricted
and requires an Authorization
header containing an OAuth 2.0 Bearer Token with the read:selfassessment
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.2.0+json

GovTestScenario
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:selfassessment scope.
For example: Bearer bb7fed3fe10dd235a2ccda3d50fb

See also fraud prevention.
Response headers
Name  Description 

XCorrelationId
required

Unique ID for operation tracking For example: c75f40a6a3df4429a697471eeec46435

See also fraud prevention.
Response
HTTP status: 200 (OK)
{ "summary": { "totalAllowancesAndDeductions": 1000, "totalReliefs": 1000.25 }, "detail": { "allowancesAndDeductions": { "personalAllowance": 1000, "reducedPersonalAllowance": 1000, "giftOfInvestmentsAndPropertyToCharity": 1000, "blindPersonsAllowance": 1000, "lossesAppliedToGeneralIncome": 1000, "qualifyingLoanInterestFromInvestments": 2000.58, "postCessationTradeReceipts": 2000.58, "paymentsToTradeUnionsForDeathBenefits": 2000.58, "annualPayments": { "grossAnnualPayments": 2000.58, "reliefClaimed": 2000.58, "rate": 10.25 }, "pensionContributions": { "totalPensionContributions": 2000.58, "retirementAnnuityPayments": 2000.58, "paymentToEmployersSchemeNoTaxRelief": 2000.58, "overseasPensionSchemeContributions": 2000.58 } }, "reliefs": { "residentialFinanceCosts": { "adjustedTotalIncome": 49820.34, "totalAllowableAmount": 49821.34, "relievableAmount": 49822.34, "rate": 45.34, "totalResidentialFinanceCostsRelief": 49823.34, "ukProperty": { "amountClaimed": 49824.34, "allowableAmount": 49825.34, "carryForwardAmount": 49826.34 }, "foreignProperty": { "totalForeignPropertyAllowableAmount": 49827.34, "foreignPropertyRfcDetail": [ { "countryCode": "ASM", "amountClaimed": 49829, "allowableAmount": 49828.34, "carryForwardAmount": 49830.34 } ] }, "allOtherIncomeReceivedWhilstAbroad": { "totalOtherIncomeAllowableAmount": 49831.34, "otherIncomeRfcDetail": [ { "countryCode": "ASM", "residentialFinancialCostAmount": 49833.34, "broughtFwdResidentialFinancialCostAmount": 49832.34 } ] } }, "foreignTaxCreditRelief": { "customerCalculatedRelief": true, "totalForeignTaxCreditRelief": 8019.25, "foreignTaxCreditReliefOnProperty": 8020.25, "foreignTaxCreditReliefOnDividends": 8021.25, "foreignTaxCreditReliefOnSavings": 8022.25, "foreignTaxCreditReliefOnForeignIncome": 8023.25 }, "pensionContributionReliefs": { "totalPensionContributionReliefs": 2000.58, "regularPensionContributions": 2000.58, "oneOffPensionContributionsPaid": 2000.58 }, "reliefsClaimed": [ { "type": "vctSubscriptions", "amountClaimed": 2000.58, "allowableAmount": 2000.58, "amountUsed": 2000.58, "rate": 20 } ] } }, "links": [ { "href": "/individuals/calculations/RW399019B/selfassessment/f2fb30e54ab64a29b3c1c7264259ff1c/allowancesdeductionsreliefs", "rel": "self", "method": "GET" }, { "href": "/individuals/calculations/RW399019B/selfassessment/f2fb30e54ab64a29b3c1c7264259ff1c", "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: 
qualifyingLoanInterestFromInvestments
number
optional

Qualifying loan interest payments made. This value must be between 0 and 99999999999.99 up to 2 decimal places.
For example: 
postCessationTradeReceipts
number
optional

Trade reliefs and other losses post cessation of a business. This value must be between 0 and 99999999999.99 up to 2 decimal places.
For example: 
paymentsToTradeUnionsForDeathBenefits
number
optional

Payments made to a Trade union or friendly society for death benefits. This value must be between 0 and 99999999999.99 up to 2 decimal places.
For example: 
annualPayments
object
optional

Details of any annual payments made. 
grossAnnualPayments
number
optional

The gross value of annual payments made. This value must be between 0 and 99999999999.99 up to 2 decimal places.
For example: 
reliefClaimed
number
optional

The value of annual payments made. This value must be between 0 and 99999999999.99 up to 2 decimal places.
For example: 
rate
number
optional

The tax rate used in the calculation. This value must be between 0 and 99.99 up to 2 decimal places.
For example: 
pensionContributions
object
optional

Details of any pension contributions made. 
totalPensionContributions
number
optional

The value of pension contributions made. This value must be between 0 and 99999999999.99 up to 2 decimal places.
For example: 
retirementAnnuityPayments
number
optional

The value of retirement annuity payments. This value must be between 0 and 99999999999.99 up to 2 decimal places.
For example: 
paymentToEmployersSchemeNoTaxRelief
number
optional

Payments to employers pension scheme with no tax relief. This value must be between 0 and 99999999999.99 up to 2 decimal places.
For example: 
overseasPensionSchemeContributions
number
optional

The value of contributions to an overseas pension scheme. This value must be between 0 and 99999999999.99 up to 2 decimal places.
For example: 
reliefs
object
optional

Details the reliefs used in the calculation. 
residentialFinanceCosts
object
optional

Details the total residential finance cost reliefs used in the calculation. 
adjustedTotalIncome
number
required

The income (after losses and reliefs, and excluding savings and dividends income) that exceeds your personal allowance. This value must be between 0 and 99999999999.99 up to 2 decimal places.
For example: 
totalAllowableAmount
number
optional

The total allowable amount. This value must be between 0 and 99999999999.99 up to 2 decimal places.
For example: 
relievableAmount
number
required

The lower of either Adjusted Total Income or Total Allowable Amount. This value must be between 0 and 99999999999.99 up to 2 decimal places.
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: 
totalResidentialFinanceCostsRelief
number
required

The total value of residential finance costs relief. This value must be between 0 and 99999999999.99 up to 2 decimal places.
For example: 
ukProperty
object
optional

Details the residential finance costs for UK property. 
amountClaimed
number
required

The total amount claimed for residential finance costs. This value must be between 0 and 99999999999.99 up to 2 decimal places.
For example: 
allowableAmount
number
required

The total amount allowable for residential finance costs. This value must be between 0 and 99999999999.99 up to 2 decimal places.
For example: 
carryForwardAmount
number
optional

The amount of residential finance costs that can be carried forward to future tax years. This value must be between 0 and 99999999999.99 up to 2 decimal places.
For example: 
foreignProperty
object
optional

Details the residential finance costs for foreign property. 
totalForeignPropertyAllowableAmount
number
required

The total amount allowable for all foreign property residential finance costs. This value must be between 0 and 99999999999.99 up to 2 decimal places.
For example: 
foreignPropertyRfcDetail
array
required

Details residential finance costs for foreign property broken down by country. 
countryCode
string
required

A threeletter code that represents a country name. The value must be ISO 31661 alpha3
For example: 
amountClaimed
number
required

The total amount claimed for residential finance costs. This value must be between 0 and 99999999999.99. No decimals.
For example: 
allowableAmount
number
required

The total amount allowable for residential finance costs. This value must be between 0 and 99999999999.99 up to 2 decimal places.
For example: 
carryForwardAmount
number
optional

The amount of residential finance costs that can be carried forward to future tax years. This value must be between 0 and 99999999999.99 up to 2 decimal places.
For example: 
allOtherIncomeReceivedWhilstAbroad
object
optional

Details the residential finance costs for other income received whilst abroad. 
totalOtherIncomeAllowableAmount
number
required

The total amount allowable for all other income received whilst abroad for residential finance costs. This value must be between 0 and 99999999999.99 up to 2 decimal places.
For example: 
otherIncomeRfcDetail
array
required

Details residential finance costs for other income broken down by country. 
countryCode
string
required

A threeletter code that represents a country name. The value must be ISO 31661 alpha3
For example: 
residentialFinancialCostAmount
number
optional

The total amount claimed for residential finance costs. This value must be between 0 and 99999999999.99 up to 2 decimal places.
For example: 
broughtFwdResidentialFinancialCostAmount
number
optional

The amount of residential financial costs brought forward from previous tax years. This value must be between 0 and 99999999999.99 up to 2 decimal places.
For example: 
foreignTaxCreditRelief
object
optional

Details the foreign tax credit relief (FTCR) used in the calculation. 
customerCalculatedRelief
boolean
optional

When this field is true, it means the customer has calculated their own relief. When it is false it means HMRC determined the relief.
For example: 
totalForeignTaxCreditRelief
number
required

The total value of foreign tax credit relief. This value must be between 0 and 99999999999.99 up to 2 decimal places.
For example: 
foreignTaxCreditReliefOnProperty
number
optional

The value of foreign tax credit relief on property. This value must be between 0 and 99999999999.99 up to 2 decimal places.
For example: 
foreignTaxCreditReliefOnDividends
number
optional

The value of foreign tax credit relief on dividends. This value must be between 0 and 99999999999.99 up to 2 decimal places.
For example: 
foreignTaxCreditReliefOnSavings
number
optional

The value of foreign tax credit relief on savings. This value must be between 0 and 99999999999.99 up to 2 decimal places.
For example: 
foreignTaxCreditReliefOnForeignIncome
number
optional

The value of foreign tax credit relief on foreign income. This value must be between 0 and 99999999999.99 up to 2 decimal places.
For example: 
pensionContributionReliefs
object
optional

Details the pension contribution reliefs used in the calculation. 
totalPensionContributionReliefs
number
required

The total value of pension contribution reliefs made. This value must be between 0 and 99999999999.99 up to 2 decimal places.
For example: 
regularPensionContributions
number
optional

The total value of regular pension contributions made. This value must be between 0 and 99999999999.99 up to 2 decimal places.
For example: 
oneOffPensionContributionsPaid
number
optional

The total value of oneoff pension contributions made. This value must be between 0 and 99999999999.99 up to 2 decimal places.
For example: 
reliefsClaimed
array
optional

Details of investment and other reliefs used in the calculation. 
type
string
required

The type of relief claimed. Limited to the following possible values: vctSubscriptions
eisSubscriptions
communityInvestment
seedEnterpriseInvestment
socialEnterpriseInvestment
maintenancePayments
deficiencyRelief
nonDeductibleLoanInterest
qualifyingDistributionRedemptionOfSharesAndSecurities

amountClaimed
number
optional

The amount of relief claimed. This value must be between 0 and 99999999999.99 up to 2 decimal places.
For example: 
allowableAmount
number
optional

The amount of allowable relief. This value must be between 0 and 99999999999.99 up to 2 decimal places.
For example: 
amountUsed
number
optional

The amount of relief used. This value must be between 0 and 99999999999.99 up to 2 decimal places.
For example: 
rate
number
optional

The rate associated with the relief claimed. This value must be between 0 and 99.99 up to 2 decimal places.
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 GovTestScenario headers is only available in the sandbox environment.
Header Value (GovTestScenario)  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 NonFHL Property business with Dividends. 
UK_PROP_GIFTAID_EXAMPLE 
Simulates an example tax calculation with realistic data values, for a UK NonFHL Property business with Gift Aid. 
UK_PROP_SAVINGS_EXAMPLE 
Simulates an example tax calculation with realistic data values, for a UK NonFHL Property business with Savings. 
UK_SE_SAVINGS_EXAMPLE 
Simulates an example tax calculation with realistic data values, for a UK SelfEmployment business with Savings. 
SCOT_SE_DIVIDENDS_EXAMPLE 
Simulates an example tax calculation with realistic data values, for a Scottish SelfEmployment business with Dividends. 
/individuals/calculations/{nino}/selfassessment/{calculationId}/endofyearestimate
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 Inyear 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
userrestricted
and requires an Authorization
header containing an OAuth 2.0 Bearer Token with the read:selfassessment
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.2.0+json

GovTestScenario
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:selfassessment scope.
For example: Bearer bb7fed3fe10dd235a2ccda3d50fb

See also fraud prevention.
Response headers
Name  Description 

XCorrelationId
required

Unique ID for operation tracking For example: c75f40a6a3df4429a697471eeec46435

See also fraud prevention.
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, "totalStudentLoansRepaymentAmount": 2000.95, "totalAnnualPaymentsTaxCharged": 2000.95, "totalRoyaltyPaymentsTaxCharged": 2000.95, "totalTaxDeducted": 2000.58 }, "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 }, "otherDividends": { "taxableIncome": 2000 }, "foreignCompanyDividends": { "taxableIncome": 2000 }, "stateBenefits": { "taxableIncome": 2000 }, "ukSecurities": { "taxableIncome": 2000 }, "foreignProperty": { "taxableIncome": 2000, "finalised": false }, "eeaPropertyFhl": { "taxableIncome": 2000 }, "foreignInterest": { "taxableIncome": 2000 }, "otherIncome": { "taxableIncome": 2000 }, "foreignPension": { "taxableIncome": 2000 } }, "links": [{ "href": "/individuals/calculations/RW399019B/selfassessment/f2fb30e54ab64a29b3c1c7264259ff1c/endofyearestimate", "rel": "self", "method": "GET" }, { "href": "/individuals/calculations/RW399019B/selfassessment/f2fb30e54ab64a29b3c1c7264259ff1c", "rel": "metadata", "method": "GET" } ] }
Name  Description 

summary
object
optional

Details the highlevel 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 endofyear combined Income Tax, Class 2 and Class 4 National Insurance contributions amount. This value must be between 99999999999.99 and 99999999999.99
For example: 
totalStudentLoansRepaymentAmount
number
optional

The estimated endofyear student loans repayment amount. This value must be between 0 and 99999999999.99 up to 2 decimal places.
For example: 
totalAnnualPaymentsTaxCharged
number
optional

The estimated endofyear annual payments tax charged amount. This value must be between 0 and 99999999999.99 up to 2 decimal places.
For example: 
totalRoyaltyPaymentsTaxCharged
number
optional

The estimated endofyear royalty payments tax charged amount. This value must be between 0 and 99999999999.99 up to 2 decimal places.
For example: 
totalTaxDeducted
number
optional

The estimated endofyear total tax deducted amount. This value must be between 99999999999.99 and 99999999999.99
For example: 
detail
object
optional

Details the lowlevel taxable income amounts of each income source 
selfEmployments
array
optional

A list of selfemployment business detailing the taxable income estimate for each business 
selfEmploymentId
string
required

An identifier for the selfemployment 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 selfemployment 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 NonFHL 
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 NonFHL 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: 
otherDividends
object
optional

Details the taxable income estimate for other dividends 
taxableIncome
number
required

The estimated endofyear taxable income. This value must be between 0 and 99999999999. No decimals.
For example: 
foreignCompanyDividends
object
optional

Details the taxable income estimate for foreign company dividends. 
taxableIncome
number
required

The estimated endofyear taxable income. This value must be between 0 and 99999999999. No decimals.
For example: 
stateBenefits
object
optional

Details the taxable income estimate for state benefits 
taxableIncome
number
required

The estimated endofyear taxable income. This value must be between 0 and 99999999999. No decimals.
For example: 
ukSecurities
object
optional

Details the taxable income estimate for UK Securities 
taxableIncome
number
required

The estimated endofyear taxable income. This value must be between 0 and 99999999999. No decimals.
For example: 
foreignProperty
object
optional

Details the taxable income estimate for Foreign Property 