Skip to main content
GOV.UK
Menu
HMRC Developer Hub
  • Documentation
  • Applications
  • Support
  • Service availability

GOV.UK uses cookies to make the site simpler. Find out more about cookies

  1. Home
  2. API Documentation
  3. Individual Calculations (MTD) API v1.0 (Beta)
  • Register
  • Sign in
  • Overview
  • Changelog
  • Support
  • Testing
  • Versioning
  • Errors
  • Endpoints
    • Self Assessment
 

This version is in beta - expect some breaking changes.

Individual Calculations (MTD) API

Available in SandboxYes
Sandbox base URLhttps://test-api.service.hmrc.gov.uk
Available in ProductionNo

Overview

The individual calculations API allows a self-assessment taxpayer via software, to:

  • trigger a self-assessment tax calculation
  • list all their self-assessment tax calculations for a tax year
  • retrieve their self-assessment tax calculation result using multiple endpoints

Changelog

You can find the changelog in the individual-calculations-api GitHub wiki.

Support

  • Raise non-technical or platform-related issues with the Software Development Support Team (SDST).
  • Raise technical issues on the individual-calculations-api GitHub page.

Testing

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

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

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

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

Versioning

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

Errors

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

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

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

Back to top

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 [test only]
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 - it 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.1.0+json
Gov-Test-Scenario
optional

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


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

For example: Bearer bb7fed3fe10dd235a2ccda3d50fb

See also fraud prevention for other request headers which will become mandatory.

Response headers

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 for other request headers which will become mandatory.

Response

HTTP status: 200 (OK)

{
  "calculations": [
    {
      "id": "f2fb30e5-4ab6-4a29-b3c1-c7264259ff1c",
      "calculationTimestamp": "2019-03-17T09:22:59Z",
      "type": "inYear",
      "requestedBy": "hmrc",
      "links": [
        {
          "href": "/individuals/calculations/RW399019B/self-assessment/f2fb30e5-4ab6-4a29-b3c1-c7264259ff1c",
          "rel": "self",
          "method": "GET"
        }
      ]
    },
    {
      "id": "cf63c46a-1a4f-3c56-b9ea-9a82551d27bb",
      "calculationTimestamp": "2019-06-17T18:45:59Z",
      "type": "crystallisation",
      "requestedBy": "customer",
      "links": [
        {
          "href": "/individuals/calculations/RW399019B/self-assessment/cf63c46a-1a4f-3c56-b9ea-9a82551d27bb",
          "rel": "self",
          "method": "GET"
        }
      ]
    }
  ],
  "links": [
    {
      "href": "/individuals/calculations/RW399019B/self-assessment",
      "rel": "self",
      "method": "GET"
    },
    {
      "href": "/individuals/calculations/RW399019B/self-assessment",
      "rel": "trigger",
      "method": "POST"
    }
  ]
}
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 exceeded. A tax year range of one year is required.

400 (Bad Request)

RULE_TAX_YEAR_RANGE_EXCEEDED

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

403 (Forbidden)

CLIENT_OR_AGENT_NOT_AUTHORISED

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

404 (Not Found)

MATCHING_RESOURCE_NOT_FOUND

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

Test data

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

Header Value (Gov-Test-Scenario) Scenario

N/A - DEFAULT

Simulate success scenario for self-employment

CRYSTALLISATION

Simulate success scenario where a crystallisation calculation is found

MULTIPLE_CALCULATIONS

Simulate success scenario where multiple tax calculations are found

NOT_FOUND

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

Close section
Trigger a Self Assessment Tax Calculation [test only]
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. It can take up to 5 seconds for a Calculation ID to be returned when triggering a tax calculation. The result of the calculation can be seen using the “Retrieve Self Assessment Tax Calculation Metadata” endpoint.

Authorisation

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

Path parameters

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.1.0+json
Content-Type
required

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


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

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


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

For example: Bearer bb7fed3fe10dd235a2ccda3d50fb

See also fraud prevention for other request headers which will become mandatory.

Request

{
  "taxYear": "2017-18"
}
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 for other request headers which will become mandatory.

Response

HTTP status: 202 (Accepted)

{
  "id": "f2fb30e5-4ab6-4a29-b3c1-c7264259ff1c",
  "links": [
    {
      "href": "/individuals/calculations/RW399019B/self-assessment/f2fb30e5-4ab6-4a29-b3c1-c7264259ff1c",
      "rel": "self",
      "method": "GET"
    }
  ]
}
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 exceeded. A tax year range of one year is required.

