Sign in

v1

latestOpenAPI 3.0.32026-07-1342625.4 MB
Tax Calculations

List Self Assessment Tax Calculations

This endpoint enables you to list Self Assessment tax calculations for a given National Insurance number and tax year.

A National Insurance number must be provided.

Test data

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

Header Value (Gov-Test-Scenario)Scenario
N/A - DEFAULTSimulates success response.
NOT_FOUNDSimulates the scenario where no data is found.
DYNAMICThe following response parameters will be based on the data submitted in the request: <br><br/> • taxYear <br/> • calculationTimestamp <br/> • finalDeclarationTimestamp
get/individuals/calculations/{nino}/self-assessment/{taxYear}

Path parameters

ninostring required
Example:TC663795B

National Insurance number, in the format AA999999A

taxYearstring required
Example:2021-22

The tax year the data applies to, for example, 2021-22. The start year and end year must not span two tax years. The minimum tax year is 2017-18. No gaps are allowed, for example, 2020-22 is not valid.

Query parameters

calculationTypestring

This field is used to filter API response based on given calculation type. Tax years 23-24 and 24-25 will accept the following values:

  • in-year
  • intent-to-finalise
  • final-declaration

Tax years 25-26 onwards will accept the following values:

  • in-year
  • intent-to-finalise
  • intent-to-amend
  • final-declaration
  • confirm-amendment

Headers

Accept'application/vnd.hmrc.8.0+json' required

Specifies the response format and the version of the API to be used.

Authorizationstring required
Example:Bearer bb7fed3fe10dd235a2ccda3d50fb

An OAuth 2.0 Bearer Token with the read:self-assessment scope.

Gov-Test-Scenariostring
Example:-

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

Response

Success

OR
OR

Example response

{
  "calculations": [
    {
      "calculationId": "f2fb30e5-4ab6-4a29-b3c1-c7264259ff1c",
      "calculationTimestamp": "2019-07-13T07:51:43.112Z",
      "taxYear": "2020-21",
      "totalIncomeTaxAndNicsDue": 2000.58,
      "finalDeclarationTimestamp": "2019-07-13T07:51:43.112Z"
    }
  ]
}