Can an AI System Process and File a Self Assessment Tax Return to HMRC Automatically?

This is the long-form deep-dive. For a quicker companion, see the blog post. Not tax advice. Always have a UK accountant review before a live HMRC submission.

1. Introduction: can AI file Self Assessment automatically?

The honest answer is mostly yes for preparation, no for unattended submission. An AI system can ingest a PDF bank statement, extract hundreds of transactions, classify them into HMRC Self Assessment expense categories, reconcile balances, compute income tax and National Insurance for a tax year such as 2025-26, and call the HMRC Making Tax Digital (MTD) API to file — but only after a human (or accountant) has reviewed the classifications, the reconciliation, and the calculated return, and only after the taxpayer has completed HMRC OAuth with their Government Gateway credentials.

This article documents FileMyTax, a demonstration pipeline developed by Workstation for CognoAI, which owns the underlying system intellectual property and granted permission to publish how it works. FileMyTax is the publication name used here; it is not the same product name as other CognoAI offerings. Workstation built and documented the implementation; CognoAI owns the IP.

We will walk through the six-API pipeline, the architecture, where AI helps financial analysis, where deterministic code must take over, HMRC OAuth and MTD filing, limitations learned from landlord bank-statement testing, and why fully unattended filing is not recommended.

2. Who built this and why

CognoAI commissioned the underlying platform to reduce the pain of UK Self Assessment for landlords, sole traders, and finance teams drowning in PDF bank statements and spreadsheet glue. The goal is not to replace accountants — it is to automate the tedious 90% (extraction, categorisation, reconciliation, draft calculation) so professional review focuses on judgement calls, not data entry.

Workstation engineered the stack: Dockerised nginx routing, a Next.js frontend, FastAPI for AI-heavy operations, opsapi (Lua Lapis) for authentication and tax CRUD, PostgreSQL, MinIO object storage, and Gatus health monitoring. This article explains that architecture under the FileMyTax demo name with CognoAI attribution throughout.

3. The problem: PDFs, spreadsheets, and MTD

Landlords and sole traders often receive annual packs of bank PDFs — multiple accounts, mixed personal and business lines, mortgage interest, repairs, agent fees, and transfers that are hard to classify at scale. In development we stress-tested the pipeline against fictional HSBC-style landlord statement fixtures (synthetic data only, not real customer records) with turnover scenarios around £500k and £700k to validate extraction under load. Real-world packs are messy: scanned pages, table layouts where the balance column is mistaken for paid-in amounts, and descriptions like "RENT REC" next to "TRANSFER" that need context.

Spreadsheets work until they do not: formula drift, no audit trail, no direct MTD submission, and no consistent mapping to HMRC expense categories (costOfGoods, premisesRunningCosts, professionalFees, and the rest). Packaged SaaS can help, but teams with bespoke data residency needs or awkward statement formats still benefit from a pipeline they control.

4. FileMyTax overview

In plain English, FileMyTax does the following:

1. You upload a PDF bank statement.
2. AI and pdfplumber extract structured transactions.
3. An LLM classifies each line into Self Assessment categories with confidence scores.
4. The system reconciles debits, credits, and running balances.
5. A deterministic tax engine calculates the return for a chosen tax year.
6. After human approval and HMRC OAuth, the platform can file via MTD.

Everything runs behind a single nginx entry point on localhost (or LAN IP for mobile testing). JWT authentication is shared between FastAPI and opsapi. Sensitive fields such as National Insurance numbers are encrypted at rest.

5. The six-step API pipeline

The complete demo pipeline is six authenticated API calls (examples use nginx at http://localhost; adjust port if NGINX_HOST_PORT is set). Obtain a JWT via POST /opsapi/auth/login first.

Each step updates ProcessingStatus and ValidationStatus rows so the UI and Gatus-adjacent ops tooling can see whether a statement is stuck in extraction versus ready for calculate. That state machine is easy to overlook when reading curl examples in isolation, but it is what makes parallel uploads safe: statement IDs are independent, and calculate always keys off a single statement_id plus explicit tax_year query parameter (for example 2025-26).

Swagger for FastAPI lives at http://localhost/fastapi/docs; opsapi exposes http://localhost/opsapi/swagger. When nginx port 80 is taken (common with Rancher Desktop or Apache), set NGINX_HOST_PORT=8080 in .env and rerun ./start.sh — all examples then use localhost:8080 instead.

5.1 Upload PDF statement

curl -F "file=@bank_statement.pdf" \
  -H "Authorization: Bearer $TOKEN" \
  http://localhost/fastapi/api/upload

5.2 Extract transactions

curl -X POST http://localhost/fastapi/api/extract \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"statement_id": 1}'

Native PDFs use pdfplumber; scanned PDFs fall back to Claude Vision OCR. The classifier provider is selected by LLM_PROVIDER (OpenAI or Anthropic) at startup — there is no automatic cross-provider fallback on failure; failed classifications return uncategorised with confidence: 0.0.

5.3 Classify transactions

curl -X POST http://localhost/fastapi/api/classify \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"statement_id": 1}'

5.4 Reconcile statement

curl -X POST http://localhost/fastapi/api/reconcile \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"statement_id": 1}'

5.5 Calculate tax return

curl -H "Authorization: Bearer $TOKEN" \
  http://localhost/fastapi/api/calculate/1?tax_year=2025-26

The tax calculator applies 2025/26 rules: personal allowance £12,570 with taper above £100k, income tax bands at 20%, 40%, 45%, and Class 4 NI at 8% and 2%. This step is deterministic Python — no LLM in the arithmetic.

5.6 File to HMRC

curl -X POST http://localhost/fastapi/api/file \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "statement_id": 1,
    "nino": "AB123456C",
    "access_token": "your_hmrc_token",
    "tax_year": "2025-26"
  }'