400 (Bad Request)

RULE_TAX_YEAR_RANGE_EXCEEDED

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

400 (Bad Request)

RULE_INCORRECT_OR_EMPTY_BODY_SUBMITTED

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

403 (Forbidden)

CLIENT_OR_AGENT_NOT_AUTHORISED

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

403 (Forbidden)

RULE_NO_INCOME_SUBMISSIONS_EXIST

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

Test data

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

Header Value (Gov-Test-Scenario) Scenario

N/A - DEFAULT

Simulates a successful response

NO_INCOME_SUBMISSIONS_EXIST

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

Close section
/individuals/calculations/{nino}/self-assessment/{calculationId}
Retrieve Self Assessment Tax Calculation Metadata [test only]
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 - it 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.1.0+json
Gov-Test-Scenario
optional

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


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

For example: Bearer bb7fed3fe10dd235a2ccda3d50fb

See also fraud prevention for other request headers which will become mandatory.

Response headers

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 for other request headers which will become mandatory.

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 [test only]
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 - it 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.1.0+json
Gov-Test-Scenario
optional

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


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

For example: Bearer bb7fed3fe10dd235a2ccda3d50fb

See also fraud prevention for other request headers which will become mandatory.

Response headers

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 for other request headers which will become mandatory.

Response

HTTP status: 200 (OK)

Example calculation response.
{
  "summary": {
    "incomeTax": {
      "incomeTaxCharged": 1000.12,
      "incomeTaxDueAfterReliefs": 1000.12,
      "incomeTaxDueAfterGiftAid": 1000.12
    },
    "nics": {
      "class2NicsAmount": 1000.12,
      "class4NicsAmount": 1000.12,
      "totalNic": 1000.12
    },
    "totalIncomeTaxNicsCharged": 1000.12,
    "totalTaxDeducted": 1000,
    "totalIncomeTaxAndNicsDue": 1000.12,
    "taxRegime": "UK"
  },
  "detail": {
    "incomeTax": {
      "payPensionsProfit": {
        "allowancesAllocated": 1000,
        "incomeTaxAmount": 1000,
        "taxBands": [
          {
            "name": "SRT",
            "rate": 10.12,
            "bandLimit": 1000,
            "apportionedBandLimit": 1000,
            "income": 1000,
            "taxAmount": 1000.12
          }
        ]
      },
      "savingsAndGains": {
        "allowancesAllocated": 1000,
        "incomeTaxAmount": 1000,
        "taxBands": [
          {
            "name": "SSR",
            "rate": 10.12,
            "bandLimit": 1000,
            "apportionedBandLimit": 1000,
            "income": 1000,
            "taxAmount": 1000.12
          }
        ]
      },
      "dividends": {
        "allowancesAllocated": 1000,
        "incomeTaxAmount": 1000,
        "taxBands": [
          {
            "name": "BRT",
            "rate": 10.12,
            "bandLimit": 1000,
            "apportionedBandLimit": 1000,
            "income": 1000,
            "taxAmount": 1000.12
          }
        ]
      },
      "giftAid": {
        "grossGiftAidPayments": 1000,
        "rate": 10.12,
        "giftAidTax": 1000.12
      }
    },
    "nics": {
      "class2Nics": {
        "weeklyRate": 1000.12,
        "weeks": 10,
        "limit": 1000,
        "apportionedLimit": 1000,
        "underSmallProfitThreshold": true,
        "actualClass2Nic": true
      },
      "class4Nics": {
        "totalIncomeChargeableToClass4": 1000,
        "class4Losses": {
          "totalClass4LossesAvailable": 1000,
          "totalClass4LossesUsed": 1000,
          "totalClass4LossesCarriedForward": 1000
        },
        "totalIncomeLiableToClass4Charge": 1000,
        "class4NicBands": [
          {
            "name": "ZRT",
            "rate": 10.12,
            "threshold": 1000,
            "apportionedThreshold": 1000,
            "income": 1000,
            "amount": 1000.12
          }
        ]
      }
    },
    "taxDeductedAtSource": {
      "savings": 1000,
      "ukLandAndProperty": 1000
    }
  },
  "links": [
    {
      "href": "/individuals/calculations/RW399019B/self-assessment/f2fb30e5-4ab6-4a29-b3c1-c7264259ff1c/income-tax-nics-calculated",
      "rel": "self",
      "method": "GET"
    },
    {
      "href": "/individuals/calculations/RW399019B/self-assessment/f2fb30e5-4ab6-4a29-b3c1-c7264259ff1c",
      "rel": "metadata",
      "method": "GET"
    }
  ]
}
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

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

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 0 and 99999999999. No decimals.

