HMRC compliance

The Public API exposes a small hmrc.* read surface — VAT obligations/liabilities/payments/return view, ITSA status/obligations/calculations, and Self Assessment status/filing summary — mounted at /api/rpc/hmrc/... and forwarded to ac-co.ai's HMRC filing service. See the hmrc group in the API Reference for the exact endpoints.

This is a restricted surface

Both hmrc:read and hmrc:write are restricted scopes: they require manual approval by ac-co.ai before we'll grant them to your API key or OAuth client, even though you can select them in the key creator or request them in an OAuth scope parameter. If you need HMRC access, contact us to request approval — an unapproved key or client simply won't be granted the scope.

hmrc:write exists in the scope catalog as a documented future extension. Nothing in the API currently writes to HMRC — every endpoint exposed today is read-only.

Compliance is the client's responsibility

HMRC's Making Tax Digital APIs carry real regulatory obligations that sit with you, the API client, not with ac-co.ai:

• Fraud prevention headers — HMRC requires specific headers (device ID, user IP, screen resolution, and more) on every MTD API call, sourced from the end user's actual device/browser. If your integration calls through to HMRC on a user's behalf, you are responsible for meeting HMRC's fraud-prevention header requirements for your own client.
• Vendor terms and conditions — using HMRC's MTD APIs requires accepting HMRC's software vendor terms. That agreement is between you and HMRC, not something ac-co.ai can accept on your behalf.

We do not indemnify or take on these obligations for you. Read HMRC's Making Tax Digital for developers documentation if you're building against this surface.

Current implementation status

HMRC forwarding is live: a correctly-scoped request to an hmrc.* endpoint is forwarded server-to-server to ac-co.ai's HMRC filing service and returns the real HMRC-backed data. What gates access today is scope, not implementation status — a request without hmrc:read gets a normal 403 insufficient_scope, and hmrc:read itself is only granted after the manual approval described above. There's no self-serve path to live HMRC data; approval is the gate.

If the upstream HMRC filing service is unreachable when we try to forward your request, you'll get:

{
  "error": "bad_gateway",
  "message": "HMRC service unreachable: <reason>"
}

with HTTP status 502. This reflects an outage or connectivity issue on our HMRC service, not a problem with your request — retry with backoff. Every endpoint in the API (entities, accounting, banking, landlord, assets, vault, billing, periods, and now hmrc) is fully implemented today.