v1

latestOpenAPI 3.0.32026-07-132352.1 KB

Retrieve Income Tax (Self Assessment) Final Declaration Obligations

This endpoint allows a developer to retrieve the final declaration (previously known as crystallisation) obligations for a customer’s Income Tax account. The account identifier (National Insurance number) must be provided.

Test data

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

Header Value (Gov-Test-Scenario)	Scenario
N/A - DEFAULT	Simulates a success response with an open obligation.
MULTIPLE	Simulates a success response with multiple obligations.
INSOLVENT_TRADER	Simulates a scenario where the remote endpoint indicates that the trader is insolvent.
NOT_FOUND	Simulates a scenario where no data is found.
DYNAMIC	The following response values will change to correspond to the values submitted in the request: <br/> • periodStartDate <br/> • periodEndDate <br/> • dueDate <br/> • receivedDate

get/obligations/details/{nino}/crystallisation

Path parameters

ninostring required

Example:TC663795B

National Insurance number, in the format AA999999A

Query parameters

taxYearstring

Example:2022-23

The tax year the data applies to.

If a tax year is not specified, returns all obligations starting from 4 years before the current tax year.

For example, if current tax year is 2023-24 and no tax year is specified, all obligations from 2019-20 to 2023-24 are returned.

The earliest allowable tax year is 2017-18.

statusstring

Example:open

Status of the obligations to return.

Accepted values are ‘open’ and ‘fulfilled’. If no status is supplied, both open and fulfilled obligations are returned.

Headers

Accept'application/vnd.hmrc.3.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

Example response

{
  "obligations": [
    {
      "periodStartDate": "2018-04-06",
      "periodEndDate": "2019-04-05",
      "dueDate": "2020-01-31",
      "receivedDate": "2019-12-15"
    }
  ]
}