This version is in beta - expect some breaking changes.

Individual Calculations (MTD) API

Dates and amounts
Date Amount
Version and status
Available in Sandbox Yes
Sandbox base URL https://test-api.service.hmrc.gov.uk
Available in Production Yes
Production base URL https://api.service.hmrc.gov.uk

Overview

This API allows a developer to:

  • trigger a customer’s self-assessment tax calculation
  • list a customer’s self-assessment tax calculations for a tax year
  • retrieve a customer’s self-assessment tax calculation result using multiple endpoints
  • provide the customer’s intent to make a final declaration, for which they will receive a Calculation ID
  • submit a final declaration for a tax year

For information on how to connect to this API see the Income Tax MTD end-to-end service guide.

Versioning

When an API changes in a way that is backwards-incompatible, we increase the version number of the API. See our reference guide for more on versioning.

Errors

We use standard HTTP status codes to show whether an API request succeeded or not. They are usually in the range:

  • 200 to 299 if it succeeded, including code 202 if it was accepted by an API that needs to wait for further action
  • 400 to 499 if it failed because of a client error by your application
  • 500 to 599 if it failed because of an error on our server

Errors specific to each API are shown in the Endpoints section, under Response. See our reference guide for more on errors.

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 income-tax-mtd-changelog GitHub wiki.

Support

Testing

You can use the sandbox environment to test this API. You can use the Create Test User API or it's frontend service to create test users.

It may not be possible to test all scenarios in the sandbox. You can test some scenarios by passing the Gov-Test-Scenario header. Documentation for each endpoint includes a Test data section, which explains the scenarios that you can simulate using the Gov-Test-Scenario header.

If you have a specific testing need that is not supported in the sandbox, contact our support team.

Some APIs may be marked [test only]. This means that they are not available for use in production and may change.

Skip to main content

Endpoints

Self Assessment

Here a developer can:

  • list self-assessment tax calculations for a given National Insurance number (NINO) and tax year
  • trigger a self-assessment tax calculation for a given tax year. The result of the calculation can be explored via the “Retrieve a self-assessment tax calculation metadata” endpoint
  • retrieve high-level calculation metadata for a given Calculation ID
  • retrieve the calculated Income Tax and National Insurance contributions for a given NINO and Calculation ID
  • retrieve the taxable income that has been used in the self-assessment tax calculation for a given NINO and Calculation ID
  • retrieve the allowances, deductions and reliefs that exist for the self assessment tax calculation for a given NINO and Calculation ID
  • retrieve the end-of-year Income Tax and National Insurance contribution estimates for a given NINO and Calculation ID
  • retrieve “info”, “warning” and “error” level messages linked to a Calculation ID

Self Assessment resources

/individuals/calculations/{nino}/self-assessment

List Self Assessment Tax Calculations
GET

The “List Self Assessment tax calculations” endpoint allows users to list their Self Assessment tax calculations for the supplied NINO and given tax year.

Authorisation

This endpoint is user-restricted and requires an Authorization header containing an OAuth 2.0 Bearer Token with the read:self-assessment scope.

Path parameters

Path parameters table
Name Description
nino
string
required

National Insurance number, in the format AA999999A.

For example: TC663795B

Query parameters

Query parameters table
Name Description
taxYear
string
optional

The tax year the data applies to, for example, 2019-20. Calculations for the current tax year are returned if no tax year is supplied.

The start year and end year must not span two tax years. No gaps are allowed, for example, 2019-21 is not valid. The earliest tax year is 2017-18.

For example: 2017-18

Request headers

Request headers Table
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
Gov-Test-Scenario
optional

Only in sandbox environment. See Test Data table for all header values.

For example: -
Authorization
required
An OAuth 2.0 Bearer Token with the read:self-assessment scope.

For example: Bearer bb7fed3fe10dd235a2ccda3d50fb

See also fraud prevention.

Response headers

Response headers Table
Name Description
X-CorrelationId
required

Unique ID for operation tracking
String, 36 characters.

For example: c75f40a6-a3df-4429-a697-471eeec46435

See also fraud prevention.

Response

HTTP status: 200 (OK)

{
  "calculations": [
    {
      "id": "f2fb30e5-4ab6-4a29-b3c1-c7264259ff1c",
      "calculationTimestamp": "2019-03-17T09:22:59Z",
      "type": "inYear",
      "requestedBy": "hmrc",
      "links": [
        {
          "href": "/individuals/calculations/RW399019B/self-assessment/f2fb30e5-4ab6-4a29-b3c1-c7264259ff1c",
          "rel": "self",
          "method": "GET"
        }
      ]
    },
    {
      "id": "cf63c46a-1a4f-3c56-b9ea-9a82551d27bb",
      "calculationTimestamp": "2019-06-17T18:45:59Z",
      "type": "crystallisation",
      "requestedBy": "customer",
      "links": [
        {
          "href": "/individuals/calculations/RW399019B/self-assessment/cf63c46a-1a4f-3c56-b9ea-9a82551d27bb",
          "rel": "self",
          "method": "GET"
        }
      ]
    }
  ],
  "links": [
    {
      "href": "/individuals/calculations/RW399019B/self-assessment",
      "rel": "self",
      "method": "GET"
    },
    {
      "href": "/individuals/calculations/RW399019B/self-assessment",
      "rel": "trigger",
      "method": "POST"
    }
  ]
}

