v1

latestOpenAPI 3.0.32026-07-1342625.4 MB

Final Declaration

Submit a Self Assessment Final Declaration

This endpoint allows the developer to submit a final declaration for a tax year by agreeing to the HMRC's tax calculation.

A National Insurance number, tax year and calculation ID 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 - DEFAULT	Simulates success response.
OUTSIDE_AMENDMENT_WINDOW	Simulates the scenario where the request cannot be completed as it is outside the amendment window.
FINAL_DECLARATION_IN_PROGRESS	Simulates the scenario where there is a calculation in progress for the tax year.
FINAL_DECLARATION_RECEIVED	Simulates the scenario where a final declaration has already been received.
FINAL_DECLARATION_TAX_YEAR	Simulates the scenario where the final declaration cannot be submitted until after the end of the tax year.
INCOME_SOURCES_CHANGED	Simulates the scenario where information relating to an income source has changed.
INCOME_SOURCES_INVALID	Simulates the scenario where a valid income source cannot be found.
NO_INCOME_SUBMISSIONS_EXIST	Simulates the scenario where no income submissions exist.
RECENT_SUBMISSIONS_EXIST	Simulates the scenario where more recent submissions exist.
RESIDENCY_CHANGED	Simulates the scenario where residency has changed.
SUBMISSION_FAILED	Simulates the scenario where a submission has failed.
TAX_YEAR_NOT_SUPPORTED	Simulates the scenario where the specified tax year is not supported.
NOT_FOUND	Simulates the scenario where the supplied income source could not be found.

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

calculationIdstring required

Example:f2fb30e5-4ab6-4a29-b3c1-c7264259ff1c

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

calculationTypestring required

Example:final-declaration

Specifies the calculation types to be confirmed. Limited to the following possible values for TY24-25 and before: final-declaration

Limited to the following possible values for TY25-26 onwards: 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 write:self-assessment scope.

Gov-Test-Scenariostring

Example:-

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

Response

Success