Building HMRC MTD for Income Tax Software: A UK API Architecture

The Appycodes MTD build that deliberately stops before filing

In September 2026, Appycodes designed and shipped a public Making Tax Digital for Income Tax checker for UK sole traders and landlords. The repository contains the original product brief, the 302-line rules engine, the user interface and the release commit. A user enters gross self-employment and property income for the relevant tax years; the tool applies the phased thresholds, chooses the earliest qualifying band, builds the standard quarterly dates and exports an .ics calendar.

The difficult decision was the product boundary. A live HMRC connection would have made the page look more authoritative, but it would also have changed a low-risk planning tool into an authenticated tax-software product. The team kept the calculation in the browser, stored no income figures, used published rules and stated that the checker does not access HMRC or confirm whether an obligation has been met. That reduced capability is intentional: it avoids pretending that a threshold calculation is a filing status.

There is also a real limitation. The checker can explain a likely start date from the figures supplied, but it cannot discover the customer's HMRC business sources, agent relationship, exemption, enrolment state or live obligations. It cannot submit or retrieve a tax calculation. Those gaps are why the next step is not “add an API key”; it is a different architecture and approval programme.

You can inspect the live MTD for Income Tax checker. Its narrow scope is a useful design pattern for UK firms: separate the customer-help feature you can safely deliver now from the regulated or approval-dependent transaction you may need to source elsewhere.

Choose direct filing, an approved integration or a workflow layer

HMRC's current Business Details and Individual Calculations API pages both warn that the market window for new 2026–27 quarterly-update products has closed. The APIs remain visible in sandbox and existing production products may use supported versions, but a new supplier must confirm what later production route is open before making a sales promise. HMRC: Business Details (MTD) API · HMRC: Individual Calculations (MTD) API

HMRC's integration guide sets minimum functionality across the customer journey and identifies the API families needed for in-year and end-of-year products. For in-year updates, that includes Business Details, Obligations and Self-Employment Business and/or Property Business; Individual Calculations is also needed if the software displays calculations rather than signposting the customer to HMRC. End-of-year software needs a broader set for adjustments, losses and the final declaration. HMRC: how to integrate with MTD for Income Tax APIs

That list changes the build-versus-buy calculation. A practice may only want “send quarterly totals”, but the production product must support the surrounding journey it advertises. A narrow partner integration can be more honest and cheaper than owning a tax engine, approval evidence and multi-year API lifecycle.

The Appycodes MTD Delivery Gate

Score five gates from 0 to 3: 0 unknown, 1 assumed, 2 documented but unproved, 3 tested with retained evidence. The maximum is 15. Market Access and Authority are hard gates: either at zero means no live filing commitment, regardless of the total.

The gate is an architecture and product-readiness model, not tax or regulatory advice and not a statistical risk score. Apply it to the precise product variant. A workflow portal might score three for Coverage without direct filing because its documented end state is an export to approved software; a product claiming live submission cannot.

A production architecture needs a control loop, not one API call

HMRC user-restricted endpoints use OAuth 2.0 authorisation code grants. Individuals and organisations access their own data; agents act for clients according to the relationship and endpoint rules. Access tokens last four hours, and refresh authority eventually expires, so a durable product needs a recoverable reauthorisation journey rather than a hidden token-refresh loop. HMRC: user-restricted endpoint authorisation

HMRC says fraud-prevention headers are legally required for its MTD Income Tax APIs and that continued incorrect or missing data can lead to sanctions or blocked API access. Its validator checks individual requests and later sandbox feedback, but HMRC warns that a validator pass is not a guarantee of production compliance. HMRC: send fraud-prevention data · HMRC: Test Fraud Prevention Headers API

Design headers at the start. A browser product, installed desktop tool, server-to-server bridge and remote desktop deployment expose different signals. If the chosen stack cannot lawfully and reliably collect the required values for its connection method, that is an architecture blocker—not a task to leave until production approval.

Make the write idempotent locally, then reconcile

The TypeScript service below sits above an HMRC adapter. The adapter owns the current endpoint path, media type, OAuth token and fraud headers; the domain service owns the business source, obligation and attempt ledger. This keeps a version change from leaking across the whole product and prevents a double click from becoming a second uncontrolled write.

type SubmissionState =
  | "prepared"
  | "sending"
  | "accepted_pending_obligation"
  | "fulfilled"
  | "needs_review";

type SubmitQuarterInput = {
  tenantId: string;
  authorityId: string;
  businessId: string;
  obligationId: string;
  periodEnd: string;
  totals: Record<string, number>;
};