Response table
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 ^[0-9]{8}|[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$

For example: f2fb30e5-4ab6-4a29-b3c1-c7264259ff1c

calculationTimestamp
string
required

The timestamp of when the calculation was performed in ISO8601 UTC format: YYYY-MM-DDThh:mm:ssZ.

For example: 2019-06-17T09:22:59Z

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: /individuals/calculations/{nino}/self-assessment/{calculationId}

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: /individuals/calculations/{nino}/self-assessment

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

Error scenarios table
Scenario HTTP status Code

The format of the supplied NINO is not valid

400 (Bad Request)

FORMAT_NINO

The format of the supplied tax year field is not valid

400 (Bad Request)

FORMAT_TAX_YEAR

The specified tax year is not supported. That is, the tax year specified is before the minimum tax year value.

400 (Bad Request)

RULE_TAX_YEAR_NOT_SUPPORTED

Tax year range invalid. A tax year range of one year is required.

400 (Bad Request)

RULE_TAX_YEAR_RANGE_INVALID

The client and/or agent is not authorised. This is normally because: the client is not subscribed to MTD, the agent is not subscribed to Agent Services, or the client has not authorised the agent to act on their behalf.

403 (Forbidden)

CLIENT_OR_AGENT_NOT_AUTHORISED

No tax calculations can be found for the supplied NINO and tax year.

404 (Not Found)

MATCHING_RESOURCE_NOT_FOUND

For error scenarios that are common across all APIs, and for error formats, see our reference guide.

Test data

Scenario simulations using Gov-Test-Scenario headers is only available in the sandbox environment.

Header Value (Gov-Test-Scenario) Scenario

N/A - DEFAULT

Simulate success scenario for self-employment

CRYSTALLISATION

Simulate success scenario where a crystallisation calculation is found

MULTIPLE_CALCULATIONS

Simulate success scenario where multiple tax calculations are found

NOT_FOUND

Simulates the scenario where no tax calculations could be found for the supplied NINO and tax year


Close Section
/individuals/calculations/{nino}/self-assessment

Trigger a Self Assessment Tax Calculation
POST

This endpoint allows the user to trigger a self-assessment tax calculation for a given tax year. It should be called whenever income data is updated through a periodic or annual endpoint. 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 user-restricted and requires an Authorization header containing an OAuth 2.0 Bearer Token with the write:self-assessment scope.

Path parameters

Path parameters table
Name Description
nino
string
required

National Insurance number, in the format AA999999A.

For example: TC663795B

Request headers

Request headers Table
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
Content-Type
required

Specifies the format of the request body, which must be JSON.

For example: application/json
Gov-Test-Scenario
optional

Only in sandbox environment. See Test Data table for all header values.

For example: -
Authorization
required
An OAuth 2.0 Bearer Token with the write:self-assessment scope.

For example: Bearer bb7fed3fe10dd235a2ccda3d50fb

See also fraud prevention.

Request

{
  "taxYear": "2017-18"
}

Request table
Name Description
taxYear
string
required

The tax year that the calculation is being triggered for. The start year and end year must not span two tax years. No gaps are allowed, for example, 2019-21 is not valid. The minimum tax year is 2017-18.

For example: 2019-20

Response headers

Response headers Table
Name Description
X-CorrelationId
required

Unique ID for operation tracking
String, 36 characters.

For example: c75f40a6-a3df-4429-a697-471eeec46435

See also fraud prevention.

Response

HTTP status: 202 (Accepted)

{
  "id": "f2fb30e5-4ab6-4a29-b3c1-c7264259ff1c",
  "links": [
    {
      "href": "/individuals/calculations/RW399019B/self-assessment/f2fb30e5-4ab6-4a29-b3c1-c7264259ff1c",
      "rel": "self",
      "method": "GET"
    }
  ]
}

Response table
Name Description
id
string
required

The unique identifier of the calculation.

Must conform to the regular expression ^[0-9]{8}|[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$

For example: f2fb30e5-4ab6-4a29-b3c1-c7264259ff1c

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: /individuals/calculations/{nino}/self-assessment/{calculationId}

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

Error scenarios table
Scenario HTTP status Code

The format of the supplied NINO is not valid

400 (Bad Request)

FORMAT_NINO

The format of the supplied tax year field is not valid

400 (Bad Request)

FORMAT_TAX_YEAR

The specified tax year is not supported. That is, the tax year specified is before the minimum tax year value.

400 (Bad Request)

RULE_TAX_YEAR_NOT_SUPPORTED

Tax year range invalid. A tax year range of one year is required.

400 (Bad Request)

RULE_TAX_YEAR_RANGE_INVALID

An empty or non-matching body was submitted, this could be caused by a missing mandatory field

400 (Bad Request)

RULE_INCORRECT_OR_EMPTY_BODY_SUBMITTED

The client and/or agent is not authorised. This is normally because: the client is not subscribed to MTD, the agent is not subscribed to Agent Services, or the client has not authorised the agent to act on their behalf.

403 (Forbidden)

CLIENT_OR_AGENT_NOT_AUTHORISED

A calculation could not be performed because no income data has been submitted against the tax year

403 (Forbidden)

RULE_NO_INCOME_SUBMISSIONS_EXIST

For error scenarios that are common across all APIs, and for error formats, see our reference guide.

Test data

Scenario simulations using Gov-Test-Scenario headers is only available in the sandbox environment.

Header Value (Gov-Test-Scenario) Scenario

N/A - DEFAULT

Simulates a successful response

NO_INCOME_SUBMISSIONS_EXIST

Simulates the scenario where no income submissions exist for the tax year


Close Section
/individuals/calculations/{nino}/self-assessment/{calculationId}

Retrieve Self Assessment Tax Calculation Metadata
GET

The “Retrieve Self Assessment tax calculation metadata” endpoint allows users to retrieve high-level calculation metadata for a given Calculation ID. There will always be calculation metadata associated to a Calculation ID that exists within HMRC. Calculation metadata is mutable and can be updated after a calculation has been run, an example scenario being when a crystallisation declaration has been accepted by HMRC.

Authorisation

This endpoint is user-restricted and requires an Authorization header containing an OAuth 2.0 Bearer Token with the read:self-assessment scope.

Path parameters

Path parameters table
Name Description
nino
string
required

National Insurance number, in the format AA999999A.

For example: TC663795B

calculationId
string
required

The unique identifier of the calculation. Must conform the regular expression: ^[0-9]{8}|[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$

For example: f2fb30e5-4ab6-4a29-b3c1-c7264259ff1c

Request headers

Request headers Table
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
Gov-Test-Scenario
optional

Only in sandbox environment. See Test Data table for all header values.

For example: -
Authorization
required
An OAuth 2.0 Bearer Token with the read:self-assessment scope.

For example: Bearer bb7fed3fe10dd235a2ccda3d50fb

See also fraud prevention.

Response headers

Response headers Table
Name Description
X-CorrelationId
required

Unique ID for operation tracking
String, 36 characters.

For example: c75f40a6-a3df-4429-a697-471eeec46435

See also fraud prevention.

Response

HTTP status: 200 (OK)

Retrieve Calculation Metadata for Crystallisation Calculation

{
  "id": "f2fb30e5-4ab6-4a29-b3c1-c7264259ff1c",
  "taxYear": "2018-19",
  "requestedBy": "customer",
  "calculationReason": "customerRequest",
  "calculationTimestamp": "2019-11-15T09:35:15.094Z",
  "calculationType": "crystallisation",
  "intentToCrystallise": true,
  "crystallised": true,
  "totalIncomeTaxAndNicsDue": 5010.34,
  "links": [
    {
      "href": "/individuals/calculations/RW399019B/self-assessment/f2fb30e5-4ab6-4a29-b3c1-c7264259ff1c",
      "rel": "self",
      "method": "GET"
    },
    {
      "href": "/individuals/calculations/RW399019B/self-assessment/f2fb30e5-4ab6-4a29-b3c1-c7264259ff1c/income-tax-nics-calculated",
      "rel": "income-tax-and-nics-calculated",
      "method": "GET"
    },
    {
      "href": "/individuals/calculations/RW399019B/self-assessment/f2fb30e5-4ab6-4a29-b3c1-c7264259ff1c/taxable-income",
      "rel": "taxable-income",
      "method": "GET"
    },
    {
      "href": "/individuals/calculations/RW399019B/self-assessment/f2fb30e5-4ab6-4a29-b3c1-c7264259ff1c/allowances-deductions-reliefs",
      "rel": "allowances-deductions-reliefs",
      "method": "GET"
    },
    {
      "href": "/individuals/calculations/RW399019B/self-assessment/f2fb30e5-4ab6-4a29-b3c1-c7264259ff1c/end-of-year-estimate",
      "rel": "end-of-year-estimate",
      "method": "GET"
    },
    {
      "href": "/individuals/calculations/RW399019B/self-assessment/f2fb30e5-4ab6-4a29-b3c1-c7264259ff1c/messages",
      "rel": "messages",
      "method": "GET"
    }
  ]
}

Retrieve Calculation Metadata for In Year Calculation

{
  "id": "b03921dc-8e23-5e8a-bf0e-55a8e3904673",
  "taxYear": "2018-19",
  "requestedBy": "customer",
  "calculationReason": "customerRequest",
  "calculationTimestamp": "2019-02-15T08:22:15.094Z",
  "calculationType": "inYear",
  "intentToCrystallise": false,
  "crystallised": false,
  "totalIncomeTaxAndNicsDue": 2000.98,
  "links": [
    {
      "href": "/individuals/calculations/RW399019B/self-assessment/f2fb30e5-4ab6-4a29-b3c1-c7264259ff1c",
      "rel": "self",
      "method": "GET"
    },
    {
      "href": "/individuals/calculations/RW399019B/self-assessment/f2fb30e5-4ab6-4a29-b3c1-c7264259ff1c/income-tax-nics-calculated",
      "rel": "income-tax-and-nics-calculated",
      "method": "GET"
    },
    {
      "href": "/individuals/calculations/RW399019B/self-assessment/f2fb30e5-4ab6-4a29-b3c1-c7264259ff1c/taxable-income",
      "rel": "taxable-income",
      "method": "GET"
    },
    {
      "href": "/individuals/calculations/RW399019B/self-assessment/f2fb30e5-4ab6-4a29-b3c1-c7264259ff1c/allowances-deductions-reliefs",
      "rel": "allowances-deductions-reliefs",
      "method": "GET"
    },
    {
      "href": "/individuals/calculations/RW399019B/self-assessment/f2fb30e5-4ab6-4a29-b3c1-c7264259ff1c/end-of-year-estimate",
      "rel": "end-of-year-estimate",
      "method": "GET"
    },
    {
      "href": "/individuals/calculations/RW399019B/self-assessment/f2fb30e5-4ab6-4a29-b3c1-c7264259ff1c/messages",
      "rel": "messages",
      "method": "GET"
    }
  ]
}

Retrieve Calculation Metadata with Error Messages

{
  "id": "17d6876e-620e-4059-96ef-50adf5422d27",
  "taxYear": "2018-19",
  "requestedBy": "hmrc",
  "calculationReason": "newClaimEvent",
  "calculationTimestamp": "2019-07-04T13:37:35.094Z",
  "calculationType": "inYear",
  "intentToCrystallise": false,
  "crystallised": false,
  "calculationErrorCount": 8,
  "links": [
    {
      "href": "/individuals/calculations/RW399019B/self-assessment/f2fb30e5-4ab6-4a29-b3c1-c7264259ff1c",
      "rel": "self",
      "method": "GET"
    },
    {
      "href": "/individuals/calculations/RW399019B/self-assessment/f2fb30e5-4ab6-4a29-b3c1-c7264259ff1c/messages",
      "rel": "messages",
      "method": "GET"
    }
  ]
}

Response table
Name Description
id
string
required

The unique identifier of the calculation.

Must conform to the regular expression ^[0-9]{8}|[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$

For example: f2fb30e5-4ab6-4a29-b3c1-c7264259ff1c

taxYear
string
required

The tax year in which the calculation was performed in the format YYYY-YY

For example: 2019-20

requestedBy
string
required

The requestor of the calculation. Currently agent will default to customer until it can be supported.

Limited to the following possible values:

customer
hmrc
agent
calculationReason
string
required

The reason why the calculation was triggered

Limited to the following possible values:

customerRequest - The calculation was triggered by the customer via software.
class2NICEvent - The calculation was triggered internally by HMRC once the actual Class 2 NIC amount is available. This event is only applicable for an in-year "crystallisation" calculation type.
newLossEvent - The calculation was triggered internally by HMRC on receipt of a new pre-MTD brought forward loss made by the customer. This event is only applicable for a "crystallisation" calculation type. This event is not currently supported and will be supported in the future.
newClaimEvent - The calculation was triggered internally by HMRC on receipt of a new loss claim made by the customer. This event is only applicable for a "crystallisation" calculation type. This event is not currently supported and will be supported in the future.
updatedClaimEvent - The calculation was triggered internally by HMRC on receipt of an updated loss claim made by the customer. This event is only applicable for a "crystallisation" calculation type. This event is not currently supported and will be supported in the future.
updatedLossEvent - The calculation was triggered internally by HMRC on receipt of an updated pre-MTD brought forward loss made by the customer. This event is only applicable for a "crystallisation" calculation type. This event is not currently supported and will be supported in the future.
newAnnualAdjustmentEvent - The calculation was triggered internally by HMRC on receipt of a request for a new adjustable summary calculation by the customer. This event is not currently supported.
updatedAnnualAdjustmentEvent - The calculation was triggered internally by HMRC on receipt of an adjustment to an adjustable summary calculation made by the customer. This event is not currently supported.
calculationTimestamp
string
optional

The timestamp of when the calculation was performed in ISO8601 UTC format: YYYY-MM-DDThh:mm:ssZ.

For example: 2019-06-17T09:22:59Z

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: true

crystallised
boolean
required

Boolean value showing whether the calculation is intended to be crystallised against. Valid values are true or false

For example: true

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: 2000.98

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: 2

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: /individuals/calculations/{nino}/self-assessment/{calculationId}

rel
string
required

A label for the endpoint, which describes how it is related to the current resource The rel will be self where the action is retrieval of the same resource

Limited to the following possible values:

self
income-tax-and-nics-calculated
taxable-income
allowances-deductions-reliefs
end-of-year-estimate
messages
method
string
required

The HTTP method type for the endpoint

Limited to the following possible values:

GET

Error scenarios

Error scenarios table
Scenario HTTP status Code

The format of the supplied NINO is not valid

400 (Bad Request)

FORMAT_NINO

The format of the supplied Calculation ID is not valid

400 (Bad Request)

FORMAT_CALC_ID

The client and/or agent is not authorised. This is normally because: the client is not subscribed to MTD, the agent is not subscribed to Agent Services, or the client has not authorised the agent to act on their behalf.

403 (Forbidden)

CLIENT_OR_AGENT_NOT_AUTHORISED

No tax calculation data exists for the supplied NINO and calculation ID.

404 (Not Found)

MATCHING_RESOURCE_NOT_FOUND

For error scenarios that are common across all APIs, and for error formats, see our reference guide.

Test data

Scenario simulations using Gov-Test-Scenario headers is only available in the sandbox environment.

Header Value (Gov-Test-Scenario) Scenario

N/A - DEFAULT

Simulates returning an in year tax calculation with all fields.

Please note the values do not represent a realistic tax calculation and is intended to show all fields being populated.

CRYSTALLISATION_METADATA

Simulates returning a crystallisation tax calculation with all fields.

Please note the values do not represent a realistic tax calculation and is intended to show all fields being populated.

ERROR_MESSAGES_EXIST

Simulates the scenario where errors exist and no calculation has been generated.

NOT_FOUND

Simulates the scenario where no data can be found.

UK_MULTIPLE_INCOMES_EXAMPLE

Simulates an example tax calculation with realistic data values, for a UK FHL Property business with Savings and Dividends.

UK_PROP_DIVIDENDS_EXAMPLE

Simulates an example tax calculation with realistic data values, for a UK Non-FHL Property business with Dividends.

UK_PROP_GIFTAID_EXAMPLE

Simulates an example tax calculation with realistic data values, for a UK Non-FHL Property business with Gift Aid.

UK_PROP_SAVINGS_EXAMPLE

Simulates an example tax calculation with realistic data values, for a UK Non-FHL Property business with Savings.

UK_SE_GIFTAID_EXAMPLE

Simulates an example tax calculation with realistic data values, for a UK Self-Employment business with Gift Aid.

UK_SE_SAVINGS_EXAMPLE

Simulates an example tax calculation with realistic data values, for a UK Self-Employment business with Savings.

SCOT_SE_DIVIDENDS_EXAMPLE

Simulates an example tax calculation with realistic data values, for a Scottish Self-Employment business with Dividends.


Close Section
/individuals/calculations/{nino}/self-assessment/{calculationId}/income-tax-nics-calculated

Retrieve Self Assessment Tax Calculation Income Tax and NICs Calculated
GET

This endpoint allows you to retrieve the calculated Income Tax and National Insurance Contributions for a given NINO and Calculation ID.

An error will occur if your calculation has one or more error messages. You can use the Retrieve Self Assessment Tax Calculation Messages endpoint to retrieve these messages.

Authorisation

This endpoint is user-restricted and requires an Authorization header containing an OAuth 2.0 Bearer Token with the read:self-assessment scope.

Path parameters

Path parameters table
Name Description
nino
string
required

National Insurance number, in the format AA999999A.

For example: TC663795B

calculationId
string
required

The unique identifier of the calculation. Must conform the regular expression: ^[0-9]{8}|[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$

For example: f2fb30e5-4ab6-4a29-b3c1-c7264259ff1c

Request headers

Request headers Table
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
Gov-Test-Scenario
optional

Only in sandbox environment. See Test Data table for all header values.

For example: -
Authorization
required
An OAuth 2.0 Bearer Token with the read:self-assessment scope.

For example: Bearer bb7fed3fe10dd235a2ccda3d50fb

See also fraud prevention.

Response headers

Response headers Table
Name Description
X-CorrelationId
required

Unique ID for operation tracking
String, 36 characters.

For example: c75f40a6-a3df-4429-a697-471eeec46435

See also fraud prevention.

Response

HTTP status: 200 (OK)

Example calculation response.

{
  "summary": {
    "incomeTax": {
      "incomeTaxCharged": 5000,
      "incomeTaxDueAfterReliefs": -99999999999.99,
      "incomeTaxDueAfterGiftAid": 5000,
      "totalNotionalTax": 5000.99,
      "incomeTaxDueAfterTaxReductions": 5000.99,
      "totalPensionSavingsTaxCharges": 5000.99,
      "statePensionLumpSumCharges": 5000.99,
      "totalIncomeTaxDue": 5000.99,
      "payeUnderpaymentsCodedOut": 7003.43
    },
    "nics": {
      "class2NicsAmount": 5000,
      "class4NicsAmount": 5000,
      "totalNic": 5000
    },
    "capitalGainsTax": {
      "totalCapitalGainsIncome": 6001.99,
      "annualExemptionAmount": 6002.99,
      "totalTaxableGains": 6003.99,
      "capitalGainsTaxAmount": 6004.99,
      "adjustments": -99999999999.99,
      "adjustedCapitalGainsTax": 6005.99,
      "foreignTaxCreditRelief": 6006.99,
      "capitalGainsTaxAfterFTCR": 6007.99,
      "taxOnGainsAlreadyPaid": 6008.99,
      "capitalGainsTaxDue": 6009.99,
      "capitalGainsOverpaid": 6007.99
    },
    "totalStudentLoansRepaymentAmount": 5000.99,
    "totalAnnualPaymentsTaxCharged": 12500,
    "totalRoyaltyPaymentsTaxCharged": 5000.99,
    "totalIncomeTaxNicsCharged": 5000,
    "totalTaxDeducted": 12500,
    "totalIncomeTaxAndNicsDue": -99999999999.99,
    "taxRegime": "UK",
    "totalTaxDeductedBeforeCodingOut": 98234.44,
    "saUnderpaymentsCodedOut": 38495.21,
    "totalIncomeTaxAndNicsAndCgt": 8764.99
  },
  "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,
      "inYearAdjustmentCodedInLaterTaxYear": 68394.21
    },
    "capitalGainsTax": {
      "businessAssetsDisposalsAndInvestorsRel": {
        "gainsIncome": 12500.99,
        "lossesBroughtForward": 2002.02,
        "lossesArisingThisYear": 500.99,
        "gainsAfterLosses": 459.89,
        "annualExemptionAmount": 5000.99,
        "taxableGains": 3888.88,
        "rate": 90.44,
        "taxAmount": 110.99
      },
      "residentialPropertyAndCarriedInterest": {
        "gainsIncome": 12500.99,
        "lossesBroughtForward": 500.01,
        "lossesArisingThisYear": 600.99,
        "gainsAfterLosses": 210.11,
        "annualExemptionAmount": 500.99,
        "taxableGains": 210.99,
        "cgtTaxBands": [
          {
            "name": "higherRate",
            "rate": 55.05,
            "income": 100.99,
            "taxAmount": 500.99
          }
        ],
        "totalTaxAmount": 100.99
      },
      "otherGains": {
        "gainsIncome": 12500.99,
        "lossesBroughtForward": 500.99,
        "lossesArisingThisYear": 200.50,
        "gainsAfterLosses": 200.99,
        "attributedGains": 110.99,
        "netGains": 250.99,
        "annualExemptionAmount": 500.99,
        "taxableGains": 100.99,
        "cgtTaxBands": [
          {
            "name": "lowerRate",
            "rate": 10.55,
            "income": 110.99,
            "taxAmount": 500.99
          }
        ],
        "totalTaxAmount": 500.99
      },
      "marriageAllowanceTransferredIn": {
        "amount": 3000.00,
        "rate": 10.50
      }
    }
  },
  "links": [
    {
      "href": "/individuals/calculations/RW399019B/self-assessment/f2fb30e5-4ab6-4a29-b3c1-c7264259ff1c/income-tax-nics-calculated",
      "rel": "self",
      "method": "GET"
    },
    {
      "href": "/individuals/calculations/RW399019B/self-assessment/f2fb30e5-4ab6-4a29-b3c1-c7264259ff1c",
      "rel": "metadata",
      "method": "GET"
    }
  ]
}

Response table
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: 1000.12

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: 1000.12

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: 2000.58

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: 3248.98

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: 3280.37

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: 4082.42

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: 2308.83

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: 5083.38

payeUnderpaymentsCodedOut
number
optional

The total coded out amount attributed to PAYE underpayments. This value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 1000.15

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: 1000.12

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: 1000.12

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: 1000.12

capitalGainsTax
object
optional

Details the breakdown of Capital Gains Tax due.

totalCapitalGainsIncome
number
required

The total amount of Capital Gains income. This value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 3000.99

annualExemptionAmount
number
required

The total amount of annual exemption. This value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 3001.99

totalTaxableGains
number
required

The total amount of taxable gains. This value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 3002.99

capitalGainsTaxAmount
number
optional

The total amount of Capital Gains Tax. This value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 3003.99

adjustments
number
optional

The total amount of the adjustments. This value must be between -99999999999.99 and 99999999999.99.

For example: 3004.99

adjustedCapitalGainsTax
number
optional

The total amount of the adjusted Capital Gains Tax. This value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 3005.99

foreignTaxCreditRelief
number
optional

The total amount of the foreign Tax Credit Relief. This value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 3006.99

capitalGainsTaxAfterFTCR
number
optional

The total amount of Capital Gains Tax after Foreign Tax Credit Relief. This value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 3007.99

taxOnGainsAlreadyPaid
number
optional

The total amount of tax already pain on Capital Gain. This value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 3008.99

capitalGainsTaxDue
number
required

The total amount of Capital Gain Tax due. This value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 3009.99

capitalGainsOverpaid
number
optional

The total amount of Capital Gain Tax overpaid. This value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 3010.99

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: 2435.12

totalAnnualPaymentsTaxCharged
number
optional

The total amount of tax charged on annual payments. This value must be between 0 and 99999999999. No decimals.

For example: 7824

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: 1000.12

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: 1000.12

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: 250.32

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: 1000.12

taxRegime
string
required

The national tax rates and rules that apply to the calculation.

Limited to the following possible values:

UK
Scotland
Wales
totalTaxDeductedBeforeCodingOut
number
optional

The total deducted before coded out. This value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 1000.16

saUnderpaymentsCodedOut
number
optional

The total coded out amount attributed to Self Assessment underpayments. This value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 1000.17

totalIncomeTaxAndNicsAndCgt
number
optional

The total amount of income tax, national insurance and capital gains tax. The value must be between 0 and 99999999999.99.

For example: 5600.99

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: 1000

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: 1000.12

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: 10.12

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: 1000

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: 1000

income
number
required

The amount of taxable income for the tax band. This value must be between 0 and 99999999999. No decimals.

For example: 1000

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: 1000.12

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: 1000

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: 1000.12

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: 10.12

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: 1000

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: 1000

income
number
required

The amount of taxable income for the tax band. This value must be between 0 and 99999999999. No decimals.

For example: 1000

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: 1000.12

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: 1000

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: 1000.12

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: 10.12

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: 1000

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: 1000

income
number
required

The amount of taxable income for the tax band. This value must be between 0 and 99999999999. No decimals.

For example: 1000

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: 1000.12

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: 1000

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: 1000.12

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: 10.12

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: 1000

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: 1000

income
number
required

The amount of taxable income for the tax band. This value must be between 0 and 99999999999. No decimals.

For example: 1000

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: 1000.12

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: 1000

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: 1000.12

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: 10.12

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: 1000

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: 1000

income
number
required

The amount of taxable income for the tax band. This value must be between 0 and 99999999999. No decimals.

For example: 1000

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: 1000.12

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: 1000

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: 10.12

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: 200.99

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: 120.99

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: 500.99

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: 200.99

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: 2439.43

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: 3543.63

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: 6334.54

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: 3474.98

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: 5866.34

studentLoanApportionedIncomeThreshold
number
required

The student loan threshold. This value must be between 0 and 99999999999. No decimals.

For example: 4757

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: 42.32

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: 2345.62

totalTaxPaid
number
optional

Total tax paid. This value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 6344.65

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: 7454.87

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: 5089.78

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: 200.99

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: 2532.35

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: 3643.34

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: 65.87

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: 3456.87

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: 6343.45

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: 5445.75

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: 55.34

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: 5765.45

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: 500.99

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: 500.99

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: 3453.43

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: 4564.76

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: 76.44

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: 7655.45

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: 7866.34

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: 4574.78

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: 45.36

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: 4353.64

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: 4654.76

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: 6344.65

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: 43.23

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: 3453.54

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: 9678.56

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: 8756.67

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: 7546.76

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: 3450.64

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: 34.44

bandLimit
number
required

The tax band limit. This value must be between 0 and 99999999999. No decimals.

For example: 5426

apportionedBandLimit
number
required

The apportioned tax band limit. This value must be between 0 and 99999999999. No decimals.

For example: 4563

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: 3393.44

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: 3456.45

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: 3465.34

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: 5343.45

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: 8565.34

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: 8756.45

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: 43.23

bandLimit
number
required

The total band limit. This value must be between 0 and 99999999999. No decimals.

For example: 4382

apportionedBandLimit
number
required

The apportioned band limit. This value must be between 0 and 99999999999. No decimals.

For example: 6343

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: 8556.23

shortServiceRefundCharge
number
required

The amount chargeable. This value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 7547.45

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: 110.99

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: 10

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: 1000

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: 10000

underSmallProfitThreshold
boolean
required

Boolean showing whether the self employment profits are under the Class 2 NIC small profits threshold.

For example: true

actualClass2Nic
boolean
optional

Boolean showing whether the Class 2 NIC charge is an actual charge or estimate in this calculation.

For example: true

class2VoluntaryContributions
boolean
optional

Boolean showing the customer has requested to make voluntary Class 2 NICs contributions.

For example: true

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: 10000

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: 1000

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: 1000

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: 10000

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: 1000

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: 10.12

threshold
number
optional

The upper threshold for the tax band. This value must be between 0 and 99999999999. No decimals.

For example: 1000

apportionedThreshold
number
optional

The amount of the upper threshold that has been apportioned. This value must be between 0 and 99999999999.

For example: 1000

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: 1000

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: 1000

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: 1000.99

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: 1000.99

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: 110.99

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: 2355.65

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: 3456.63

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: 3644.94

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: 2345.64

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: 2389.23

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: 2000.58

inYearAdjustmentCodedInLaterTaxYear
number
optional

Tax that has been deducted due to an in-year adjustment that has been coded out in a later tax year. This value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 1000.15

capitalGainsTax
object
optional

Details the breakdown of Capital Gains Tax

businessAssetsDisposalsAndInvestorsRel
object
optional

Details about tax due on Business assets disposals and Investors Reliefs

gainsIncome
number
optional

The amount of gains income from Business assets disposals and Investors Reliefs. This value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 2001.01

lossesBroughtForward
number
optional

The amount of losses brought forward. This value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 2002.02

lossesArisingThisYear
number
optional

The amount of losses arising from this year. This value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 2003.03

gainsAfterLosses
number
optional

The amount of gains after losses. This value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 2004.04

annualExemptionAmount
number
optional

The amount of annual exemption. This value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 2005.05

taxableGains
number
optional

The taxable gains amount from selling the asset. This value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 2006.06

rate
number
optional

The rate associated with the tax band. This value must be between 0 and 99.99 up to two decimal places.

For example: 55.99

taxAmount
number
optional

The amount of tax paid on business Assets disposals And Investors Reliefs. This value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 2007.07

residentialPropertyAndCarriedInterest
object
optional

Details about tax due on Residential Property and Carried Interest

gainsIncome
number
optional

The amount of gains income from Residential Property and Carried Interest. This value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 2008.08

lossesBroughtForward
number
optional

The amount of losses brought forward. This value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 2009.09

lossesArisingThisYear
number
optional

The amount of losses arising from this year. This value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 2010.10

gainsAfterLosses
number
optional

The amount of gains after losses. This value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 2011.11

annualExemptionAmount
number
optional

The amount of annual exemption. This value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 2012.12

taxableGains
number
optional

The taxable gains amount from selling the asset. This value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 2013.13

cgtTaxBands
array
optional

Details the relevant tax bands for Residential Property and Carried Interest.

name
string
required

The name of the tax band.

Limited to the following possible values:

lowerRate
higherRate
rate
number
required

The rate associated with the tax band. This value must be between 0 and 99.99 up to two decimal places.

For example: 20.14

income
number
required

The amount from Residential Property and Carried Interest income. This value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 215.15

taxAmount
number
required

The amount of tax paid on Residential Property and Carried Interest. This value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 2016.16

totalTaxAmount
number
optional

The total amount of tax paid on Residential Property and Carried Interest. This value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 2017.17

otherGains
object
optional

Details about tax due on Other Gains

gainsIncome
number
optional

The amount of gains income from Other Gains. This value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 218.18

lossesBroughtForward
number
optional

The amount of losses brought forward. This value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 2019.19

lossesArisingThisYear
number
optional

The amount of losses arising from this year. This value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 2020.20

gainsAfterLosses
number
optional

The amount of gains after losses. This value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 221.21

attributedGains
number
optional

The amount of attributed gains. This value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 2022.22

netGains
number
optional

The amount of net gains. This value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 2023.23

annualExemptionAmount
number
optional

The amount of annual exemption. This value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 224.24

taxableGains
number
optional

The taxable gains amount from selling the asset. This value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 2025.25

cgtTaxBands
array
optional

Details the relevant tax bands for Residential Property and Carried Interest.

name
string
required

The name of the tax band.

Limited to the following possible values:

lowerRate
higherRate
rate
number
required

The rate associated with the tax band. This value must be between 0 and 99.99 up to two decimal places.

For example: 26.6

income
number
required

The amount from Other Gains income. This value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 2027.27

taxAmount
number
required

The amount of paid tax on Other Gains. This value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 228.28

totalTaxAmount
number
optional

The total amount of tax paid on Other Gains. This value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 2029.29

marriageAllowanceTransferredIn
object
optional

Details holding marriage allowance transfer in amount.

amount
number
optional

The amount of marriage allowance transferred in. This value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 3000.00

rate
number
optional

The percentage of the relief applied. This value must be between 0 and 99.99 up to 2 decimal places.

For example: 10.50

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: /individuals/calculations/{nino}/self-assessment/{calculationId}

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

Error scenarios table
Scenario HTTP status Code

The format of the supplied NINO is not valid

400 (Bad Request)

FORMAT_NINO

The format of the supplied Calculation ID is not valid

400 (Bad Request)

FORMAT_CALC_ID

The client and/or agent is not authorised. This is normally because: the client is not subscribed to MTD, the agent is not subscribed to Agent Services, or the client has not authorised the agent to act on their behalf.

403 (Forbidden)

CLIENT_OR_AGENT_NOT_AUTHORISED

No Income Tax and National Insurance Contributions data exists for the supplied calculation ID and NINO because error messages were generated while performing the calculation. These error messages can be viewed using the "Retrieve self assessment tax calculation messages" endpoint.

403 (Forbidden)

RULE_CALCULATION_ERROR_MESSAGES_EXIST

No tax calculation data exists for the supplied NINO and calculation ID.

404 (Not Found)

MATCHING_RESOURCE_NOT_FOUND

For error scenarios that are common across all APIs, and for error formats, see our reference guide.

Test data

Scenario simulations using Gov-Test-Scenario headers is only available in the sandbox environment.

Header Value (Gov-Test-Scenario) Scenario

N/A - DEFAULT

Simulates returning a tax calculation with all fields.

Please note the values do not represent a realistic tax calculation and is intended to show all fields being populated.

ERROR_MESSAGES_EXIST

Simulates the scenario where errors exist and no calculation has been generated.

NOT_FOUND

Simulates the scenario where no data can be found.

UK_MULTIPLE_INCOMES_EXAMPLE

Simulates an example tax calculation with realistic data values, for a UK FHL Property business with Savings and Dividends.

UK_PROP_DIVIDENDS_EXAMPLE

Simulates an example tax calculation with realistic data values, for a UK Non-FHL Property business with Dividends.

UK_PROP_GIFTAID_EXAMPLE

Simulates an example tax calculation with realistic data values, for a UK Non-FHL Property business with Gift Aid.

UK_PROP_SAVINGS_EXAMPLE

Simulates an example tax calculation with realistic data values, for a UK Non-FHL Property business with Savings.

UK_SE_GIFTAID_EXAMPLE

Simulates an example tax calculation with realistic data values, for a UK Self-Employment business with Gift Aid.

UK_SE_SAVINGS_EXAMPLE

Simulates an example tax calculation with realistic data values, for a UK Self-Employment business with Savings.

SCOT_SE_DIVIDENDS_EXAMPLE

Simulates an example tax calculation with realistic data values, for a Scottish Self-Employment business with Dividends.


Close Section
/individuals/calculations/{nino}/self-assessment/{calculationId}/taxable-income

Retrieve Self Assessment Tax Calculation Taxable Income
GET

This endpoint allows you to retrieve the taxable income that has been used in the self assessment tax calculation for a given NINO and Calculation ID.

An error will occur if your calculation has one or more error messages. You can use the Retrieve Self Assessment Tax Calculation Messages endpoint to retrieve these messages.

Authorisation

This endpoint is user-restricted and requires an Authorization header containing an OAuth 2.0 Bearer Token with the read:self-assessment scope.

Path parameters

Path parameters table
Name Description
nino
string
required

National Insurance number, in the format AA999999A.

For example: TC663795B

calculationId
string
required

The unique identifier of the calculation. Must conform the regular expression: ^[0-9]{8}|[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$

For example: f2fb30e5-4ab6-4a29-b3c1-c7264259ff1c

Request headers

Request headers Table
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
Gov-Test-Scenario
optional

Only in sandbox environment. See Test Data table for all header values.

For example: -
Authorization
required
An OAuth 2.0 Bearer Token with the read:self-assessment scope.

For example: Bearer bb7fed3fe10dd235a2ccda3d50fb

See also fraud prevention.

Response headers

Response headers Table
Name Description
X-CorrelationId
required

Unique ID for operation tracking
String, 36 characters.

For example: c75f40a6-a3df-4429-a697-471eeec46435

See also fraud prevention.

Response

HTTP status: 200 (OK)

Example calculation response.

{
  "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,
      "tipsIncome": 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": "717f3a7a-db8e-11e9-8a34-2a2ae2dbcce4",
              "applied": true,
              "links": [
                {
                  "href": "/individuals/self-assessment/adjustable-summary/AA123456A/self-employment/717f3a7a-db8e-11e9-8a34-2a2ae2dbcce4/adjust",
                  "rel": "retrieve-self-employment-accounting-adjustments",
                  "method": "GET"
                }
              ]
            },
            "lossClaimsSummary": {
              "carrySidewaysIncomeTaxLossesUsed": 1000,
              "totalBroughtForwardIncomeTaxLosses": 12500,
              "broughtForwardIncomeTaxLossesUsed": 12500,
              "totalIncomeTaxLossesCarriedForward": 12000,
              "totalBroughtForwardClass4Losses": 2000,
              "broughtForwardClass4LossesUsed": 2000,
              "carrySidewaysClass4LossesUsed": 2000,
              "totalClass4LossesCarriedForward": 2000
            },
            "lossClaimsDetail": {
              "lossesBroughtForward": [
                {
                  "lossType": "income",
                  "taxYearLossIncurred": "2019-20",
                  "currentLossValue": 12500,
                  "mtdLoss": true
                }
              ],
              "resultOfClaimsApplied": [
                {
                  "claimId": "EzluDU2ObK02SdA",
                  "taxYearClaimMade": "2019-20",
                  "claimType": "carry-forward",
                  "mtdLoss": true,
                  "taxYearLossIncurred": "2019-20",
                  "lossAmountUsed": 12500,
                  "remainingLossValue": 12500,
                  "lossType": "income"
                }
              ],
              "unclaimedLosses": [
                {
                  "taxYearLossIncurred": "2019-20",
                  "currentLossValue": 5000,
                  "lossType": "income"
                }
              ],
              "carriedForwardLosses": [
                {
                  "claimId": "EzluDU2ObK02SdA",
                  "claimType": "carry-forward",
                  "taxYearClaimMade": "2018-19",
                  "taxYearLossIncurred": "2019-20",
                  "currentLossValue": 12500,
                  "lossType": "income"
                }
              ],
              "claimsNotApplied": [
                {
                  "claimId": "EzluDU2ObK02SdA",
                  "taxYearClaimMade": "2019-20",
                  "claimType": "carry-sideways"
                }
              ]
            }
          }
        ],
        "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": "818f3a7a-db8e-11e9-8a34-2a2ae2dbdde4",
            "applied": true,
            "links": [
              {
                "href": "/individuals/self-assessment/adjustable-summary/AA123456A/property/818f3a7a-db8e-11e9-8a34-2a2ae2dbdde4/adjust",
                "rel": "retrieve-uk-property-accounting-adjustments",
                "method": "GET"
              }
            ]
          },
          "lossClaimsSummary": {
            "lossForCSFHL": 12500,
            "totalBroughtForwardIncomeTaxLosses": 12500,
            "broughtForwardIncomeTaxLossesUsed": 12500,
            "totalIncomeTaxLossesCarriedForward": 12000
          },
          "lossClaimsDetail": {
            "lossesBroughtForward": [
              {
                "taxYearLossIncurred": "2019-20",
                "currentLossValue": 12500,
                "mtdLoss": true
              }
            ],
            "resultOfClaimsApplied": [
              {
                "claimId": "EzluDU2ObK02SdA",
                "taxYearClaimMade": "2019-20",
                "claimType": "carry-forward",
                "mtdLoss": true,
                "taxYearLossIncurred": "2019-20",
                "lossAmountUsed": 12500,
                "remainingLossValue": 12500
              }
            ],
            "defaultCarriedForwardLosses": [
              {
                "taxYearLossIncurred": "2019-20",
                "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": "a54ba782-5ef4-47f4-ab72-495406665ca9",
            "applied": true,
            "links": [
              {
                "href": "/individuals/self-assessment/adjustable-summary/AA123456A/property/a54ba782-5ef4-47f4-ab72-495406665ca9/adjust",
                "rel": "retrieve-uk-property-accounting-adjustments",
                "method": "GET"
              }
            ]
          },
          "lossClaimsSummary": {
            "totalBroughtForwardIncomeTaxLosses": 12500,
            "broughtForwardIncomeTaxLossesUsed": 12500,
            "carrySidewaysIncomeTaxLossesUsed": 12500,
            "totalIncomeTaxLossesCarriedForward": 12000,
            "broughtForwardCarrySidewaysIncomeTaxLossesUsed": 12500
          },
          "lossClaimsDetail": {
            "lossesBroughtForward": [
              {
                "taxYearLossIncurred": "2019-20",
                "currentLossValue": 12500,
                "mtdLoss": true
              }
            ],
            "resultOfClaimsApplied": [
              {
                "claimId": "EzluDU2ObK02SdA",
                "originatingClaimId": "EzluDU2ObK02SdA",
                "taxYearClaimMade": "2019-20",
                "claimType": "carry-forward-to-carry-sideways",
                "mtdLoss": true,
                "taxYearLossIncurred": "2019-20",
                "lossAmountUsed": 12500,
                "remainingLossValue": 12500
              }
            ],
            "defaultCarriedForwardLosses": [
              {
                "taxYearLossIncurred": "2019-20",
                "currentLossValue": 12500
              }
            ],
            "claimsNotApplied": [
              {
                "claimId": "0vayS9JrW2jTa6n",
                "taxYearClaimMade": "2019-20",
                "claimType": "carry-sideways-fhl"
              }
            ]
          }
        },
        "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": "818f3a7a-db8e-11e9-8a34-2a2ae2dbdde4",
            "applied": true,
            "links": [
              {
                "href": "/individuals/self-assessment/adjustable-summary/AA123456A/foreign-property/818f3a7a-db8e-11e9-8a34-2a2ae2dbdde4/adjust",
                "rel": "retrieve-foreign-property-accounting-adjustments",
                "method": "GET"
              }
            ]
          },
          "lossClaimsSummary": {
            "lossForCSFHL": 12500,
            "totalBroughtForwardIncomeTaxLosses": 12500,
            "broughtForwardIncomeTaxLossesUsed": 12500,
            "totalIncomeTaxLossesCarriedForward": 12000
          },
          "lossClaimsDetail": {
            "lossesBroughtForward": [
              {
                "taxYearLossIncurred": "2019-20",
                "currentLossValue": 12500,
                "mtdLoss": true
              }
            ],
            "resultOfClaimsApplied": [
              {
                "claimId": "EzluDU2ObK02SdA",
                "taxYearClaimMade": "2019-20",
                "claimType": "carry-forward",
                "mtdLoss": true,
                "taxYearLossIncurred": "2019-20",
                "lossAmountUsed": 12500,
                "remainingLossValue": 12500
              }
            ],
            "defaultCarriedForwardLosses": [
              {
                "taxYearLossIncurred": "2019-20",
                "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": "a54ba782-5ef4-47f4-ab72-495406665ca9",
            "applied": true,
            "links": [
              {
                "href": "/individuals/self-assessment/adjustable-summary/AA123456A/foreign-property/a54ba782-5ef4-47f4-ab72-495406665ca9/adjust",
                "rel": "retrieve-foreign-property-accounting-adjustments",
                "method": "GET"
              }
            ]
          },
          "lossClaimsSummary": {
            "totalBroughtForwardIncomeTaxLosses": 12500,
            "broughtForwardIncomeTaxLossesUsed": 12500,
            "carrySidewaysIncomeTaxLossesUsed": 12500,
            "totalIncomeTaxLossesCarriedForward": 12000,
            "broughtForwardCarrySidewaysIncomeTaxLossesUsed": 12500
          },
          "lossClaimsDetail": {
            "lossesBroughtForward": [
              {
                "taxYearLossIncurred": "2019-20",
                "currentLossValue": 12500,
                "mtdLoss": true
              }
            ],
            "resultOfClaimsApplied": [
              {
                "claimId": "EzluDU2ObK02SdA",
                "originatingClaimId": "EzluDU2ObK02SdA",
                "taxYearClaimMade": "2019-20",
                "claimType": "carry-forward",
                "mtdLoss": true,
                "taxYearLossIncurred": "2019-20",
                "lossAmountUsed": 12500,
                "remainingLossValue": 12500
              }
            ],
            "defaultCarriedForwardLosses": [
              {
                "taxYearLossIncurred": "2019-20",
                "currentLossValue": 12500
              }
            ],
            "claimsNotApplied": [
              {
                "claimId": "0vayS9JrW2jTa6n",
                "taxYearClaimMade": "2019-20",
                "claimType": "carry-forward"
              }
            ]
          }
        }
      }
    },
    "savingsAndGains": {
      "incomeReceived": 12500,
      "taxableIncome": 12500,
      "totalOfAllGains": 2000,
      "totalUkSavingsAndSecurities": 5000,
      "ukSavings": [
        {
          "savingsAccountId": "SAVKB2UVwUTBQGJ",
          "savingsAccountName": "Santander",
          "grossIncome": 5000,
          "netIncome": 5000.99,
          "taxDeducted": 5000.99
        }
      ],
      "ukSecurities": [
        {
          "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/self-assessment/a54ba782-5ef4-47f4-ab72-495406665ca9",
      "rel": "metadata",
      "method": "GET"
    },
    {
      "href": "/individuals/calculations/AA123456A/self-assessment/a54ba782-5ef4-47f4-ab72-495406665ca9/taxable-income",
      "rel": "self",
      "method": "GET"
    }
  ]
}