Do not call this endpoint unattended. Treat it as the final gate after review and accountant sign-off.

6. Architecture

Traffic flows through nginx: / to Next.js, /fastapi/* to FastAPI, /opsapi/* to opsapi. PostgreSQL holds statements, transactions, tax returns, and processing status. MinIO stores uploaded PDFs. Gatus on port 8085 polls health endpoints every 10-30 seconds. Direct debug ports exist (FastAPI 8847, frontend 3847) but production-style testing uses nginx paths only.

7. Workflow diagram

The swim lanes separate concerns: client review, ingest, AI extraction and classification, deterministic tax engine, HMRC OAuth and filing, and audit (JWT, encrypted NINO, logs). The decision matrix compares FileMyTax AI-assisted flow against manual spreadsheets and accountant-only preparation on time, accuracy, audit trail, cost, HMRC compliance, and human oversight.

8. AI for financial analysis — benefits

8b. Stack and services (technical detail)

Behind FileMyTax sits a Docker Compose stack orchestrated by ./start.sh, which can run in local, LAN, test, staging, or production modes. The backend uses FastAPI with SQLModel on PostgreSQL; uploaded PDFs land in MinIO with zero local disk storage in the API containers. The frontend is Next.js with NEXT_PUBLIC_* variables baked at build time from the root .env.

Authentication is split deliberately. opsapi (Lua Lapis) issues JWT access tokens and opaque refresh tokens (HttpOnly secure cookies for web, JSON body for mobile). FastAPI verifies the same JWT_SECRET_KEY. Services include StorageService, PDFProcessorService, LLMService, ClassificationService, ReconciliationService, TaxCalculatorService, and HMRCClient — each with a narrow boundary so AI failures do not corrupt tax arithmetic.

Supported bank parsers target common UK layouts (HSBC, Barclays, Lloyds, Santander, and similar table PDFs). The parser detects date, description, debit/credit or amount, and balance columns flexibly — which is powerful until the wrong column is chosen; see limitations below.

9. HMRC Making Tax Digital

MTD Self Assessment requires user-authorised OAuth — a NINO alone is not enough. The typical flow:

1. Save NINO — POST /opsapi/api/v2/tax/profile/nino (encrypted at rest, masked in responses).
2. Connect HMRC — GET /opsapi/auth/hmrc/initiate returns auth_url; user signs in via Government Gateway; callback exchanges code for tokens stored server-side.
3. Fetch businesses — POST /fastapi/api/hmrc/businesses/fetch caches trading names and IDs.
4. Fetch obligations — POST /fastapi/api/hmrc/obligations/fetch for quarterly periods and due dates.
5. File — POST /fastapi/api/file after review.

Set HMRC_ENVIRONMENT=sandbox for development; switch to production without code changes when ready. The backend sends mandatory fraud prevention headers; clients should provide stable X-Device-ID and accurate User-Agent values. Sandbox test users can be created via POST /fastapi/api/hmrc/sandbox/create-test-user when sandbox mode is enabled.

HMRC access tokens expire after roughly four hours; the backend manages refresh — mobile and web clients use opsapi-stored tokens rather than embedding secrets in the browser beyond the OAuth redirect.

9.1 Save NINO and check profile

curl -X POST http://localhost/opsapi/api/v2/tax/profile/nino \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "nino": "QQ123456C" }'

curl -H "Authorization: Bearer $TOKEN" \
  http://localhost/opsapi/api/v2/tax/profile

Responses mask the NINO (****456C) while confirming hmrc_connected and token expiry after OAuth.

9.2 OAuth initiate

curl -H "Authorization: Bearer $TOKEN" \
  "http://localhost/opsapi/auth/hmrc/initiate?source=settings"

Open auth_url in a system browser or ASWebAuthenticationSession — not a credential-stuffed WebView. Mobile apps should register a deep link or universal link as HMRC_REDIRECT_URI.

9.3 Businesses and obligations

curl -X POST http://localhost/fastapi/api/hmrc/businesses/fetch \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{}'

curl -X POST http://localhost/fastapi/api/hmrc/obligations/fetch \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "business_id": "XAIS12345678910" }'

Cached reads afterwards avoid hitting HMRC on every page load: GET /fastapi/api/hmrc/businesses and GET /fastapi/api/hmrc/obligations?tax_year=2024-25.

9.4 Disconnect and status

curl -X DELETE http://localhost/opsapi/auth/hmrc/disconnect \
  -H "Authorization: Bearer $TOKEN"

curl -H "Authorization: Bearer $TOKEN" \
  http://localhost/fastapi/api/hmrc/status

8c. AI for financial analysis — deeper view

Beyond the summary table, three patterns matter for FinOps teams evaluating build-vs-buy.

First, throughput. A sole trader with twelve months of transactions across two rental accounts might spend a day in Excel pivot tables; the FileMyTax pipeline completes extract + classify + reconcile in the time it takes to make coffee, leaving the human hour for judgement. That shift moves accountant economics from data entry to advisory — the billable value accountants prefer anyway.

Second, explainability. Each classification carries a confidence score and can be overridden with a reason stored alongside the transaction. That is weaker than a full chain-of-thought audit log, but stronger than a black-box SaaS export where you cannot see why row 417 was "repairs".

Third, cost curve. Running locally, marginal cost per return is API tokens for classification plus electricity — not per-seat SaaS fees scaling with entity count. For portfolio landlords or finance ops teams with many statements, that curve matters. The upfront engineering cost is real; CognoAI absorbed that via Workstation delivery rather than pushing spreadsheet labour onto each user every year.

Privacy-sensitive organisations also care that PDFs and Postgres rows stay inside their Docker network until HMRC filing — there is no multi-tenant cloud ingestion step in the demo architecture. Production hardening still requires backups, access control, and DPIA documentation; the article does not pretend GDPR compliance is automatic because the stack is local.

10. Demo video

End-to-end FileMyTax demonstration: bank PDF through classification and calculation to HMRC MTD sandbox filing, with review gates shown in the UI.

11. Human in the loop

AI can misread a scanned column, confuse a transfer with income, or assign the wrong expense category when the description is vague. The UI is designed for review: accept, override, or split transactions with reasons captured. The tax calculation is deterministic and testable; the LLM never computes tax due.

Accountant sign-off before any live HMRC submission is mandatory. This article is not tax advice. FileMyTax demonstrates engineering capability for CognoAI; your circumstances may differ on allowances, property income splits, partnerships, and other SA schedules.

11b. Monitoring with Gatus

The included Gatus dashboard (http://localhost:8085 by default) polls the frontend via nginx, FastAPI /fastapi/health, opsapi /opsapi/health?detailed=true, Swagger reachability, and direct container ports for bypass diagnostics. Interval is 10-30 seconds per check. Adding a service means editing monitoring/gatus/config.yaml and restarting the Gatus container — a small but important ops habit before you trust the pipeline for real financial data.

Health checks are not a substitute for end-to-end tests: the repo also supports Playwright E2E against a running stack and pytest on the backend. A green Gatus board plus a failed reconcile is still a failed day.

12. Limitations

• PDF extraction: pdfplumber assumes table layouts; HSBC-style statements taught us to validate balance vs paid-in columns explicitly — wrong column mapping silently corrupts reconciliation.
• OCR: Scanned statements depend on Claude Vision; poor scans need human correction.
• LLM guardrails: Low-confidence classifications must not auto-file; default uncategorised on provider failure rather than guessing.
• Deterministic separation: Tax bands and NI rates live in tax_calculator.py with DECIMAL precision — never prompt-engineered.
• Compliance scope: GDPR, Data Protection Act 2018, and HMRC rules apply; production needs backups, secrets management, and monitoring beyond a dev Docker compose.
• JWT alignment: FastAPI and opsapi must share JWT_SECRET_KEY; mismatch surfaces as opaque 401 signature errors — check both containers if auth suddenly breaks after redeploy.
• Provider lock-in at startup: LLM_PROVIDER is openai or anthropic without cross-failover; plan maintenance windows if a provider has an outage.

When testing landlord scenarios, treat reconciliation deltas as first-class signals, not nuisances. A £12k mismatch often means column mis-mapping, not a naughty tenant. Fixing extraction rules and re-running the idempotent pipeline is cheaper than overriding hundreds of rows by hand.

12b. How this compares to packaged tax software

FreeAgent, Xero Tax, and similar tools are the right default for most users: certified MTD connectors, support desks, and accountants already trained. FileMyTax-style platforms make sense when you need custom categorisation rules, on-prem or VPC deployment, integration with an existing opsapi identity plane, or publication of a vertical workflow (as CognoAI does for AI-assisted accounting). The decision matrix in the workflow SVG is intentionally honest: spreadsheets are slow and error-prone; accountant-only is safe but expensive on recurring prep; AI-assisted local pipelines win on auditability and marginal cost only if you invest in engineering and still pay for professional sign-off.

13. What is next for FileMyTax / CognoAI

Roadmap items visible in the platform docs include deeper MTD ITSA preview-calculation round-trips, expanded RAG-style training data from accountant corrections, multi-tenant auth cookie domains for SaaS deployments, and tighter mobile OAuth flows. Workstation continues engineering on behalf of CognoAI; product direction and IP remain with CognoAI.

Engineering readers should watch three integration documents in the upstream repo: HMRC MTD Integration (phases A-D for preview calculation), Shared Authentication (JWT + refresh rotation), and AI Training Data Pipeline (pgvector embeddings plus MinIO markdown exports of accountant corrections). Together they show how today's demo pipeline becomes a learning system — classifications improve when professionals fix mistakes, without retraining the tax calculator.

For operators, production deployment means ENVIRONMENT=production, HTTPS termination in front of nginx, database backups, secrets outside flat .env files, and alerting beyond Gatus green lights. None of that diminishes the core story: AI removes spreadsheet friction; deterministic code holds tax law; humans retain accountability.

13b. Frequently asked questions

Does FileMyTax replace my accountant? No. It reduces prep labour; accountants still validate treatment, reliefs, and other income sources not on the bank PDF.

Can I run this on a phone? LAN mode rewrites CORS and API URLs to your Wi-Fi IP so you can test the Next.js UI on a phone on the same network — useful for demos, not a substitute for hardened mobile release engineering.

What if the LLM is down? Classification returns uncategorised rows with zero confidence; the pipeline does not silently switch providers. You fix provider config or wait — another reason human review exists.

Is DIY TAX RETURN mentioned here? No. That name refers to separate CognoAI product branding. This article uses FileMyTax only, per publication rules.

13c. 2025-26 calculation snapshot

For readers verifying the deterministic engine against HMRC guidance, the 2025/26 parameters baked into the calculator include: personal allowance £12,570 reducing by £1 for every £2 of income above £100,000; basic rate 20% between £12,571 and £50,270; higher rate 40% up to £125,140; additional rate 45% above that; Class 4 NI at 8% on profits between £12,571 and £50,270 and 2% above. Expense categories align to HMRC self-employment boxes — costOfGoods, premisesRunningCosts, travelCosts, professionalFees, and the remainder listed in the platform README. The engine consumes classified totals; it does not reinterpret natural language descriptions. That boundary is what makes automated filing defensible: the LLM proposes labels; the calculator applies statute.

14. Conclusion

Can an AI system process and file a UK Self Assessment return to HMRC automatically? It can automate almost all preparation and expose a one-click file API — but responsible use demands human review, accountant sign-off, sandbox testing, and taxpayer OAuth. FileMyTax shows what that looks like in practice: six APIs, clear architecture, AI where pattern recognition wins, and deterministic code where the law requires precision.

Watch the demo on YouTube, visit CognoAI for the product context, and contact Workstation if you need this class of FinOps engineering on your stack.

SEO snapshot for this article

• SEO title: Can AI File Self Assessment to HMRC? | FileMyTax
• Meta description: FileMyTax demo: AI extracts bank PDFs, classifies SA transactions, calculates 2025-26 tax, files via HMRC MTD — with human review. Built by Workstation for CognoAI.
• Primary keywords: AI self assessment, FileMyTax, HMRC MTD, automatic tax filing, bank statement AI, CognoAI, Workstation
• Twitter / X (under 280 chars): Can AI file UK Self Assessment to HMRC? FileMyTax demo: bank PDF → classify → calculate → MTD, with human gate + sandbox first. Built by Workstation for @CognoAI. Video + 4k-word write-up. Not tax advice. #HMRC #MTD #AI #FileMyTax
• LinkedIn post: We published how FileMyTax — developed by Workstation for CognoAI — takes a landlord or sole-trader bank PDF through AI extraction, HMRC category classification, deterministic 2025-26 tax calculation, and MTD filing, with encrypted NINO storage, OAuth, and a hard human approval gate before submission. The long article covers the six-API pipeline, architecture SVGs, fraud prevention headers, and honest limits (pdfplumber column traps, LLM confidence guardrails). Watch the new demo video; get an accountant to sign off before any live file. Not tax advice.

Disclaimer: fictional bank data where referenced; FileMyTax is a demonstration name; not tax advice; accountant review required before live HMRC submission.