v1
latestOpenAPI 3.0.32026-07-132236.5 KBProduce a HMRC Self Assessment Assist Report
This endpoint allows a developer to request a HMRC Assist report to be generated for a customer or their agent.
<strong> A 200 OK response is returned when applicable messages are available, and a 204 No Content response is returned when there are no messages to report.</strong></p>
Test data
In the sandbox environment, responses are simulated based on specific Calculation IDs included in the request. Each Calculation ID corresponds to a predefined test scenario that defines the response outcome.
| Calculation ID | Scenario |
|---|---|
| Any valid Calculation ID except the two listed below | Simulates a scenario where a 200 OK success response is returned with a report containing assist messages. |
| 620490b4-06e3-4fef-a555-6fd0877dc7ca | Simulates a scenario where there are no messages to report and a 204 No Content success response is returned. |
| 640490b4-06e3-4fef-a555-6fd0877dc7ca | Simulates a scenario where the specified Calculation ID is not found. |
Path parameters
National Insurance number, in the format AA999999A
The tax year the data applies to, for example, 2025-26. The start year and end year must not span two tax years. No gaps are allowed, for example, 2025-27 is not valid.
The unique identifier for 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}$
Headers
Specifies the response format and the version of the API to be used.
An OAuth 2.0 Bearer Token with the read:self-assessment-assist scope.
Response
Success - messages returned
Example response
{
"reportId": "579800fe-e047-cd40-b3e4-0e14b1f183a8",
"messages": [
{
"title": "HMRC feedback: the title tells the user to review or check something in the return (placeholder title)\n",
"body": "The body section is usually one to three sentences. This section lets the user know why they are getting the message or which tax rule is relevant.\nFor example, if you use something for both business and personal reasons you can only claim allowable expenses for the business costs. (placeholder body)\n",
"action": "The action section is usually three to four sentences. It explains what the user can do to resolve the potential error.\nIn some messages this section may also warn users about consequences if they submit incorrect information.\nFor example, the user may be advised to make changes if needed to avoid interest and potential penalties. (placeholder action)\n",
"links": [
{
"title": "You can also go to GOVUK to find out about expenses when you’re self-employed. (placeholder link)",
"url": "https://www.gov.uk/expenses-if-youre-self-employed"
}
],
"path": "/individuals/business/self-employment/[nino]/[businessId]/cumulative/[taxYear] (placeholder path)"
}
],
"nino": "TC663795B",
"taxYear": "2025-26",
"calculationId": "f2fb30e5-4ab6-4a29-b3c1-c7264259ff1c",
"correlationId": "BD5A1B594995A197D528ECCF4BC6EA793C869B2F75333902F043E35561B927C4"
}