For example: 250

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

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

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 when insufficient Income Tax has been paid. This value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 1000.12

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

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. No decimals.

For example: 1000

ukLandAndProperty
number
optional

Tax that has been deducted at source for UK land and property. This value must be between 0 and 99999999999. No decimals.

For example: 1000

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 [test only]
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 - it 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.1.0+json
Gov-Test-Scenario
optional

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


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

For example: Bearer bb7fed3fe10dd235a2ccda3d50fb

See also fraud prevention for other request headers which will become mandatory.

Response headers

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 for other request headers which will become mandatory.

Response

HTTP status: 200 (OK)

Example calculation response.
{
  "summary": {
    "totalIncomeReceivedFromAllSources": 1000,
    "totalTaxableIncome": 1000
  },
  "detail": {
    "payPensionsProfit": {
      "incomeReceived": 1000,
      "taxableIncome": 1000,
      "totalSelfEmploymentProfit": 1000,
      "totalPropertyProfit": 1000,
      "totalFHLPropertyProfit": 1000,
      "totalUKOtherPropertyProfit": 1000,
      "businessProfitAndLoss": {
        "selfEmployments": [
          {
            "selfEmploymentId": "XGIS00000001319",
            "totalIncome": 1000.12,
            "totalExpenses": 1000.12,
            "netProfit": 1000.12,
            "netLoss": 1000.12,
            "totalAdditions": 1000.12,
            "totalDeductions": 1000.12,
            "accountingAdjustments": 1000.12,
            "taxableProfit": 1000,
            "adjustedIncomeTaxLoss": 1000,
            "class4Loss": 1000,
            "taxableProfitAfterIncomeTaxLossesDeduction": 1000,
            "lossClaimsSummary": {
              "totalBroughtForwardIncomeTaxLosses": 1000,
              "broughtForwardIncomeTaxLossesUsed": 1000,
              "totalIncomeTaxLossesCarriedForward": 1000,
              "totalBroughtForwardClass4Losses": 1000,
              "broughtForwardClass4LossesUsed": 1000,
              "carrySidewaysClass4LossesUsed": 1000,
              "totalClass4LossesCarriedForward": 1000
            },
            "lossClaimsDetail": {
              "lossesBroughtForward": [
                {
                  "lossType": "income",
                  "taxYearLossIncurred": "2018-19",
                  "currentLossValue": 1000,
                  "mtdLoss": false
                }
              ],
              "resultOfClaimsApplied": [
                {
                  "claimId": "XGIS00000001319",
                  "taxYearClaimMade": "2018-19",
                  "claimType": "carry-forward",
                  "mtdLoss": false,
                  "taxYearLossIncurred": "2018-19",
                  "lossAmountUsed": 1000,
                  "remainingLossValue": 1000,
                  "lossType": "class4-nics"
                }
              ],
              "unclaimedLosses": [
                {
                  "taxYearLossIncurred": "2018-19",
                  "currentLossValue": 1000,
                  "expires": "2018-19",
                  "lossType": "class4-nics"
                }
              ],
              "carriedForwardLosses": [
                {
                  "claimId": "XGIS00000001319",
                  "claimType": "carry-forward",
                  "taxYearClaimMade": "2018-19",
                  "taxYearLossIncurred": "2018-19",
                  "currentLossValue": 1000,
                  "lossType": "class4-nics"
                }
              ],
              "claimsNotApplied": [
                {
                  "claimId": "XGIS00000001319",
                  "taxYearClaimMade": "2018-19",
                  "claimType": "carry-forward"
                }
              ]
            }
          }
        ],
        "ukPropertyFhl": {
          "totalIncome": 1000.12,
          "totalExpenses": 1000.12,
          "netProfit": 1000.12,
          "netLoss": 1000.12,
          "totalAdditions": 1000.12,
          "totalDeductions": 1000.12,
          "accountingAdjustments": 1000.12,
          "taxableProfit": 1000,
          "adjustedIncomeTaxLoss": 1000,
          "taxableProfitAfterIncomeTaxLossesDeduction": 1000,
          "lossClaimsSummary": {
            "lossForCSFHL": 1000,
            "totalBroughtForwardIncomeTaxLosses": 1000,
            "broughtForwardIncomeTaxLossesUsed": 1000,
            "totalIncomeTaxLossesCarriedForward": 1000
          },
          "lossClaimsDetail": {
            "lossesBroughtForward": [
              {
                "taxYearLossIncurred": "2018-19",
                "currentLossValue": 1000,
                "mtdLoss": false
              }
            ],
            "resultOfClaimsApplied": [
              {
                "claimId": "EzluDU2ObK02SdA",
                "taxYearClaimMade": "2018-19",
                "claimType": "carry-forward",
                "mtdLoss": false,
                "taxYearLossIncurred": "2018-19",
                "lossAmountUsed": 1000,
                "remainingLossValue": 1000
              }
            ],
            "defaultCarriedForwardLosses": [
              {
                "taxYearLossIncurred": "2018-19",
                "currentLossValue": 1000
              }
            ]
          }
        },
        "ukPropertyNonFhl": {
          "totalIncome": 1000.12,
          "totalExpenses": 1000.12,
          "netProfit": 1000.12,
          "netLoss": 1000.12,
          "totalAdditions": 1000.12,
          "totalDeductions": 1000.12,
          "accountingAdjustments": -1000.12,
          "taxableProfit": 1000,
          "adjustedIncomeTaxLoss": 1000,
          "taxableProfitAfterIncomeTaxLossesDeduction": 1000,
          "lossClaimsSummary": {
            "totalBroughtForwardIncomeTaxLosses": 1000,
            "broughtForwardIncomeTaxLossesUsed": 1000,
            "totalIncomeTaxLossesCarriedForward": 1000
          },
          "lossClaimsDetail": {
            "lossesBroughtForward": [
              {
                "taxYearLossIncurred": "2018-19",
                "currentLossValue": 1000,
                "mtdLoss": false
              }
            ],
            "resultOfClaimsApplied": [
              {
                "claimId": "XGIS00000001319",
                "originatingClaimId": "XGIS00000001319",
                "taxYearClaimMade": "2018-19",
                "claimType": "carry-forward",
                "mtdLoss": false,
                "taxYearLossIncurred": "2018-19",
                "lossAmountUsed": 1000,
                "remainingLossValue": 1000
              }
            ],
            "defaultCarriedForwardLosses": [
              {
                "taxYearLossIncurred": "2018-19",
                "currentLossValue": 1000
              }
            ],
            "claimsNotApplied": [
              {
                "claimId": "XGIS00000001319",
                "taxYearClaimMade": "2018-19",
                "claimType": "carry-sideways"
              }
            ]
          }
        }
      }
    },
    "savingsAndGains": {
      "incomeReceived": 1000,
      "taxableIncome": 1000,
      "ukSavings": [
        {
          "savingsAccountId": "SAVKB2UVwUTBQGJ",
          "savingsAccountName": "friendly name",
          "grossIncome": 1000.12,
          "netIncome": 1000.12,
          "taxDeducted": 1000.12
        }
      ]
    },
    "dividends": {
      "incomeReceived": 1000,
      "taxableIncome": 1000
    }
  },
  "links": [
    {
      "href": "/individuals/calculations/RW399019B/self-assessment/f2fb30e5-4ab6-4a29-b3c1-c7264259ff1c/taxable-income",
      "rel": "self",
      "method": "GET"
    },
    {
      "href": "/individuals/calculations/RW399019B/self-assessment/f2fb30e5-4ab6-4a29-b3c1-c7264259ff1c",
      "rel": "metadata",
      "method": "GET"
    }
  ]
}
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

