What actually happens when your software files an MTD update

Why nobody tells you this

Every guide to Making Tax Digital ends at the same sentence: connect your software to HMRC, and your software does the rest. It is true, and it is useless. You are about to hand a company the ability to file tax on your behalf, and the standard explanation of what that involves is a shrug.

So this is the rest. It is what our software does, four times a year, written down. Some of it will make you more comfortable. The part about the headers may make you less comfortable, and you should probably know it anyway.

First, the handshake, and the clock you cannot see

When you press “connect to HMRC”, you are sent to HMRC's own site, not ours. You sign in there, you approve the permissions there, and HMRC sends you back with a code. That code is worth ten minutes and can be used once.

Your software trades it for two tokens, and their lifetimes are the thing worth understanding.

The eighteen months is the one to remember. HMRC is explicit: after eighteen months refresh tokens stop working, and you must go through the authorisation process again. No software can engineer around that. When your provider asks you to reconnect to HMRC in 2028, it is not being lazy. It is being obeyed.

Then your software tells HMRC about your computer

This is the part almost nobody writes about, and it is the part you would most want to know.

HMRC requires fraud prevention headers on every Making Tax Digital call. Not as a nice-to-have. In HMRC's own words: “You are required by law to submit header data for the VAT (MTD) and Income Tax Self Assessment (MTD) APIs.” Software that keeps sending missing or incorrect data can be fined and blocked from HMRC's APIs.

For a web application like ours, that is eleven mandatory headers and five conditional ones. Here is what actually goes over the wire about you.

Read that list again as a landlord rather than as an engineer. Gov-Client-Screens is the resolution and colour depth of your monitor. Gov-Client-Window-Size is how big your browser window was. Gov-Client-Timezone is where you are. Gov-Client-Public-IP-Timestamp is when your IP address was captured. HMRC is building a fingerprint of the machine that filed your tax, so that if someone else files as you, the fingerprint will not match.

That is a defensible thing for a tax authority to want. It is also a thing you were never told about, by anyone, before you clicked connect.

The two headers we do not send, and why

HMRC is blunt that you must submit data for every header your connection method lists, and that you are required by law to do so. It does not call any of them optional. But for a few, its own guidance names circumstances in which you will not be able to collect a value, and then tells you to follow its missing-data guidance. We omit two, and we have told HMRC exactly why.

A third conditional header, Gov-Client-Public-Port, was the awkward one. Our API runs at the Cloudflare edge, which does not expose your browser's source port, so for a time we omitted it too. We now collect it, on every call, from a dedicated service we built for the purpose. That has its own story: why your MTD software asks for your device details.

This is not a technicality. HMRC requires fraud prevention headers in sandbox calls before it will grant production access, and says they “will be checked by a specialist team”. Getting this wrong does not produce a polite error. It produces a conversation with HMRC.

Now the filing itself: six calls, one of which matters

Here is the sequence, with the API versions that are live today.

Call three is the only one that submits anything, and it is a single PUT:

HMRC replies 204 No Content. No body, no cheerful message: just a 204 and an X-CorrelationId you can quote back to HMRC if you ever need to. The absence of an error is the success, which takes some getting used to, and is why good software goes back and checks the obligation afterwards rather than trusting the silence.

And that check needs patience. HMRC says it “may take up to an hour for the obligation to be marked as fulfilled”. If you file on the afternoon of 7 August and your dashboard still says “open” ten minutes later, nothing is wrong.

Three things about that number it shows you afterwards

Calls four to six exist to produce a tax estimate, and there is more sharp edge here than anyone admits.

It is asynchronous. Your software asks HMRC to calculate, gets back 202 Accepted and an ID, and then has to wait: HMRC says software should wait at least five seconds before retrieving the result, to avoid an error. So the little spinner you see is real. It is your software counting to five because HMRC asked it to.

It is an estimate. It is computed from whatever HMRC has received so far, which in July is one quarter of your property income and none of your employment income, dividends or savings. It is not your bill, and treating it as one is the fastest way to be unpleasantly surprised in January 2028.

And it is not the filing. The final declaration is a separate two-step operation entirely, and it is the point at which you say “this is my tax return” rather than “here are my figures”. As an aside for anyone who has read older documentation: HMRC's spec calls it the final declaration “(previously known as crystallisation)”, and yet the Obligations API still has an endpoint with the word crystallisation sitting in the path. The term was retired. The word was not.

What happens if you file twice

Nothing bad, and the reason is worth understanding, because it is not the reason you would expect.

HMRC publishes no idempotency mechanism for these APIs. There is no idempotency key, no header, nothing in the reference guide. If you are hoping the platform will politely detect and discard a duplicate submission, it will not, because it has no way of knowing that is what you meant.

What actually protects you is the shape of the data. Quarterly updates are cumulative from 6 April, and the submission is a PUT that replaces the entire record for the tax year. Send it twice and the second one overwrites the first with the same numbers. You are safe because of the data model, not because of a guarantee. That is a meaningful distinction, and one you will not find stated anywhere in HMRC's documentation, because it is a property of the design rather than a feature of it.

What “HMRC approved” actually means

Before anyone can file for real, HMRC requires three things: that the relevant APIs and endpoints have been tested satisfactorily, that calls include compliant fraud prevention headers, and that a Production Approvals Checklist is completed and matches the testing. A specialist team then reads your sandbox logs.

The header data described above is central to it. HMRC requires that fraud prevention headers are included in sandbox calls, and says those “will be checked by a specialist team”. It separately tells developers to “test with a variety of user IDs, devices, browsers, and screen sizes” to confirm the header spec is implemented correctly. Not your user interface. Not your pricing. Whether the data you send about your customers is accurate.

One caveat about the phrase itself. There is no longer a public, browsable table of recognised software to check a vendor against. HMRC published a personalised finder tool in July 2025, which asks you questions and returns a filtered list, and the older static compatibility-list page has since been redirected. So “HMRC approved” is harder to check than it was: you have to run the finder yourself rather than scan a published table. Ask a vendor which APIs and versions they are approved for. If the answer is vague, that tells you something.

The small print your software lives inside

• HMRC’s standard rate limit is 3 requests per second per application. Exceed it and you get a 429, with the error MESSAGE_THROTTLED_OUT.
• The sandbox has a stateful mode, where you can submit data and read it back. Test users are deleted after three months without use.
• There is a Test Fraud Prevention Headers API to validate your headers, and HMRC warns you not to treat passing it as a guarantee that production will accept them.
• The cumulative endpoint is only available for tax years from 2025-26. The old per-period endpoints still exist, and still serve the years up to 2024-25.

Common questions

Sources

All from HMRC's developer hub and its own published specifications. Note that the developer hub does not stamp its pages with a last-updated date, so these were checked live on 14 July 2026 and are stated as at that day, no stronger.

• HMRC: user-restricted endpoints (the 4-hour and 18-month token lifetimes)
• HMRC: send fraud prevention data (the legal requirement, and the fine-and-block)
• HMRC: fraud prevention, web app via server (the exact header list)
• HMRC: how to integrate (production approval, and the sandbox log inspection)
• HMRC: tax calculations (asynchronous, and the five-second wait)
• HMRC: Property Business (MTD) API v6.0 (the cumulative period summary, currently published as beta)
• HMRC: making updates during the tax year (the “up to an hour” obligation lag)
• HMRC: reference guide (the 3-per-second rate limit)

Related

• Why your second MTD update looks twice as big as your first
• The landlord's compliance year: every date that actually matters