export async function submitQuarter(input: SubmitQuarterInput) {
  const payloadHash = stableHash(input.totals);
  const attempt = await db.mtdSubmission.upsert({
    where: {
      obligationId_payloadHash: {
        obligationId: input.obligationId,
        payloadHash,
      },
    },
    create: {
      ...input,
      payloadHash,
      state: "prepared",
    },
    update: {},
  });

  if (["accepted_pending_obligation", "fulfilled"].includes(attempt.state)) {
    return attempt; // a browser retry cannot create a second local write
  }

  const authority = await authorityVault.getUsableGrant(input.authorityId);
  const obligation = await hmrc.getObligation({
    authority,
    businessId: input.businessId,
    obligationId: input.obligationId,
  });
  if (obligation.status !== "open" || obligation.periodEnd !== input.periodEnd) {
    return db.mtdSubmission.update({
      where: { id: attempt.id },
      data: { state: "needs_review", errorCode: "obligation_mismatch" },
    });
  }

  await db.mtdSubmission.update({
    where: { id: attempt.id },
    data: { state: "sending", sentAt: new Date() },
  });

  const response = await hmrc.submitQuarterlyUpdate({
    authority,
    businessId: input.businessId,
    periodEnd: input.periodEnd,
    totals: input.totals,
    // The adapter adds the API version and the fraud-prevention headers for
    // this product's documented connection method.
  });

  await db.mtdSubmission.update({
    where: { id: attempt.id },
    data: {
      state: "accepted_pending_obligation",
      hmrcCorrelationId: response.correlationId,
      acceptedAt: new Date(),
    },
  });

  await jobs.enqueue("reconcile-mtd-obligation", {
    submissionId: attempt.id,
    notBefore: addMinutes(new Date(), 10),
  });

  return { ...attempt, state: "accepted_pending_obligation" as const };
}

The unique key is local because this guide does not assume that every HMRC endpoint offers a provider idempotency key. For a timeout after the request leaves your server, do not blindly repeat the write. Preserve the attempt as uncertain, retrieve the latest obligation or supported summary state, and let an operator or endpoint-specific retry rule decide whether resubmission is safe.

HMRC says a submitted quarterly update or annual return can take up to an hour to appear as a fulfilled obligation. Its guidance also says software should continue to show the latest obligations and notes that changing from standard to calendar quarters requires a refresh before submitting against the new periods. Model accepted_pending_obligation as a normal state, poll with sensible backoff, and show the customer a receipt plus the fact that confirmation is pending. HMRC: updates, obligations and processing latency

1. Prepare. Freeze the business source, obligation, period and totals under a payload hash; require a fresh customer or agent confirmation for material changes.
2. Authorise. Resolve the correct grant and scopes. Refresh server-side; if authority has expired or been revoked, stop with a customer-safe reauthorisation path.
3. Submit. Send the documented API version and connection-method headers. Store the HTTP result and correlation identifier without logging tokens or unnecessary personal data.
4. Reconcile. Refresh the obligation after the documented delay. Close only when HMRC state and the local attempt agree; otherwise create an owned exception.
5. Support. Give staff the attempt ID, business source, period, safe error class and next action—not a screen of raw API data.

Seven failure modes to rehearse before a tax deadline

1. The sandbox works, but the product has no production route

This is the most expensive failure because it can appear after a polished prototype. Record written confirmation of the applicable production process, target cohort, API versions and approval evidence before a fixed launch commitment. The 2026–27 market-window warning makes this a current risk, not a theoretical one.

2. One OAuth grant is treated as office-wide authority

Keep grants per subject and agent context. Re-check access when staff move teams or a client ends the engagement. HMRC's integration guide distinguishes main and supporting agents; supporting agents can use only specified endpoints. A 403 may be an authority-model error, not a transient outage.

3. Fraud headers are assembled from server defaults

A cloud server's IP address and user agent do not automatically describe the originating user environment. Select the documented connection method, capture the required values at the correct boundary, encode them correctly and test across representative devices and network paths.

4. A 2xx response marks the quarter complete

Keep acceptance and fulfilment separate. Poll the relevant obligation, allow the documented processing delay and escalate a stale pending state. This prevents a customer dashboard from declaring success while HMRC still shows an open obligation.

5. Quarterly dates are generated instead of retrieved

A calendar is useful for planning, as Appycodes' checker demonstrates. Filing software must work from HMRC business-source and obligation state, including calendar-quarter elections, new businesses and changes. Local dates should support reminders, never replace live obligation identity.

6. API errors are shown directly to the customer

Map provider errors into stable product classes such as reauthorise, amend records, wait for HMRC, contact support or manual review. Retain the original code and correlation ID for operators. Do not expose tokens, National Insurance numbers or raw payloads in analytics, support chat or browser logs.

7. API versions change without an owned upgrade path

Pin the media type in one adapter, monitor deprecation and sunset headers, run contract tests against the sandbox and inventory which customer journeys use each version. A tax deadline is the wrong time to discover that one endpoint moved and another changed validation.

Recommendations for UK firms

After building the public MTD planner and reviewing the current HMRC production constraints, Appycodes recommends a two-week discovery before a direct-filing estimate: confirm production eligibility with HMRC, choose the supported customer and agent journeys, prototype OAuth and fraud headers on representative devices, submit sandbox scenarios, and rehearse one accepted-but-not-yet-fulfilled obligation. If any hard gate remains unknown, price an approved-product integration instead.

Our API and integration service covers product-boundary discovery, HMRC or partner adapters, secure authority storage, reconciliation, observability and operational handover. The Professional Energy case study shows the wider Appycodes approach to replacing disconnected business workflows with a central, supportable operational system; it is related delivery evidence, not a claim that the project used HMRC's MTD APIs.

Primary sources

• GOV.UK: who must use MTD for Income Tax and when
• HMRC: MTD for Income Tax integration and approval guide
• HMRC: OAuth for user-restricted endpoints
• HMRC: fraud-prevention data requirements
• HMRC: Test Fraud Prevention Headers API
• HMRC: Business Details (MTD) API
• HMRC: Individual Calculations (MTD) API
• HMRC: quarterly updates, obligations and latency

Technical and operational guidance, not tax, legal, accounting, regulatory or financial advice. HMRC API access, versions and product windows can change; confirm the current position with HMRC and qualified advisers before committing a filing product.