v1

latestOpenAPI 3.0.32026-07-131728.7 KB

Retrieve ITSA Status

This endpoint enables you to retrieve an ITSA status for an HMRC customer for a specified tax year, and optionally future years after that tax year. A National Insurance number and tax year must be provided. An ITSA status is always available for each tax year from the year the customer signed up for MTD to the current year. Availability of status after the current year varies, depending on factors such as the customer's annual return submissions.

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.
NOT_FOUND	Simulates the scenario where no data is found.
NOT_ENROLLED	Simulates the scenario where a Client is not MTD Enrolled
STATEFUL	Performs a stateful retrieve.

get/individuals/person/itsa-status/{nino}/{taxYear}

Path parameters

ninostring required

Example:TC663795B

National Insurance number, in the format AA999999A

taxYearstring required

Example:2023-24

The tax year to retrieve data for. The start year and end year must not span two tax years. No gaps are allowed, for example, 2023-25 is not valid. There is no minimum tax year.

Query parameters

futureYearsboolean

The status of future tax years. When set to true, the API will return the future tax years from the specified tax years if present. The default is false

historyboolean

The history status of the specified tax year. When set to true, the API will return history of the specified tax year (and future years if the futureYear flag is set to true). The default is false

Headers

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

{
  "itsaStatuses": [
    {
      "taxYear": "2023-24",
      "itsaStatusDetails": [
        {
          "submittedOn": "2021-03-23T16:02:34.039Z",
          "businessIncome2YearsPrior": 99999999999.99
        }
      ]
    }
  ]
}