businessProfitAndLoss
object
optional

Details the profit and loss position for business income sources.

selfEmployments
array
optional

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

selfEmploymentId
string
required

A unique identifier for the self-employment business income source.

Must conform to the regular expression ^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 0 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 0 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

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 the loss arose. 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

expires
string
required

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

For example: 2018-19

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
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. The value must be between 0 and 999999999999.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 0 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

accountingAdjustments
number
optional

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

For example: -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

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

For example: 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 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: 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

ukPropertyNonFhl
object
optional

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

totalIncome
number
optional

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

For example: 2000.98

totalExpenses
number
optional

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

For example: 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 0 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

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

For example: 2001

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

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

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-forward-to-carry-sideways
savingsAndGains
object
optional

Details the breakdown of taxable savings income.

incomeReceived
number
required

The total taxed and untaxed savings income received. This value must be between 0 and 99999999999. No decimals.

For example: 2000

taxableIncome
number
required

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

For example: 2000

ukSavings
array
optional

Details of each savings account.

savingsAccountId
string
required

The unique identifier of the savings account.

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

For example: SAVKB2UVwUTBQGJ

savingsAccountName
string
required

Friendly account name. Each account name will be unique for that National Insurance number. The account name will be between 1 and 32 characters in length. Allowed characters, including spaces are: mixed case alphanumeric characters and the characters; &'()*,-./@£.