Response table
Name Description
summary
object
required

Details the high-level income for the calculation.

totalIncomeReceivedFromAllSources
number
required

The total income received from all income sources. This value must be between 0 and 99999999999. No decimals.

For example: 5000

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: 5000

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: 5000

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: 5000

totalSelfEmploymentProfit
number
optional

The total self-employment profit for all self-employment businesses. This value must be between 0 and 99999999999. No decimals.

For example: 5000

totalPropertyProfit
number
optional

The total of the UK Property FHL and UK Property Non-FHL profits. This value must be between 0 and 99999999999. No decimals.

For example: 5000

totalFHLPropertyProfit
number
optional

The total UK Property FHL profit. This value must be between 0 and 99999999999. No decimals.

For example: 5000

totalUKOtherPropertyProfit
number
optional

The total UK Property Non-FHL profit. This value must be between 0 and 99999999999. No decimals.

For example: 5000

totalForeignPropertyProfit
number
optional

The total Foreign Property Profit. This value must be between 0 and 99999999999. No decimals.

For example: 5000

totalEeaFhlProfit
number
optional

The total EEA FHL Profit. This value must be between 0 and 99999999999. No decimals.

For example: 5000

totalOccupationalPensionIncome
number
optional

The total occupational pension income. This value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 2000.99

