MTD for Developers: A Technical Guide

Making Tax Digital sounds like a government rebranding exercise. It’s actually one of the largest API integration mandates in UK history — and if you’re building software that touches VAT, you need to understand how it works at the protocol level.

MTD requires VAT-registered businesses to keep digital records and submit VAT returns through HMRC-recognised software via their API. No more logging into the HMRC portal and typing numbers into a web form. Your software talks to HMRC’s API directly.

Here’s what that actually means for developers.

HMRC’s API Architecture

HMRC’s Making Tax Digital APIs are REST-based, JSON over HTTPS. They’re hosted on the HMRC Developer Hub at developer.service.hmrc.gov.uk.

The core VAT API has four main endpoints:

GET  /organisations/vat/{vrn}/obligations   # What periods need filing
GET  /organisations/vat/{vrn}/returns/{periodKey}  # View submitted return
POST /organisations/vat/{vrn}/returns       # Submit a return
GET  /organisations/vat/{vrn}/liabilities   # Outstanding payments
GET  /organisations/vat/{vrn}/payments      # Payment history

The {vrn} is the VAT Registration Number — a 9-digit identifier like 123456789.

Authentication uses OAuth 2.0 with HMRC as the identity provider. Your application redirects the user to HMRC’s login page, they authorise access, and you receive an access token. Standard OAuth flow — if you’ve integrated with GitHub or Google, the mechanics are identical.

The 9-Box VAT Return

Every UK VAT return consists of exactly 9 boxes. This is the data structure your software needs to calculate and submit:

Note the unit difference: Boxes 1–5 are in pence (minor units), while Boxes 6–9 are in whole pounds rounded down. This catches out a lot of implementations.

The Submission Payload

Here’s what an actual VAT return submission looks like:

POST /organisations/vat/123456789/returns

{
  "periodKey": "26A1",
  "vatDueSales": 1250000,
  "vatDueAcquisitions": 0,
  "totalVatDue": 1250000,
  "vatReclaimedCurrPeriod": 230000,
  "netVatDue": 1020000,
  "totalValueSalesExVAT": 62500,
  "totalValuePurchasesExVAT": 11500,
  "totalValueGoodsSuppliedExVAT": 0,
  "totalAcquisitionsExVAT": 0,
  "finalised": true
}

The periodKey identifies which quarter you’re filing for. You get this from the obligations endpoint. The finalised: true flag is HMRC’s equivalent of a confirmation — it tells them this is a real submission, not a draft.

Fraud Prevention Headers

Here’s the part that surprises most developers. HMRC requires a set of “fraud prevention” headers on every API call:

Gov-Client-Connection-Method: WEB_APP_VIA_SERVER
Gov-Client-Browser-JS-User-Agent: Mozilla/5.0...
Gov-Client-Browser-Do-Not-Track: true
Gov-Client-Device-ID: <device-uuid>
Gov-Client-Timezone: UTC+00:00
Gov-Client-Window-Size: width=1920&height=1080
Gov-Vendor-Version: SpeyBooks=3.4
Gov-Vendor-Product-Name: SpeyBooks

There are about 15 of these headers, and HMRC validates them. If they’re missing or malformed, the API returns a 403. The exact requirements depend on your connection method — web app, desktop app, mobile, or batch process.

HMRC provides a test endpoint to validate your headers before you submit real returns. Use it. The error messages are reasonably helpful, which is not something you can say about all government APIs.

The Sandbox

HMRC provides a full sandbox environment with test credentials. You can create test users, generate obligations, submit returns, and check liabilities — all without touching real tax records.

Sandbox: https://test-api.service.hmrc.gov.uk
Production: https://api.service.hmrc.gov.uk

The sandbox generates test VRNs and populates them with obligations. It’s the closest you’ll get to a realistic testing environment for tax software.

To get sandbox access, register an application on the HMRC Developer Hub. Production access requires an additional review process — HMRC checks your fraud prevention headers and tests your software against their validation rules before issuing production credentials.

Obligations and Deadlines

Before you can submit a return, you need to know which periods are due:

GET /organisations/vat/123456789/obligations?status=O

{
  "obligations": [
    {
      "periodKey": "26A1",
      "start": "2026-01-01",
      "end": "2026-03-31",
      "due": "2026-05-07",
      "status": "O",
      "received": null
    }
  ]
}

Status O means open (not yet filed). Status F means fulfilled. The due date is when HMRC expects the return — typically one month and seven days after the period end.

What Your Software Needs to Do

To be MTD-compliant, your software needs to:

Keep digital records: transactions must be stored digitally, not on paper. This is the record-keeping requirement — your database is your digital record.

Calculate the 9 boxes: derive the VAT return figures from the digital records. No manual entry of the 9 box values — they must be calculated from the underlying transactions.

Submit via API: send the return to HMRC using their VAT API. This is the submission requirement.

Preserve the digital link: there must be an unbroken digital chain from the source transactions to the submitted return. No manual transcription or re-keying of figures.

For a double-entry accounting system like SpeyBooks, these requirements map naturally onto existing functionality. The ledger is the digital record. The report engine calculates the 9 boxes. The API submission is one more endpoint. The double-entry audit trail is the digital link.

For more on how SpeyBooks handles VAT calculations, see VAT Schemes Explained (With Code).

ITSA: What’s Coming Next

MTD for Income Tax Self Assessment (ITSA) launches in April 2026 for self-employed individuals and landlords with income above £50,000. It expands to £30,000+ in April 2027.

ITSA requires quarterly updates to HMRC — not full returns, but summaries of income and expenses. The API structure is similar to VAT MTD but with different endpoints and data requirements.

If you’re building accounting software for UK sole traders, ITSA compliance is about to become as important as VAT MTD. The HMRC ITSA API documentation is already available for sandbox testing.