Must conform to the regular expression ^[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

dividends
object
optional

Details of dividend income.

incomeReceived
number
required

The dividends income received. This value must be between 0 and 99999999999. No decimals.

For example: 2000

taxableIncome
number
required

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

For example: 2000

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}/allowances-deductions-reliefs
Retrieve Self Assessment Tax Calculation Allowances, Deductions and Reliefs [test only]
GET

This endpoint allows you to retrieve the allowances, deductions and reliefs that have been used in the self assessment tax calculation for a given NINO and Calculation ID.

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

Authorisation

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

Path parameters

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.1.0+json
Gov-Test-Scenario
optional

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


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

For example: Bearer bb7fed3fe10dd235a2ccda3d50fb

See also fraud prevention for other request headers which will become mandatory.

Response headers

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 for other request headers which will become mandatory.

Response

HTTP status: 200 (OK)

Example calculation response.
{
  "summary": {
    "totalAllowancesAndDeductions": 1000,
    "totalReliefs": 1000
  },
  "detail": {
    "allowancesAndDeductions": {
      "personalAllowance": 1000,
      "reducedPersonalAllowance": 1000,
      "giftOfInvestmentsAndPropertyToCharity": 1000,
      "blindPersonsAllowance": 1000,
      "lossesAppliedToGeneralIncome": 1000
    },
    "reliefs": {
      "residentialFinanceCosts": {
        "amountClaimed": 1000,
        "allowableAmount": 1000,
        "rate": 10.25,
        "propertyFinanceRelief": 1000
      }
    }
  },
  "links": [
    {
      "href": "/individuals/calculations/RW399019B/self-assessment/f2fb30e5-4ab6-4a29-b3c1-c7264259ff1c/allowances-deductions-reliefs",
      "rel": "self",
      "method": "GET"
    },
    {
      "href": "/individuals/calculations/RW399019B/self-assessment/f2fb30e5-4ab6-4a29-b3c1-c7264259ff1c",
      "rel": "metadata",
      "method": "GET"
    }
  ]
}
Response table
Name Description
summary
object
required

Details the high-level allowances, deductions and reliefs for the calculation.

totalAllowancesAndDeductions
number
optional

The total allowances and deductions available to the calculation. This value must be between 0 and 99999999999. No decimals.

For example: 1000

totalReliefs
number
optional

The total reliefs available to the calculation. This value must be between 0 and 99999999999. No decimals.

For example: 1000

detail
object
required

Details the low-level allowances, deductions and reliefs for the calculation.

allowancesAndDeductions
object
optional

Details the low-level allowances and deductions for the calculation.

personalAllowance
number
optional

The annual amount of personal allowance available for the tax year. This value must be between 0 and 99999999999. No decimals.

For example: 1000

reducedPersonalAllowance
number
optional

The annual amount that the personal allowance has been reduced to. This value must be between 0 and 99999999999. No decimals.

For example: 1000

giftOfInvestmentsAndPropertyToCharity
number
optional

Investments and/or property gifts made to charity. This value must be between 0 and 99999999999. No decimals.

For example: 1000

blindPersonsAllowance
number
optional

Blind persons allowance. This value must be between 0 and 99999999999. No decimals.

For example: 1000

lossesAppliedToGeneralIncome
number
optional

Losses that have been applied to general income. This value must be between 0 and 99999999999. No decimals.

For example: 1000

reliefs
object
optional

Details the low-level reliefs for the calculation.

residentialFinanceCosts
object
optional

Details the residential finance cost reliefs for the calculation.

amountClaimed
number
required

The amount being claimed including any carry forward amounts. This value must be between 0 and 99999999999. No decimals.

For example: 1000

allowableAmount
number
optional

The lower of: finance costs not deducted, property business profits, adjusted total income (exceeding Personal Allowance). This value must be between 0 and 99999999999. No decimals.

For example: 1000

rate
number
required

The tax rate used for the calculation. The value must be between 0 and 99.99 up to 2 decimal places.

For example: 10.25

propertyFinanceRelief
number
required

Property finance relief. This value must be between 0 and 99999999999. No decimals.

For example: 1000

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 allowances, deductions and reliefs data exists for the supplied calculation ID and NINO.