totalStateBenefitsIncome
number
optional

The total state benefits income. This value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 2000.99

totalBenefitsInKind
number
optional

The total benefits in kind. This value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 2000.99

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: 2000.99

totalEmploymentExpenses
number
optional

The total employment expenses. This value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 2000.99

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: 2000.99

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: 2000.99

totalEmploymentIncome
number
optional

The total employment and benefit income minus expenses. This value must be between 0 and 99999999999. No decimals.

For example: 45000

totalShareSchemesIncome
number
optional

The total share schemes income. This value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 2000.99

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: 2000.99

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: 2000.99

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: 2000.99

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: 2000.99

tipsIncome
number
optional

The total amount of tips received. This value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 2000.99

businessProfitAndLoss
object
optional

Details the profit and loss position for business income sources.

selfEmployments
array
optional

A list that shows the profit and loss position for each self-employment business.

selfEmploymentId
string
required

A unique identifier for the self-employment business income source. Also referred to as businessId.

Must conform to the regular expression ^X[A-Z0-9]{1}IS[0-9]{11}$

For example: XGIS00000001319

totalIncome
number
optional

The total income received for the self-employment business. This value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 2000.99

totalExpenses
number
optional

The total expenses for the self-employment business. This value must be between -99999999999.99 and 99999999999.99 up to 2 decimal places.

