How to Use the HMRC MTD API Without a Computer Science Degree

If someone told you that filing your tax return now involves REST APIs, OAuth 2.0 tokens, and JSON payloads, you would be forgiven for wondering whether HMRC had confused you with a software engineer. The HMRC MTD API is the technical backbone of Making Tax Digital, and while most sole traders will never touch it directly, understanding what it does, and what it does not do, could save you from expensive software choices and a great deal of unnecessary panic.

What the HMRC MTD API Actually Is

An API, in plain English, is a structured conversation between two pieces of software. When your MTD app sends your Q1 income figures to HMRC, it does not fill in a web form. It sends a precisely formatted message to HMRC's servers using the MTD API, and HMRC's system sends a structured reply confirming receipt. Think of it as a very formal, very fast postal system that never loses letters, provided the address is right.

HMRC began building the MTD API infrastructure in 2017 alongside the first wave of MTD for VAT. The income tax version, formally called the MTD for Income Tax Self Assessment (ITSA) API, has been in development ever since, with the mandatory start date for sole traders earning above £50,000 set for April 2026 and those earning above £30,000 following in April 2027.

The API handles several distinct tasks. It accepts quarterly updates of income and expenses. It processes end-of-period statements. It calculates your tax liability in real time and returns a figure your software can display. It also manages the Business Income Source Summary (BISS), which consolidates your figures at year end. Each of these tasks has its own API endpoint, which is developer-speak for a specific address on HMRC's servers that accepts a specific type of request.

Who Actually Needs to Understand the API?

Here is the reassuring news: almost certainly not you.

If you are a plumber, electrician, freelance graphic designer, or any other sole trader preparing for MTD compliance, your job is to choose MTD-compatible software and log your income and expenses regularly. The software handles every interaction with the HMRC MTD API on your behalf. You will never see an access token, never write a JSON object, and never worry about HTTP status codes.

The people who genuinely need to understand the HMRC MTD API at a technical level fall into three groups. First, software developers building or maintaining MTD-compatible products. Second, accountants and bookkeepers who are building bespoke solutions for clients with complex needs. Third, technically confident sole traders who want to build their own bridging solution using spreadsheets, a subject covered in more depth in Can I Use Spreadsheets for Making Tax Digital?.

For everyone else, understanding the API at a conceptual level, knowing what it does, why it exists, and how your software uses it, is genuinely useful. It helps you evaluate software, ask better questions of your accountant, and understand why MTD compliance is not simply a matter of emailing a spreadsheet to HMRC.

How the API Authentication Works

Before any software can send data to HMRC on your behalf, it must prove that you have authorised it to do so. HMRC uses a security protocol called OAuth 2.0 for this, the same system that powers "Sign in with Google" buttons across the internet.

The process works like this. You create an HMRC Government Gateway account and sign up for MTD for Income Tax. You then connect your chosen software to HMRC by logging into your Government Gateway within the software's own interface. HMRC issues your software an access token, a long string of characters that acts as a temporary key. That token expires after a set period and must be refreshed, which reputable MTD software does automatically.

From your perspective, this looks like clicking "Connect to HMRC" in your app and logging in once. Behind the scenes, your software is completing the OAuth handshake with HMRC's authorisation server, storing your token securely, and using it to sign every subsequent API request it makes on your behalf. If you have ever connected a banking app to an HMRC service, you have already been through a version of this process.

The reason HMRC chose OAuth rather than simply asking for your password is security. Your software never knows your Government Gateway password. It only holds a temporary token that can be revoked instantly if you disconnect the software. This is materially more secure than older approaches where software stored credentials directly.

The Five MTD API Endpoints a Sole Trader's Software Uses

Your MTD software quietly makes calls to several different parts of the HMRC API throughout the year. Here is what each one does, translated from developer documentation into something a sole trader earning £60,000 a year actually needs to know.

Quarterly Update Submission

Four times a year, your software sends your income and allowable expenses to HMRC using the Self Employment (SE) periodic updates endpoint. This is not a payment. It is a data submission, a digital summary of what you earned and spent in that quarter. HMRC uses it to build a running picture of your tax position. The quarterly deadlines under MTD are the 7th of the month following each quarter end, so 7 August, 7 November, 7 February, and 7 May. Miss these and HMRC's penalty points system activates, as detailed in MTD Penalty Points System: The Debt Trap Few Expect.

Annual Summary

At the end of the tax year, your software submits an annual summary that covers any income or adjustments not captured in the quarterly updates. This is where you add things like allowances, reliefs, and Class 4 National Insurance adjustments.

End-of-Period Statement

The End-of-Period Statement (EOPS) is your formal declaration that the figures submitted are correct and complete. It replaces the current Self Assessment return as the point at which you legally confirm your income. Your software submits this via a dedicated API endpoint, and you must make a positive declaration within the software before it goes.

Final Declaration

The Final Declaration is the MTD equivalent of the current Self Assessment filing. It crystallises your tax liability for the year, incorporating all income sources, not just self-employment. Your software calls the Final Declaration API endpoint once you have confirmed all figures are correct.

Tax Calculation

