GovTech HMRC Making Tax Digital for Income Tax — HMRC Registered API Developer

HMRC MTD ITSA API Integration

MTD ITSA (Making Tax Digital for Income Tax Self Assessment): quarterly updates (income and expenses) submitted to HMRC via MTD ITSA API.

HMRC API Platform

registration as a software developer (HMRC developer hub — developer account, production credentials, MTD ITSA application).

MTD ITSA API flows

• 1create obligation (HMRC creates quarterly obligation for each taxpayer),
• 2submit periodic update (quarterly income and expenses),
• 3crystallise (annual end-of-year declaration),
• 4retrieve obligations (check submission status). OAuth 2.0: taxpayer authorises software to submit on their behalf (Government Gateway OIDC).

MTD bridging software

for clients who maintain records in spreadsheets (Excel, Google Sheets), bridging software reads digital records and submits to HMRC API.

Architecture

Excel Add-in (COM Add-in or VSTO) reads spreadsheet data → validates MTD ITSA schema → submits to HMRC API.

CSV import

CSV upload from any accounting software → validation → MTD submission.

JSON API

for accounting software integrations (Xero, QuickBooks, Sage — each has their own API format that must be mapped to HMRC MTD ITSA schema).

HMRC MTD ITSA schema validation

• all submissions validated against HMRC JSON schema before submission to reduce rejection rate.
• Government Gateway OAuth 2.0 and

Government Gateway

• HMRC's identity and authorisation platform.
• MTD ITSA OAuth 2.0: (1) client clicks "Connect to HMRC", (2) redirect to Government Gateway login (taxpayer's UTR and Government Gateway password), (3) taxpayer authorises software to submit on their behalf, (4) OAuth access token returned, (5) software stores refresh token (for annual re-authorisation).

Token management

• refresh tokens expire after 18 months (taxpayer must re-authorise annually).
• Multi-agent: accountancy practices can be authorised to submit on behalf of multiple clients (HMRC MTD agent authorisation model).

HMRC API sandbox

complete MTD ITSA journey testable in sandbox before production.

Test UTR numbers

HMRC provides test UTR numbers for sandbox (specific UTRs trigger specific responses — success, errors, penalty scenarios).

HMRC MTD ITSA test scenarios

• 1successful quarterly update submission,
• 2quarterly update with validation error (missing mandatory field),
• 3crystallisation with tax liability calculation,
• 4agent authorisation flow,
• 5pension relief and gift aid scenarios.

ClickMasters

all 15 HMRC-defined MTD ITSA test scenarios pass before production deployment.