For example: 2000.99

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: 2000.99

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: 2000.99

totalAdditions
number
optional

The total additions to the net profit (or deductions from the net loss) for the self-employment business. This value must be between -99999999999.99 and 99999999999.99 up to 2 decimal places.

For example: 2000.99

totalDeductions
number
optional

The total deductions from the net loss (or additions to the net profit) for the self-employment business. This value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 2000.99

accountingAdjustments
number
optional

Accounting adjustments applied to the profit or loss calculation for the self-employment business. This value must be between -999999999999.99 and 999999999999.99 up to 2 decimal places.

For example: 2000.99

taxableProfit
number
optional

The taxable profit after all additions and deductions have been applied for the self-employment business. This value must be between 0 and 99999999999. No decimals.

For example: 5000

adjustedIncomeTaxLoss
number
optional

The adjusted Income Tax loss after all additions and deductions have been applied for the self-employment business. This value must be between 0 and 99999999999. No decimals.

For example: 5000

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: 5000

taxableProfitAfterIncomeTaxLossesDeduction
number
optional

The taxable profit after income tax losses have been deducted for the self-employment business. This value must be between 0 and 99999999999. No decimals.

For example: 5000

lossClaimsSummary
object
optional

Summarises losses and claims for the self-employment business. This will only be present for a crystallisation calculation.

