HMRC
HMRC Making Tax Digital
HMRC's Making Tax Digital programme underpins a new way of filing tax — through software that connects directly to HMRC's APIs. This guide explains how the HMRC MTD system works, from Government Gateway to quarterly submission.
What is HMRC's role in MTD?
HMRC built and operates the MTD API infrastructure. It is the central authority that:
- Maintains the MTD APIs that approved software connects to
- Authorises software products through its developer programme
- Manages taxpayer identities via the Government Gateway
- Validates and stores every quarterly update and Final Declaration
- Issues confirmation references on successful submissions
How does HMRC authorisation work?
HMRC uses OAuth 2.0 — an industry-standard secure authorisation protocol — to allow software to access your tax data on your behalf. Here's how the flow works:
Sign up for MTD with HMRC
You enrol for MTD ITSA on HMRC's website using your Government Gateway credentials. This is a separate, one-time step before connecting any software.
Connect your software to HMRC
In your MTD software, click 'Connect to HMRC'. You're redirected to HMRC's Government Gateway login page — the software never sees your password.
Authorise access
You log in with your Government Gateway User ID and password directly on HMRC's website. HMRC then asks you to approve the software's access to your tax account.
Secure token issued
HMRC issues the software a secure access token. This allows it to submit on your behalf without ever needing your Government Gateway credentials again.
Token renewal
Tokens expire after 18 months. When your token expires, you'll need to re-authorise via Government Gateway. Good software shows a 'Reconnect' prompt before this happens.
Important: MTD sign-up and software authorisation are two separate steps
Many users confuse HMRC MTD sign-up (done on gov.uk) with connecting their software (done in-app). You must complete the HMRC sign-up first — and HMRC can take up to 72 hours to activate your MTD account before software can connect.
HMRC's MTD APIs
HMRC operates a suite of APIs specifically for MTD ITSA. These are the main ones your software interacts with:
| API | Purpose |
|---|---|
| Obligations (MTD) | Retrieve your open quarterly deadlines and Final Declaration obligations |
| Business Source Self Employment | Submit and amend quarterly income/expense updates for sole traders |
| Business Source UK Property | Submit and amend quarterly updates for UK rental income |
| Business Source Foreign Property | Submit and amend quarterly updates for overseas rental income |
| Individual Calculations | Trigger an estimated tax calculation and submit Final Declaration |
| Business Source Adjustable Summary | Submit year-end adjustments before Final Declaration |
| Business Details | Retrieve business IDs and income source types registered with HMRC |
Fraud prevention headers — a legal requirement
Every API call to HMRC must include a set of fraud prevention headers. These are technical identifiers that help HMRC detect fraudulent or automated submission attempts. They are not optional — HMRC will reject API calls without them, and non-compliance can trigger an HMRC audit.
The headers capture device and browser metadata (screen size, timezone, browser plugins, IP details) and are collected automatically by your MTD software. You do not need to do anything manually — this is the software's responsibility, not yours.
HMRC's fraud prevention header specification is publicly available on the HMRC Developer Hub.
HMRC environments: sandbox and production
HMRC operates two environments for MTD:
Sandbox
Used by software developers for testing. Simulates HMRC responses with test scenarios. No real data submitted. URL: test-api.service.hmrc.gov.uk
Production
Live HMRC system. Real submissions, real obligations, real tax records. URL: api.service.hmrc.gov.uk
Common HMRC MTD errors explained
Client not authorised
Cause: Wrong Government Gateway ID or expired token (18-month TTL)
Fix: Re-authorise via Government Gateway in your software settings
HMRC sign-up not yet active
Cause: HMRC processing delay after MTD enrolment
Fix: Wait up to 72 hours after signing up on gov.uk before connecting software
NINO not associated with Gateway ID
Cause: Multiple Government Gateway accounts
Fix: Contact HMRC to confirm which Gateway ID is linked to your National Insurance number
No obligations showing
Cause: Wrong active tax year selected
Fix: Check the tax year selector in your software — default to current tax year
C55326 error on calculation
Cause: Missing Periods of Account for a self-employment source
Fix: Submit Periods of Account per income source before triggering the calculation
ArcTax connects directly to HMRC
Full OAuth 2.0 flow, mandatory fraud prevention headers included, and obligation tracking pulled live from HMRC — everything handled for you.
Get started free