At any point during the year, your software can call HMRC's calculation API to retrieve an estimate of your current tax liability. This is the genuinely useful part of MTD that HMRC does not advertise loudly enough. Rather than discovering in January that you owe £8,000 in April, you can see a running estimate throughout the year and set money aside accordingly. If you want to understand what that liability might look like before you even start using MTD software, Tax Refund Estimate Before Self Assessment: Do the Maths Now is worth reading first.

If You Want to Explore the API Yourself

For the technically curious, HMRC provides a sandbox environment where developers and savvy sole traders can test API connections without affecting real tax records. The sandbox is available through HMRC's Developer Hub at developer.service.gov.uk, and it uses simulated Government Gateway credentials so nothing you do there touches your actual tax account.

To access the sandbox, you register as a developer on HMRC's portal, create a test application, and use HMRC's provided test credentials to simulate the OAuth authentication flow. HMRC provides a set of test scenarios including successful submissions, validation errors, and API timeouts, which is useful if you are building a bridging solution using a spreadsheet and a simple script.

For most sole traders, this is firmly in the "interesting but unnecessary" category. But if you are a freelance developer, a technically confident tradesperson who manages their own accounts, or someone building a lightweight solution to avoid paying £30 a month for software you only use five times a year, the HMRC sandbox is free, well-documented, and considerably less frightening than it sounds.

Why This Matters for Choosing Your MTD Software

Here is where understanding the API has direct practical value. Not all software marketed as "MTD-ready" is actually connected to the HMRC MTD API for income tax. Some products are compliant for VAT but have not yet built out their ITSA integration. Others use bridging software, a layer that sits between your spreadsheet and the API, which is legitimate but adds a step and sometimes a cost.

When evaluating MTD software, ask one direct question: is this product listed on HMRC's approved MTD for Income Tax software list? HMRC maintains a public register of recognised software at gov.uk/guidance/software-for-making-tax-digital. If a product is not on that list, it cannot legally submit quarterly updates on your behalf regardless of what its marketing says.

For a full breakdown of what different MTD software products charge and what you actually get, MTD Software Pricing Comparison 2026: Who Charges What covers the market in detail. The short version: you should not be paying more than £10 to £15 per month for a clean, API-connected MTD solution as a straightforward sole trader. If a vendor is charging £30 or £40 and bundling in payroll features you will never use, you are subsidising their enterprise clients.

TapTax connects directly to the HMRC MTD API and handles all authentication, token refresh, and submission formatting in the background. For a sole trader with one business, no employees, and a reasonable level of income, that is all you need. There is no coding, no sandbox testing, and no OAuth documentation required.

The Honest Limitation of API-Based MTD

The MTD API is not perfect. Early adopters in the voluntary pilot reported intermittent API errors that resulted in submission failures, though HMRC has improved stability significantly since 2022. The API also has rate limits, meaning software cannot hammer HMRC's servers with repeated requests, which occasionally causes delays during peak filing periods.

More structurally, the API cannot currently handle every income type that sole traders have. Complex cases involving Lloyd's underwriters, ministers of religion, or certain partnership arrangements require workarounds or manual intervention. HMRC has committed to expanding API coverage over time, but if your tax affairs are genuinely complex, speak to an accountant before assuming your software handles everything.

For the overwhelming majority of sole traders, those with a single self-employment business, no employees on payroll, and income between £30,000 and £80,000, the API handles everything without incident. The quarterly update process is straightforward, the tax calculation endpoint is genuinely useful, and the final declaration is no more complicated than the current Self Assessment process, just more frequent.

What You Actually Need to Do Before April 2026

You do not need to understand JSON. You do not need a Developer Hub account. You do not need to know what OAuth 2.0 is. What you do need is MTD-compatible software connected to the HMRC MTD API, a Government Gateway account enrolled for MTD for Income Tax, and a habit of recording income and expenses at least monthly so that each quarterly update takes minutes rather than hours.

If your gross self-employment income exceeds £50,000 in the 2024/25 or 2025/26 tax year, April 2026 is not a distant deadline. It is one tax year away. The time to choose software, test it, and build the habit of digital record-keeping is now, not in March 2026 when every MTD provider will be overwhelmed with last-minute sign-ups.

Start with HMRC's list of approved software. Ask whether the product connects natively to the MTD ITSA API or uses a bridging layer. Check whether it handles your specific income type. Then sign up, connect to HMRC, and let the API do what it was built to do: take the administrative weight of tax compliance and move it invisibly into the background of your working week.

The HMRC MTD API is, ultimately, a piece of infrastructure you will never see. Like the wiring behind a socket, you do not need to understand how it works to benefit from the electricity.

You might also like

Photo: Unsplash

MTD Guides

TapTax: The MTD App Built for Sole Traders

TapTax makes Making Tax Digital simple for UK sole traders. Quarterly submissions, digital records, and no jargon. Here's exactly what it does and who it's for.

3 Jun 20268 min read

Photo: Unsplash

MTD Guides

YouTube Creator Tax Return: What HMRC Wants From You

YouTube income is taxable in the UK from pound one. Here's what sole trader creators must declare, what they can claim, and what MTD changes from 2026.

2 Jun 20268 min read

Photo: Unsplash

MTD Guides

Freelance Writer Tax Return UK 2026: What Changes Now

From April 2026, freelance writers earning over £50,000 must file quarterly under MTD. Here's exactly what that means for your tax return and your income.

1 Jun 20268 min read