v1

latestOpenAPI 3.0.32026-07-132352.1 KB

Retrieve Income Tax (Self Assessment) Income and Expenditure Obligations

This endpoint allows a developer to retrieve obligations for a user's business income sources. 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.
OPEN	Simulates a success response with an open obligation. <br/><br/>For a response with a self-employment business, use businessId: <br/> • XBIS12345678903 <br/>For a response with a UK property business, use businessId: <br/> • XPIS12345678903 <br/>For a response with a foreign property business, use businessId: <br/> • XFIS12345678903
FULFILLED	Simulates a success response with a fulfilled obligation. <br/><br/>For a response with a self-employment business, use businessId: <br/> • XBIS12345678902 <br/>For a response with a UK property business, use businessId: <br/> • XPIS12345678902 <br/>For a response with a foreign property business, use businessId: <br/> • XFIS12345678902
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.
NO_OBLIGATIONS_FOUND	Simulates a scenario where no obligations are found.
DYNAMIC	The following response values will change to correspond to the values submitted in the request: <br/> • fromDate <br/> • toDate <br/> • status (open or fulfilled) <br/><br/>For a response with a self-employment business, use businessId: <br/> • XBIS12345678901 <br/>For a response with a UK property business, use businessId: <br/> • XPIS12345678901 <br/>For a response with a foreign property business, use businessId: <br/> • XFIS12345678901
CUMULATIVE	Simulates a success response with cumulative quarterly updates.

get/obligations/details/{nino}/income-and-expenditure

Path parameters

ninostring required

Example:TC663795B

National Insurance number, in the format AA999999A

Query parameters

typeOfBusiness'self-employment' | 'uk-property' | 'foreign-property'

Example:self-employment

The type of business whose obligations are to be returned. If the type is not specified the default is to return obligations for all businesses. The type must be provided if "businessId" is provided.

businessIdstring

Example:XAIS12345678901

The unique identifier for the business whose obligations are to be returned.

fromDatestring

Example:2018-04-06

The start date of the range to filter obligations in the format YYYY-MM-DD. Mandatory if the “to” query parameter is supplied. If the “from” and “to” date parameters are not supplied, the date range will default to a year from today unless the status parameter is set to "open". The toDate & fromDate can be a maximum of 366 days apart.

toDatestring

Example:2019-04-05

The end date of the range to filter obligations in the format YYYY-MM-DD. Mandatory if the “from” query parameter is supplied. If the “from” and “to” date parameters are not supplied, the date range will default to a year from today unless the status parameter is set to "open". The toDate & fromDate can be a maximum of 366 days apart.

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": [
    {
      "typeOfBusiness": "self-employment",
      "businessId": "XAIS12345678910",
      "obligationDetails": [
        {
          "periodStartDate": "2018-04-06",
          "periodEndDate": "2019-04-05",
          "dueDate": "2018-04-06",
          "status": "open",
          "receivedDate": "2019-12-15"
        }
      ]
    }
  ]
}

All 2 operations