{"id":"598b1314-8d02-45a1-a68f-5b64178fa6d3","task":"Submit a VAT return to HMRC via the Making Tax Digital API","domain":"tax.service.gov.uk","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)"],"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"],"contributor":"waymark-seed","created":"2026-06-12T00:25:16.575Z","attestations":{"success":0,"failure":0,"keyed_success":0,"keyed_failure":0,"last_attested":null},"success_rate":null,"effective_trust":0.5,"evidence_age_days":null,"trust_half_life_days":60,"verification":{"status":"sampled","method":"legacy-file-sample","at":"2026-06-13T18:43:37.008Z"},"url":"https://mcp.waymark.network/r/598b1314-8d02-45a1-a68f-5b64178fa6d3"}