totalBroughtForwardIncomeTaxLosses
number
optional

The total sum of Income Tax losses brought forward from earlier years for the self-employment business. This value must be between 0 and 99999999999. No decimals.

For example: 5000

broughtForwardIncomeTaxLossesUsed
number
optional

This is the total sum of losses brought forward from previous years used against the taxable profit for the self-employment business for the tax year of the calculation. This value must be between 0 and 99999999999. No decimals.

For example: 5000

carrySidewaysIncomeTaxLossesUsed
number
optional

The Income Tax losses for the self-employment business that have been carried sideways in this calculation. This value must be between 0 and 99999999999. No decimals.

For example: 5000

totalIncomeTaxLossesCarriedForward
number
optional

The total sum of Income Tax losses to be carried forward that have not been used against the self-employment business profits for the tax year of the calculation. This value must be between 0 and 99999999999. No decimals.

For example: 5000

totalBroughtForwardClass4Losses
number
optional

The total sum of Class 4 National Insurance Contributions losses brought forward from earlier years for the self-employment business. This value must be between 0 and 99999999999. No decimals.

For example: 5000

broughtForwardClass4LossesUsed
number
optional

The total sum of Class 4 National Insurance Contributions losses brought forward from earlier years that have been used against the Class 4 National Insurance Contributions for the self-employment business for the tax year of the calculation. This value must be between 0 and 99999999999. No decimals.

