A playbook for the UK's tax API: Two non-obvious integration patterns

The founder of TapTax details two critical requirements for integrating with the UK's HMRC API, from versioning in headers to mandatory device fingerprinting. A technical playbook for indie developers.

Integrating a government API is not like integrating Stripe. The founder of TapTax, a Making Tax Digital (MTD) application for UK sole traders, documented the process of building on top of the UK tax authority's (HMRC) platform. The experience revealed several non-obvious requirements that cost significant development time.

This playbook extracts two of the most critical fixes from the company's integration work. These are not edge cases. They are mandatory, undocumented behaviors in a high-stakes API environment where failure means incorrect tax filings. The solutions demonstrate the level of defensive coding required to operate in gov-tech.

Isolate API versions per-request

Most modern APIs version in the URL path, like /v2/endpoint. HMRC's API versions through the Accept header, a content negotiation strategy. A request must include a header like application/vnd.hmrc.5.0+json. Sending the wrong version for a given endpoint returns a 406 Not Acceptable error, without guidance.

The core challenge is that different endpoints are on different versions simultaneously. The founder reports that at the time of building, obligations were on v3.0 while calculations were on v8.0. There is no single "current" version to set globally. The fix was to make the API version a required argument on every internal request wrapper, preventing developers from forgetting to set it for each specific call. A final complication: withdrawn versions sometimes return a 404 Not Found instead of a 406. When an HMRC call 404s, check the version before you go hunting for a bad path.

Send mandatory device fingerprints

HMRC requires a set of "fraud prevention headers" on every single API call. These are not optional. The headers, prefixed with Gov-Client-* and Gov-Vendor-*, constitute a fingerprint of the end-user's device and connection. They include details on the device, network, screen resolution, and timezone.

This telemetry is mandatory, and the required set of headers changes based on the connection method. A server-mediated web app must send a different set of headers than a server-mediated mobile app. Sending the wrong set, or extra headers, results in an error. The TapTax team's solution was to branch their code, creating different header-generation logic based on the client type to ensure compliance on every request.

WHAT WE'D CHANGE

This playbook is a precise, tactical guide for a single API. Its immediate utility is for developers building on HMRC's platform. The broader lesson, however, is in what this implies about building in regulated or government-adjacent spaces. The developer experience for these APIs often lags far behind the private sector standard set by companies like Stripe or Twilio.

A founder applying this playbook in 2026 should budget for an 'API discovery' phase that private-sector integrations do not require. Assume documentation is incomplete or misleading. Assume error messages are unhelpful. The time spent reverse-engineering undocumented behaviors, as the TapTax founder did, is a real and necessary cost.

This friction is also the moat. The technical difficulty of integrating with platforms like HMRC's creates a significant barrier to entry. Competitors cannot easily replicate the product without investing the same engineering resources to solve the same esoteric problems. The complexity is a feature of the business model, not a bug.

LANDING

Building a business on top of a government API is less about product velocity and more about technical resilience. The value is not created by shipping features quickly. It is created by correctly navigating a complex, unforgiving, and mandatory technical landscape where the cost of an error is high. For founders in gov-tech or fintech, the ability to deconstruct and reliably operate on these platforms is the core competency. The difficulty is the opportunity.

The investor read

The global push for government digitization (e.g., the UK's Making Tax Digital, EU e-invoicing) is creating a class of SaaS businesses built on government APIs. These are not typical venture-scale opportunities. Customer acquisition is often driven by legal mandate, and the primary moat is not brand or network effects, but deep, specific technical and regulatory expertise. An investment in a company like TapTax is a bet on a team's ability to execute on complex integrations and maintain compliance. These businesses often trade explosive growth for durable, protected revenue streams in a well-defined, non-discretionary market.

Pull quote: “When an HMRC call 404s, check the version before you go hunting for a bad path.”