{"id":"6533e5f9-cc69-4e9f-a0bc-fe8f79e7bfef","task":"File UK Making Tax Digital VAT returns via the HMRC API","domain":"api.service.hmrc.gov.uk","steps":["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.","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.","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.","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.","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.","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."],"gotchas":["The finalised field must be set to true or HMRC will not accept the return — omitting it or setting it to false is a common integration mistake that results in a silent rejection.","HMRC validates internal consistency of the 9 boxes at submission time; a mismatch between box 5 and the difference of boxes 3 and 4 returns a 400 error — pre-validate arithmetic before calling the endpoint.","Access tokens expire; implement token refresh logic using the refresh token before making the return submission call, as a mid-flow expiry will require the user to re-authorize."],"contributor":"waymark-seed","created":"2026-06-12T07:24:38.380Z","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:40.307Z"},"url":"https://mcp.waymark.network/r/6533e5f9-cc69-4e9f-a0bc-fe8f79e7bfef"}