For example: 5000

carrySidewaysClass4LossesUsed
number
optional

The Class 4 National Insurance Contributions losses for the self-employment business that have been carried sideways in this calculation. This value must be between 0 and 99999999999. No decimals.

For example: 5000

totalClass4LossesCarriedForward
number
optional

The total sum of Class 4 National Insurance Contributions losses to be carried forward that have not been used against the self-employment business profits for the tax year of the calculation. This value must be between 0 and 99999999999. No decimals.

For example: 5000

lossClaimsDetail
object
optional

Details individual loss claims and how they have been used in the calculation for the self-employment business. This section will only be present for a crystallisation calculation

lossesBroughtForward
array
optional

A list of losses brought forward into this calculation for the self-employment business.

lossType
string
required

The type of loss.

Limited to the following possible values:

income
class4-nics
taxYearLossIncurred
string
required

The tax year of the loss. Format: YYYY-YY

For example: 2019-20

currentLossValue
number
required

The current loss value. This value must be between 0 and 99999999999. No decimals.

For example: 2000

mtdLoss
boolean
required

Flag indicating the loss was registered by the taxpayer on joining MTD.

For example: false

resultOfClaimsApplied
array
optional

A list of loss claims in this calculation for the self-employment business.

claimId
string
optional

The Claim ID of the loss.

Must conform to the regular expression ^[A-Za-z0-9]{15}$

For example: EzluDU2ObK02SdA

taxYearClaimMade
string
required

The tax year in which the claim was made. Format: YYYY-YY

For example: 2019-20

claimType
string
required

The type of loss claim that was made.

Limited to the following possible values:

carry-forward
carry-sideways
mtdLoss
boolean
required

Flag indicating the loss was registered by the taxpayer on joining MTD.

For example: false

taxYearLossIncurred
string
required

The tax year in which the loss was incurred. Date in the format: YYYY-YY

For example: 2019-20

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: 2000

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: 5000

lossType
string
required

The type of loss.

Limited to the following possible values:

income
class4-nics
unclaimedLosses
array
optional

Losses from the self-employment business from this calculation where no carry forward claim has been made

taxYearLossIncurred
string
required

The tax year the loss arose. Format: YYYY-YY

For example: 2019-20

currentLossValue
number
required

The current loss value. This value must be between 0 and 99999999999. No decimals.

For example: 2000

lossType
string
required

The type of loss.

Limited to the following possible values:

income
class4-nics
carriedForwardLosses
array
optional

Losses from the self-employment business from this calculation where a carry forward claim has been made

claimId
string
optional

The Claim ID of the loss.

Must conform to the regular expression ^[A-Za-z0-9]{15}$

For example: EzluDU2ObK02SdA

claimType
string
required

The type of claim that was made.

Limited to the following possible values:

carry-forward
taxYearClaimMade
string
optional

The tax year in which the claim was made. Format: YYYY-YY

For example: 2019-20

taxYearLossIncurred
string
required

The tax year of the loss. Format: YYYY-YY

For example: 2019-20

currentLossValue
number
required

The current loss value. This value must be between 0 and 99999999999. No decimals.

For example: 2000

lossType
string
required

The type of loss.

Limited to the following possible values:

income
class4-nics
claimsNotApplied
array
optional

Loss claims that could not be applied in this calculation for the self-employment business

claimId
string
required

The Claim ID of the loss.

Must conform to the regular expression ^[A-Za-z0-9]{15}$

For example: EzluDU2ObK02SdA

taxYearClaimMade
string
required

The tax year in which the claim was made. Format: YYYY-YY

For example: 2019-20

claimType
string
required

The type of claim that was made.

Limited to the following possible values:

carry-sideways
carry-forward
bsas
object
optional

Details if the amounts in a Business Source Adjustable Summary adjustment for this self-employment business have been used in this calculation.

bsasId
string
required

The unique identifier of the Business Source Adjustable Summary for this self-employment business.