404 (Not Found)

NO_ALLOWANCES_DEDUCTIONS_RELIEFS_EXIST

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

404 (Not Found)

MATCHING_RESOURCE_NOT_FOUND

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

Test data

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

Header Value (Gov-Test-Scenario) Scenario

N/A - DEFAULT

Simulates returning a tax calculation with all fields.

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.

NO_ALLOWANCES_DEDUCTIONS_RELIEFS_EXIST

Simulates the scenario where no allowances, deductions and reliefs data exists.

NOT_FOUND

Simulates the scenario where no data can be found.

UK_MULTIPLE_INCOMES_EXAMPLE

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

UK_PROP_DIVIDENDS_EXAMPLE

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

UK_PROP_GIFTAID_EXAMPLE

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

UK_PROP_SAVINGS_EXAMPLE

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

UK_SE_SAVINGS_EXAMPLE

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

SCOT_SE_DIVIDENDS_EXAMPLE

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

Close section
/individuals/calculations/{nino}/self-assessment/{calculationId}/end-of-year-estimate
Retrieve Self Assessment Tax Calculation End Of Year Estimate [test only]
GET

This endpoint allows you to retrieve the end of year Income Tax and National Insurance contribution estimates for a given NINO and Calculation ID. Only applicable for an In-year calculation.

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

Authorisation

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

Path parameters

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.1.0+json
Gov-Test-Scenario
optional

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


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

For example: Bearer bb7fed3fe10dd235a2ccda3d50fb

See also fraud prevention for other request headers which will become mandatory.

Response headers

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 for other request headers which will become mandatory.

Response

HTTP status: 200 (OK)

Retrieve End of Year Estimate
{
    "summary": {
      "totalEstimatedIncome": 20000,
      "totalTaxableIncome": 12000,
      "incomeTaxAmount": 99999999.99,
      "nic2": 2000.33,
      "nic4": 2000.33,
      "totalNicAmount": 4000.66,
      "incomeTaxNicAmount": 6000.83
    },
    "detail": {
      "selfEmployments": [
        {
          "selfEmploymentId": "XKIS00000000988",
          "taxableIncome": 99999999,
          "finalised": true
        }
      ],
      "ukPropertyFhl": {
        "taxableIncome": 99999999,
        "finalised": true
      },
      "ukPropertyNonFhl": {
        "taxableIncome": 99999999,
        "finalised": true
      },
      "ukSavings": [
        {
          "savingsAccountId": "SAVKB2UVwUTBQGJ",
          "savingsAccountName": "UK Prime Bank Account 1",
          "taxableIncome": 1000
        }
      ],
      "ukDividends": {
        "taxableIncome": 99999999
      }
    },
  "links": [
    {
      "href": "/individuals/calculations/RW399019B/self-assessment/f2fb30e5-4ab6-4a29-b3c1-c7264259ff1c/end-of-year-estimate",
      "rel": "self",
      "method": "GET"
    },
    {
      "href": "/individuals/calculations/RW399019B/self-assessment/f2fb30e5-4ab6-4a29-b3c1-c7264259ff1c",
      "rel": "metadata",
      "method": "GET"
    }
  ]
  }
Response table
Name Description
summary
object
optional

Details the high-level Income Tax and National Insurance Contributions due

totalEstimatedIncome
number
optional

The total estimated end of year income. This value must be between 0 and 99999999999.

For example: 2000

totalTaxableIncome
number
optional

The total taxable end of year income. This value must be between 0 and 99999999999. No Decimals.

For example: 2000

incomeTaxAmount
number
optional

The estimated end of year Income Tax amount. This value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 1000.12

nic2
number
optional

The estimated end of year Class 2 National Insurance contributions amount. This value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 1000.12

nic4
number
optional

The estimated end of year Class 4 National Insurance contributions amount. This value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 1000.12

totalNicAmount
number
optional

The estimated end of year combined Class 2 and Class 4 National Insurance contributions amount. This value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 1000.12

incomeTaxNicAmount
number
optional

The estimated end of year combined Class 2 and Class 4 National Insurance contributions amount. This value must be between 0 and 99999999999.99 up to 2 decimal places.

For example: 1000.12

detail
object
optional

Details the low-level taxable income amounts of each income source

selfEmployments
array
optional

A list of self-employment business detailing the taxable income estimate for each business

selfEmploymentId
string
required

An identifier for the self-employment business, unique to the customer.

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

For example: XGIS00000001319

