Sign in

v1

latestOpenAPI 3.0.32026-07-1342625.4 MB
Tax Calculations

Trigger a Self Assessment Tax Calculation

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. To trigger a final declaration self assessment tax calculation, you must set the calculationType path parameter to intent-to-finalise.

A National Insurance number and tax year must be provided.

The tax calculation process is asynchronous, so it is recommended you wait at least 5 seconds before calling the retrieval endpoint. The result of the calculation can be seen using the “Retrieve a Self Assessment Tax Calculation” endpoint.

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.
NO_INCOME_SUBMISSIONS_EXISTSimulates the scenario where no income submissions exist for the tax year.
FINAL_DECLARATION_RECEIVEDSimulates the scenario where a final declaration has already been received.
INCOME_SOURCES_CHANGEDSimulates the scenario where income sources data has changed.
RECENT_SUBMISSIONS_EXISTSimulates the scenario where more recent submissions exist.
RESIDENCY_CHANGEDSimulates the scenario where residency has changed.
CALCULATION_IN_PROGRESSSimulates the scenario where a calculation is in progress.
BUSINESS_VALIDATION_FAILURESimulates the scenario where there is a generic business validation rule failure.
TAX_YEAR_NOT_ENDEDSimulates the scenario where a triggering for a final declaration is performed before the tax year has ended.
post/individuals/calculations/{nino}/self-assessment/{taxYear}/trigger/{calculationType}

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.

calculationTypestring required
Example:in-year

Defines the calculation type requested.
Tax years 2023-24 & 2024-25 will accept the following values:

  • in-year
  • intent-to-finalise

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

  • in-year
  • intent-to-finalise
  • intent-to-amend

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 write:self-assessment scope.

Gov-Test-Scenariostring
Example:-

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

Response

Success

calculationIdstring required

The unique identifier of the calculation.

Example response

{
  "calculationId": "f2fb30e5-4ab6-4a29-b3c1-c7264259ff1c"
}
All 4 operations