Must conform to the regular expression ^[0-9]{8}|[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$

For example: a54ba782-5ef4-47f4-ab72-495406665ca9

applied
boolean
required

Flag indicating whether the amounts in the Business Source Adjustable Summary adjustment have been used in this calculation.

For example: false

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: 2000.98

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: 2000.98

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: 2000.98

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: 2000.98

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: 2000.98

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: 2000.98

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: 2000

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: 2000

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: 2000

lossClaimsSummary
object
optional

Summarises losses and claims for the UK Property FHL. This section will only be present for a crystallisation calculation

lossForCSFHL
number
optional

The losses from UK Property Non-FHL that have been carried sideways to UK Property FHL. This value must be between 0 and 99999999999. No decimals.

For example: 2000

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: 2000

broughtForwardIncomeTaxLossesUsed
number
optional

The total sum of losses brought forward from previous years used against the taxable profit for UK Property Non-FHL for the tax year of the calculation. This value must be between 0 and 99999999999. No decimals.

For example: 2000

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: 2000

lossClaimsDetail
object
optional

Details individual loss claims and how they have been used in the calculation for the UK Property FHL. This section will only be present for a crystallisation calculation.

lossesBroughtForward
array
optional

A list of losses brought forward into this calculation for UK Property FHL.

taxYearLossIncurred
string
required

The tax year of the loss. Format: YYYY-YY

For example: 2019-20

currentLossValue
number
required

The current loss value. This value must be between 0 and 99999999999. No decimals.

For example: 2000

mtdLoss
boolean
required

Flag indicating the loss was registered by the taxpayer on joining MTD.

For example: false

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 ^[A-Za-z0-9]{15}$

For example: EzluDU2ObK02SdA

taxYearClaimMade
string
required

The tax year in which the claim was made. Format: YYYY-YY

For example: 2019-20

claimType
string
required

The type of claim made.

Limited to the following possible values:

carry-forward
mtdLoss
boolean
required

Flag indicating whether the loss was registered by the taxpayer on joining MTD.

For example: false

taxYearLossIncurred
string
required

The tax year in which the loss was incurred. Date in the format: YYYY-YY

For example: 2019-20

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: 2000

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: 2000

defaultCarriedForwardLosses
array
optional

UK Property FHL losses from this calculation that will be carried forward to the next tax year.

taxYearLossIncurred
string
required

The tax year of the loss. Format: YYYY-YY

For example: 2019-20

currentLossValue
number
required

The current loss value. This value must be between 0 and 99999999999. No decimals.

For example: 2000

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 ^[0-9]{8}|[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$

For example: a54ba782-5ef4-47f4-ab72-495406665ca9

applied
boolean
required

Flag indicating whether the amounts in the Business Source Adjustable Summary adjustment have been used in this calculation.

For example: false

ukPropertyNonFhl
object
optional

Details the profit and loss position for UK Property Non-FHL.

totalIncome
number
optional

The total income received for UK Property Non-FHL. This value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 2000.98

totalExpenses
number
optional

The total expenses for UK property Non-FHL. This value must be between -99999999999.99 and 99999999999.99 up to 2 decimal places.

For example: 2000.98

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: 2000.99

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: 2000.99

totalAdditions
number
optional

The total additions to the net profit (or deductions from the net loss) for UK Property Non-FHL. This value must be between -99999999999.99 and 99999999999.99 up to 2 decimal places.

For example: 2000.98

totalDeductions
number
optional

The total deductions from the net loss (or additions to the net profit) for UK Property Non-FHL. This value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 2000.98

accountingAdjustments
number
optional

Accounting adjustments applied to the profit or loss calculation for UK Property Non-FHL. This value must be between -999999999999.99 and 999999999999.99 up to 2 decimal places.

For example: -2000.98

taxableProfit
number
optional

The taxable profit after all additions and deductions have been applied for UK Property Non-FHL. This value must be between 0 and 99999999999. No decimals.

For example: 2000

adjustedIncomeTaxLoss
number
optional

The adjusted Income Tax loss after all additions and deductions have been applied for UK property Non-FHL. This value must be between 0 and 99999999999. No decimals.

For example: 2000

taxableProfitAfterIncomeTaxLossesDeduction
number
optional

The taxable profit after income tax losses have been deducted for UK Property Non-FHL. This value must be between 0 and 99999999999. No decimals.

For example: 2000

lossClaimsSummary
object
optional

Summarises losses and claims for UK Property Non-FHL This will only be present for a crystallisation calculation.

totalBroughtForwardIncomeTaxLosses
number
optional

The total sum of Income Tax losses brought forward from earlier years for UK Property Non-FHL. This value must be between 0 and 99999999999. No decimals.

For example: 5000

broughtForwardIncomeTaxLossesUsed
number
optional

The total sum of losses brought forward from previous years used against the taxable profit for UK Property Non-FHL for the tax year of the calculation. This value must be between 0 and 99999999999. No decimals.

For example: 2001

carrySidewaysIncomeTaxLossesUsed
number
optional

The Income Tax losses for UK Property Non-FHL that have been carried sideways in this calculation. This value must be between 0 and 99999999999. No decimals.

For example: 5000

totalIncomeTaxLossesCarriedForward
number
optional

The total sum of Income Tax losses to be carried forward that have not been utilised against the UK Property Non-FHL profits for the tax year of the calculation. This value must be between 0 and 99999999999. No decimals.

For example: 2000

broughtForwardCarrySidewaysIncomeTaxLossesUsed
number
optional

The total sum of the carry sideways losses for UK Property Non-FHL brought forward from previous tax years. This value must be between 0 and 99999999999. No decimals.

For example: 5000

lossClaimsDetail
object
optional

Details individual loss claims and how they have been used in the calculation for the UK Property Non-FHL. This section will only be present for a crystallisation calculation.

lossesBroughtForward
array
optional

A list of losses brought forward into this calculation for UK Property Non-FHL.

taxYearLossIncurred
string
required

The tax year of the loss. Format: YYYY-YY

For example: 2019-20

currentLossValue
number
required

The current loss value. This value must be between 0 and 99999999999. No decimals.

For example: 2000

mtdLoss
boolean
required

Flag indicating the loss was registered by the taxpayer on joining MTD.

For example: false

resultOfClaimsApplied
array
optional

A list of loss claims in this calculation for UK Property Non-FHL

claimId
string
optional

The Claim ID of the loss.

Must conform to the regular expression ^[A-Za-z0-9]{15}$

For example: EzluDU2ObK02SdA

originatingClaimId
string
optional

The ID of an original carry-sideways-fhl/carry-sideways claim where not all of the loss in the calculation year could be carried sideways and the resulting loss balance was carried forwards. Where a resulting carry sideways loss balance is carried forwards there will not be a new claim ID for the carried forward portion of the loss.

Must conform to the regular expression ^[A-Za-z0-9]{15}$

For example: EzluDU2ObK02SdA

taxYearClaimMade
string
required

The tax year in which the claim was made. Format: YYYY-YY

For example: 2019-20

claimType
string
required

The type of claim that was made.

Limited to the following possible values:

carry-forward
carry-sideways
carry-forward-to-carry-sideways
carry-sideways-fhl
mtdLoss
boolean
required

Flag indicating the loss was registered by the taxpayer on joining MTD.

For example: false

taxYearLossIncurred
string
optional

The tax year in which the loss was incurred. Format: YYYY-YY

For example: 2019-20

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: 5000

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: 2000

defaultCarriedForwardLosses
array
optional

UK Property Non-FHL losses from this calculation that will be carried forward to the next tax year.

taxYearLossIncurred
string
required

The tax year of the loss. Format: YYYY-YY

For example: 2018-19

currentLossValue
number
required

The current loss value. This value must be between 0 and 99999999999. No decimals.

For example: 2000

claimsNotApplied
array
optional

Loss claims that could not be applied in this calculation for UK Property Non-FHL.

claimId
string
required

The Claim ID of the loss.

Must conform to the regular expression ^[A-Za-z0-9]{15}$

For example: EzluDU2ObK02SdA

taxYearClaimMade
string
required

The tax year in which the claim was made. Format: YYYY-YY

For example: 2018-19

claimType
string
required

The type of claim that was made.

Limited to the following possible values:

carry-sideways
carry-sideways-fhl
carry-forward
carry-forward-to-carry-sideways
bsas
object
optional

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

bsasId
string
required

The unique identifier of the Business Source Adjustable Summary for UK Property Non-FHL.

Must conform to the regular expression ^[0-9]{8}|[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$

For example: a54ba782-5ef4-47f4-ab72-495406665ca9

applied
boolean
required

Flag indicating whether the amounts in the Business Source Adjustable Summary adjustment have been used in this calculation.

For example: false

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: 2000.98

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: 2000.98

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: 2000.98

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: 2000.98

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: 2000.98

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: 2000.98

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: 5000

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: 2000

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: 2000

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 ^[0-9]{8}|[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$

For example: a54ba782-5ef4-47f4-ab72-495406665ca9

applied
boolean
required

Flag indicating whether the amounts in the Business Source Adjustable Summary adjustment have been used in this calculation.

For example: false

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: /individuals/self-assessment/adjustable-summary/AA123456A/foreign-property/a54ba782-5ef4-47f4-ab72-495406665ca9/adjust

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:

retrieve-foreign-property-accounting-adjustments
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: 2000

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: 2000

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: 2000

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: 2000

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: YYYY-YY

For example: 2019-20

currentLossValue
number
required

The current loss value. This value must be between 0 and 99999999999. No decimals.

For example: 2000

mtdLoss
boolean
required

Flag indicating the loss was registered by the taxpayer on joining MTD.

For example: false

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 ^[A-Za-z0-9]{15}$

For example: EzluDU2ObK02SdA

taxYearClaimMade
string
required

The tax year in which the claim was made. Format: YYYY-YY

For example: 2019-20

claimType
string
required

The type of claim made.

Limited to the following possible values:

carry-forward
mtdLoss
boolean
required

Flag indicating the loss was registered by the taxpayer on joining MTD.

For example: false

taxYearLossIncurred
string
required

The tax year in which the loss was incurred. Date in the format: YYYY-YY

For example: 2019-20

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: 2000

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: 2000

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: YYYY-YY

For example: 2019-20

currentLossValue
number
required

The current loss value. This value must be between 0 and 99999999999. No decimals.

For example: 2000

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: 2000.98

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: 2000.99

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: 2000.99

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: 2000.98

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: 2000.98

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: 2000.98

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: -2000.98

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: 2000

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: 2000

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: 2000

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 ^[0-9]{8}|[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$

For example: a54ba782-5ef4-47f4-ab72-495406665ca9

applied
boolean
required

Flag indicating whether the amounts in the Business Source Adjustable Summary adjustment have been used in this calculation.

For example: false

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: /individuals/self-assessment/adjustable-summary/AA123456A/foreign-property/a54ba782-5ef4-47f4-ab72-495406665ca9/adjust

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:

retrieve-foreign-property-accounting-adjustments
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: 5000

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: 2000

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: 5000

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: 5000

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: 2000

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: YYYY-YY

For example: 2019-20

currentLossValue
number
required

The current loss value. This value must be between 0 and 99999999999. No decimals.

For example: 2000

mtdLoss
boolean
required

Flag indicating the loss was registered by the taxpayer on joining MTD.

For example: false

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 ^[A-Za-z0-9]{15}$

For example: EzluDU2ObK02SdA

originatingClaimId
string
optional

The ID of an original carry-sideways-fhl or carry-sideways claim where not all of the loss in the calculation year could be carried sideways and the resulting loss balance was carried forwards. Where a resulting carry sideways loss balance is carried forwards there will not be a new claim ID for the carried forward portion of the loss.

Must conform to the regular expression ^[A-Za-z0-9]{15}$

For example: EzluDU2ObK02SdA

taxYearClaimMade
string
required

The tax year in which the claim was made. Format: YYYY-YY

For example: 2019-20

claimType
string
required

The type of claim made.

Limited to the following possible values:

carry-forward
carry-sideways
carry-forward-to-carry-sideways
carry-sideways-fhl
mtdLoss
boolean
required

Flag indicating the loss was registered by the taxpayer on joining MTD.

For example: false

taxYearLossIncurred
string
required

The tax year of the loss. Format: YYYY-YY

For example: 2019-20

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: 5000

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: 2000

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: YYYY-YY

For example: 2019-20

currentLossValue
number
required

The current loss value. This value must be between 0 and 99999999999. No decimals.

For example: 2000

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 ^[A-Za-z0-9]{15}$

For example: EzluDU2ObK02SdA

taxYearClaimMade
string
required

The tax year in which the claim was made. Format: YYYY-YY

For example: 2019-20

claimType
string
required

The type of claim that was made.

Limited to the following possible values:

carry-forward
carry-sideways
carry-forward-to-carry-sideways
carry-sideways-fhl
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: 2000

taxableIncome
number
required

The taxable savings income. This value must be between 0 and 99999999999. No decimals.

For example: 2000

totalOfAllGains
number
optional

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: 2000

totalUkSavingsAndSecurities
number
optional

The total value of UK Savings and UK Securities. This value must be between 0 and 99999999999. No decimals.

For example: 5000

totalUkSavingsAndGains
number
optional

The total value of UK Savings and UK Securities. This value must be between 0 and 99999999999. No decimals.

For example: 5000

ukSavings
array
optional

Details of each savings account.

savingsAccountId
string
optional

The unique identifier of the savings account.

Must conform to the regular expression ^[A-Za-z0-9]{15}$

For example: SAVKB2UVwUTBQGJ

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 ^[A-Za-z0-9 &'()*,-./@£]{1,32}$

For example: UK savings account

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: 2000.98

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: 2000.98

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: 2000.98

ukSecurities
array
optional

Details of UK Securities accounts.

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: 2000.98

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: 2000.98

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: 2000.98

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: 5000

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: 5000

totalForeignSavingsAndGainsIncome
number
optional

The total value of Foreign Savings and Gains Income. This value must be between 0 and 99999999999. No decimals.

For example: 5000

dividends
object
optional

Details of dividend income.