taxableIncome
number
required

The estimated end of year income. This value must be between 0 and 99999999999. No decimals.

For example: 2000

finalised
boolean
optional

Shows whether the self-employment income has been finalised.

For example: true

ukPropertyFhl
object
optional

Details the taxable income estimate for UK Property FHL

taxableIncome
number
required

The estimated end of year income. This value must be between 0 and 99999999999. No decimals.

For example: 2000

finalised
boolean
optional

Shows whether the UK Property FHL income has been finalised.

For example: true

ukPropertyNonFhl
object
optional

Details the taxable income estimate for UK Property Non-FHL

taxableIncome
number
required

The estimated end of year taxable income. This value must be between 0 and 99999999999. No decimals.

For example: 2000

finalised
boolean
optional

Shows whether the UK Property Non-FHL income has been finalised.

For example: true

ukSavings
array
optional

Details the taxable income estimate for UK savings

savingsAccountId
string
required

The unique identifier of the savings account.

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

For example: SAVKB2UVwUTBQGJ

savingsAccountName
string
required

Friendly account name. Each account name will be unique for that National Insurance number. The account name will be between 1 and 32 characters in length. Allowed characters, including spaces are: mixed case alphanumeric characters and the characters; &'()*,-./@£.

Must conform to the regular expression ^[A-Za-z0-9 &'()*,-./@£]{1,32}$

For example: UK Prime Bank Account 1

taxableIncome
number
required

The estimated end of year taxable income. This value must be between 0 and 99999999999. No decimals.

For example: 2000

ukDividends
object
optional

Details the taxable income estimate for UK dividends

taxableIncome
number
required

The estimated end of year taxable income. This value must be between 0 and 99999999999. No decimals.

For example: 2000

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

End of year estimate data will only be returned for an in-year calculation

404 (Not Found)

END_OF_YEAR_ESTIMATE_NOT_PRESENT

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

Test data

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

Header Value (Gov-Test-Scenario) Scenario

N/A - DEFAULT

Simulates returning a tax calculation with all fields.

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.

EOY_ESTIMATE_NOT_PRESENT

Simulates the error returned when a tax calculation is not in year.

UK_MULTIPLE_INCOMES_EXAMPLE

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

UK_PROP_DIVIDENDS_EXAMPLE

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

UK_PROP_GIFTAID_EXAMPLE

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

UK_PROP_SAVINGS_EXAMPLE

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

UK_SE_GIFTAID_EXAMPLE

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

UK_SE_SAVINGS_EXAMPLE

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

SCOT_SE_DIVIDENDS_EXAMPLE

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

Close section
/individuals/calculations/{nino}/self-assessment/{calculationId}/messages
Retrieve Self Assessment Tax Calculation Messages [test only]
GET

This endpoint allows you to retrieve 'info', 'warning' and 'error' level messages linked to a Calculation ID. One or more error messages for a Calculation ID means a calculation could not be performed. Vendor software should surface these messages to the end user.

Authorisation

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

Path parameters

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

Query parameters

Query parameters table
Name Description
type
string
optional

The 'type' query parameter allows the messages output to be filtered by type. The type parameter can be supplied more than once; e.g. ?type=info&type=warning.

Limited to the following possible values:

info
warning
error

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.1.0+json
Gov-Test-Scenario
optional

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


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

For example: Bearer bb7fed3fe10dd235a2ccda3d50fb

See also fraud prevention for other request headers which will become mandatory.

Response headers

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 for other request headers which will become mandatory.

Response

HTTP status: 200 (OK)

Retrieve Calculation Messages with info messages
{
  "info": [
    {
      "id": "C22203",
      "text": "Class 2 National Insurance has not been charged as your self-employed profits are under the small profit threshold."
    },
    {
      "id": "C11101",
      "text": "You have entered a large amount in total Gift Aid payments. Please check"
    }
  ],
  "links": [
    {
      "href": "/individuals/calculations/RW399019B/self-assessment/f2fb30e5-4ab6-4a29-b3c1-c7264259ff1c/messages",
      "rel": "self",
      "method": "GET"
    },
    {
      "href": "/individuals/calculations/RW399019B/self-assessment/f2fb30e5-4ab6-4a29-b3c1-c7264259ff1c",
      "rel": "metadata",
      "method": "GET"
    }
  ]
}
Retrieve Calculation Messages with info and warning messages
{
  "info": [
    {
      "id": "C22201",
      "text": "Your BRT limit has been increased by 3000 to 35000 for Gift Aid payments."
    }
  ],
  "warnings": [
    {
      "id": "C11317",
      "text": "Class 4 exemption - calculation has been adjusted Individual’s age is equal to or greater than 16 years old on the 6th April of current tax year."
    },
    {
      "id": "C11509",
      "text": "Property Income Allowance has been claimed and therefore no further expenses can be claimed."
    }
  ],
  "links": [
    {
      "href": "/individuals/calculations/RW399019B/self-assessment/f2fb30e5-4ab6-4a29-b3c1-c7264259ff1c/messages",
      "rel": "self",
      "method": "GET"
    },
    {
      "href": "/individuals/calculations/RW399019B/self-assessment/f2fb30e5-4ab6-4a29-b3c1-c7264259ff1c",
      "rel": "metadata",
      "method": "GET"
    }
  ]
}
Retrieve Calculation Messages with warning and error messages
{
  "warnings": [
    {
      "id": "C11009",
      "text": "Period submissions include gaps"
    },
    {
      "id": "C11010",
      "text": "Period submissions include overlaps"
    },
    {
      "id": "C11101",
      "text": "Please check you have entered the correct amount of total gift aid payments"
    }
  ],
  "errors": [
    {
      "id": "C95005",
      "text": "Final confirmation of income and expenses for all business sources has not been provided"
    }
  ],
  "links": [
    {
      "href": "/individuals/calculations/RW399019B/self-assessment/f2fb30e5-4ab6-4a29-b3c1-c7264259ff1c/messages",
      "rel": "self",
      "method": "GET"
    },
    {
      "href": "/individuals/calculations/RW399019B/self-assessment/f2fb30e5-4ab6-4a29-b3c1-c7264259ff1c",
      "rel": "metadata",
      "method": "GET"
    }
  ]
}
Retrieve Calculation Messages with error messages
{
  "errors": [
    {
      "id": "C11103",
      "text": "Gift aid payments made this year treated as paid in the previous year cannot exceed the total gift aid payments. Please check."
    }
  ],
  "links": [
    {
      "href": "/individuals/calculations/RW399019B/self-assessment/f2fb30e5-4ab6-4a29-b3c1-c7264259ff1c/messages",
      "rel": "self",
      "method": "GET"
    },
    {
      "href": "/individuals/calculations/RW399019B/self-assessment/f2fb30e5-4ab6-4a29-b3c1-c7264259ff1c",
      "rel": "metadata",
      "method": "GET"
    }
  ]
}
Response table
Name Description
info
array
optional

A list of info messages relating to the calculation ID.

id
string
required

The ID of the message.

text
string
required

The message text.

warnings
array
optional

A list of warning messages relating to the calculation ID.

id
string
required

The ID of the message.

text
string
required

The message text.

errors
array
optional

A list of error messages relating to the calculation ID.

id
string
required

The ID of the message.

text
string
required

The message text.

links
array
optional

A list of endpoint links that indicate possible actions related to the current resource

href
string
required

The relative url of the endpoint

For example: /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 format of the type query parameter is not valid

400 (Bad Request)

FORMAT_TYPE

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

403 (Forbidden)

CLIENT_OR_AGENT_NOT_AUTHORISED

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

404 (Not Found)

MATCHING_RESOURCE_NOT_FOUND

No messages are present for the supplied types or no messages exist for that calculation ID.

404 (Not Found)

NO_MESSAGES_PRESENT

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

Test data

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

Header Value (Gov-Test-Scenario) Scenario

N/A - DEFAULT

Simulates returning a tax calculation with info and warning messages.

NOT_FOUND

Simulates the scenario where no data can be found for this calculations ID.

NO_MESSAGES_PRESENT

Simulates the scenario where a tax calculation is found, but no messages exist. This error can also be returned by the use of filters.

MESSAGES_INFO

Simulates returning a tax calculation with info messages.

MESSAGES_INFO_WARNINGS

Simulates returning a tax calculation with info and warning messages.

MESSAGES_WARNINGS

Simulates returning a tax calculation with warning messages.

MESSAGES_WARNINGS_ERRORS

Simulates returning a tax calculation with warning and error messages.

MESSAGES_ERRORS

Simulates returning a tax calculation with error messages.

Close section
Back to top
Get help with this page. Get help with this page.
  • Cookies
  • Privacy policy
  • Terms and conditions
  • Help using GOV.UK

Open Government Licence

All content is available under the Open Government Licence v3.0, except where otherwise stated

© Crown Copyright