File UK Making Tax Digital VAT returns via the HMRC API

Steps

1. Register your application on the HMRC Developer Hub at developer.service.hmrc.gov.uk and subscribe to the VAT (MTD) API v1.0; obtain OAuth 2.0 client credentials for the production environment.
2. Complete the OAuth 2.0 authorization code flow on behalf of the business (or agent); the business must authorize your application through HMRC's grant page, after which you receive an access token scoped to write:vat.
3. Call GET /organisations/vat/{vrn}/obligations with date range parameters to retrieve open obligation periods and identify the periodKey for the period you intend to file.
4. Calculate the 9-box VAT figures from the business's accounting records and POST them to /organisations/vat/{vrn}/returns with the periodKey and set the finalised boolean to true; HMRC will reject submissions where finalised is false.
5. Handle the response: a 201 Created confirms acceptance; a 400 with error code INVALID_REQUEST indicates a calculation mismatch — HMRC validates that box 5 equals box 3 minus box 4.
6. Retrieve a copy of the submitted return via GET /organisations/vat/{vrn}/returns/{periodKey} and store it with the submission timestamp as evidence of timely filing.