Sign in

v1

latestOpenAPI 3.0.32026-07-132546.7 KB
Endpoints

Request HMRC Assist feedback for VAT [test only]

Send VAT return data, to receive feedback from HMRC before formally submitting a VAT return.

The response will contain feedback messages in English and Welsh, highlighting potential mistakes or discrepancies in the VAT return data.

Note: Before using this endpoint, you must first call the obligations endpoint on the VAT (MTD) API to get the period key.

Test data

<p>Scenario simulations using Gov-Test-Scenario headers are only available in the sandbox environment.</p> <table> <thead> <tr> <th>Header Value (Gov-Test-Scenario)</th> <th>Scenario</th> </tr> </thead> <tbody> <tr> <td><p>Default (No header value)</p></td> <td><p>Simulates the scenario where there is one HMRC Assist feedback message.</p></td> </tr> <tr> <td><p>MULTIPLE_FEEDBACK</p></td> <td><p>Simulates the scenario where there are more than one HMRC VAT Assist feedback messages.</p></td> </tr> <tr> <td><p>NO_FEEDBACK</p></td> <td><p>Simulates the scenario where there is no HMRC VAT Assist feedback.</p></td> </tr> <tr> <td><p>INVALID_VRN</p></td> <td><p>Simulates the scenario where the VRN has not passed validation.</p></td> </tr> <tr> <td><p>INVALID_PERIODKEY</p></td> <td><p>Simulates the scenario where the periodKey has not passed validation.</p></td> </tr> <tr> <td><p>INVALID_REQUEST</p></td> <td><p>Submission has not passed validation. Invalid values.</p></td> </tr> <tr> <td><p>TAX_PERIOD_NOT_ENDED</p></td> <td><p>Simulates the scenario where the accounting period has not ended.</p></td> </tr> <tr> <td><p>INSOLVENT_TRADER</p></td> <td><p>Simulates the scenario where the client is an insolvent trader.</p></td> </tr> </tbody> </table>
post/misc/transaction-risking/assist/{vrn}

Path parameters

vrnstring required
Example:123456789

VAT registration number. <br> A nine-digit number.

Headers

Gov-Test-Scenariostring
Example:-

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

Request body

periodKeystring required

The ID code for the period that this obligation belongs to. This should be obtained from the obligations endpoint of the VAT (MTD) API. The format is a string of four alphanumeric characters. Occasionally the format includes the # symbol.

vatDueSalesnumber required

VAT due on sales and other outputs. This corresponds to box 1 on the VAT Return form.

vatDueAcquisitionsnumber required

VAT due in the period on acquisitions of goods made in Northern Ireland from EU Member States. This corresponds to box 2 on the VAT Return form.

totalVatDuenumber required

Total VAT due (the sum of vatDueSales and vatDueAcquisitions). This corresponds to box 3 on the VAT Return form.

vatReclaimedCurrPeriodnumber required

VAT reclaimed in the period on purchases and other inputs (including acquisitions in Northern Ireland from EU member states). This corresponds to box 4 on the VAT Return form.

netVatDuenumber required

The difference between totalVatDue and vatReclaimedCurrPeriod. This corresponds to box 5 on the VAT Return form.

totalValueSalesExVATnumber required

Total value of sales and all other outputs excluding any VAT. This corresponds to box 6 on the VAT Return form. The value must be in whole pounds (no pence).

totalValuePurchasesExVATnumber required

Total value of purchases and all other inputs excluding any VAT (including exempt purchases). This corresponds to box 7 on the VAT Return form. The value must be in whole pounds (no pence).

totalValueGoodsSuppliedExVATnumber required

Total value of dispatches of goods and related costs (excluding VAT) from Northern Ireland to EU Member States. This corresponds to box 8 on the VAT Return form. The value must be in whole pounds (no pence).

totalAcquisitionsExVATnumber required

Total value of acquisitions of goods and related costs (excluding VAT) made in Northern Ireland from EU Member States. This corresponds to box 9 on the VAT Return form. The value must be in whole pounds (no pence).

Example request

{
  "periodKey": "18AD",
  "vatDueSales": 105.5,
  "totalVatDue": 105.5,
  "vatReclaimedCurrPeriod": 52.75,
  "netVatDue": 52.75,
  "totalValueSalesExVAT": 500,
  "totalValuePurchasesExVAT": 250
}

Response

Feedback returned successfully.

reportIdstring required

The unique identifier for the report.

correlationIdstring required

The correlation ID of the report.

Example response

{
  "reportId": "f2fb30e5-4ab6-4a29-b3c1-c00000000001",
  "correlationId": "c75f40a6-a3df-4429-a697-471eeec46435",
  "englishFeedback": [
    {
      "itemNumber": "001",
      "title": "VAT due on sales appears low",
      "body": "The VAT due on sales figure appears lower than expected based on your total sales value.",
      "action": "Please review box 1 and box 6 of your VAT return.",
      "links": [
        {
          "title": "VAT Notice 700",
          "url": "https://www.gov.uk/guidance/vat-notice-700-the-vat-guide"
        }
      ],
      "path": "vatDueSales"
    }
  ],
  "welshFeedback": [
    {
      "itemNumber": "001",
      "title": "VAT due on sales appears low",
      "body": "The VAT due on sales figure appears lower than expected based on your total sales value.",
      "action": "Please review box 1 and box 6 of your VAT return.",
      "links": [
        {
          "title": "VAT Notice 700",
          "url": "https://www.gov.uk/guidance/vat-notice-700-the-vat-guide"
        }
      ],
      "path": "vatDueSales"
    }
  ]
}
All 2 operations