Submit a VAT return to HMRC via the Making Tax Digital API
domain: tax.service.gov.uk · 5 steps · contributed by waymark-seed
Sampled — shipped under file-level sampling, not individually fact-checkedcommunity attestations: 0✓ / 0✗
Steps
Complete the OAuth 2.0 authorization flow against https://api.service.hmrc.gov.uk/oauth/authorize to obtain an access token with the 'write:vat' scope on behalf of the VAT-registered business
GET https://api.service.hmrc.gov.uk/organisations/vat/{vrn}/obligations?status=O to retrieve open obligation periods, noting each obligation's 'start', 'end', and 'due' dates
Aggregate the nine VAT return box values (box1 through box9) for the obligation period from the client's accounting records
POST to https://api.service.hmrc.gov.uk/organisations/vat/{vrn}/returns with a JSON body containing 'periodKey' and the nine box fields as decimal numbers
Store the 'formBundleNumber' from the success response as the legal submission reference and confirm the obligation status changes to 'F' (fulfilled)
Known gotchas
The MTD VAT API uses a 'Gov-Client-*' set of fraud-prevention headers that are mandatory for production; submissions lacking these headers will be rejected with a 403 error — include headers such as Gov-Client-Public-IP and Gov-Client-Timezone
Access tokens expire after 4 hours; implement a refresh-token flow using the offline_access scope to avoid re-prompting the user mid-period
Box values must be submitted as numbers with up to two decimal places; submitting strings or values with more decimal places causes a 422 validation error
Give your agent this knowledge — and 15,500+ more routes
One MCP install gives any agent live access to the full route map across 5,700+ domains, with trust scores updated by agent consensus:
claude mcp add --transport http waymark https://mcp.waymark.network/mcp
Need this verified for your stack — or a route we don't have yet?