#GoFile Connect API

What the Connect API is

A compliance gateway for UK tax filing: your software calls one endpoint with a client and their figures, and #GoFile handles everything between that call and HMRC’s receipt.

Making Tax Digital is not a hard API to call once. It is a hard API to own. Recognition, OAuth grants that expire after 18 months, fraud-prevention headers that must describe the real originating device, obligation matching, period keys you must never invent, submission idempotency, and an audit trail that stands up years later — that is the work, and it never stops.

The Connect API is that work, done and maintained, behind a small REST surface. Version 1 covers VAT: checking a client is authorised, reading their full VAT position, filing a return, and following it to a receipt.

Who it’s for

The API is designed for an agent model: your partner firm connects its HMRC agent services account once, and that single authorisation covers every client it is authorised to act for.

How it works

Every request is a signed REST call. Everything that legally requires a human happens on a page we host.

GET /api/v1/vat/193054661/status

{
  "vat_number": "193054661",
  "mode": "live",
  "obligations": {
    "open": [
      { "period": { "start": "2026-04-01",
                    "end":   "2026-06-30" },
        "due": "2026-08-07",
        "overdue": false }
    ],
    "fulfilled": [ /* filed periods + figures */ ]
  }
}

{
  "external_client_id": "CLIENT-91827",
  "client_name": "Acme Trading Ltd",
  "vat_number": "193054661",
  "return": {
    "vat_due_sales": "12500.00",
    "total_vat_due": "12500.00",
    "net_vat_due":   "8300.00"
    /* ...nine boxes in total */
  }
}

{
  "id": "vfs_...",
  "status": "submitted",
  "receipt": {
    "gofile_reference": "GF-VAT-123",
    "form_bundle": "258868935084"
  }
}

The hosted approval — and why it matters

HMRC does not simply want a return; it wants to know the return came from a real person on a real device, and that a human took responsibility for the declaration. That is what fraud-prevention headers are for, and getting them wrong is a compliance problem, not a bug.

So the Connect API never asks your software to fake them. When you post a filing we return a URL to a page we host. On that page the authorised person signs in with two-factor authentication, their real device is captured, the return is displayed in full, and they confirm the declaration. Only then do we call HMRC — with headers built from that exact device, snapshotted alongside the submission as evidence.

The page carries your client through the one-off HMRC connection too. When a firm files for the first time, it authorises its agent services account there and comes straight back to the filing.

What you don’t have to build

You are never asked for a period key or a finalised flag — the API refuses them outright, because those are ours to determine and getting them wrong is how bad filings happen.

Sandbox and live

Modes are chosen by the key you sign with, so there is no global switch to flip and nothing to forget in a deployment:

• gfk_sandbox_… keys file to HMRC’s test environment. Free, unlimited, and safe to run in CI.
• gfk_live_… keys file real returns.

Both work at the same time. Your test suite can hit sandbox while production files live, and switching between them is a matter of which credential you sign with. Usage, request logs and daily limits are tracked separately per mode.

Security & evidence

Rotation is zero-downtime: several keys can be active at once, so you issue the new pair, deploy it, and revoke the old one once nothing signs with it.

Webhooks, logs and the developer portal

Filing is asynchronous by nature — a human has to approve, and HMRC has to answer. Rather than make you poll, we push signed events to your endpoint as a filing moves: awaiting approval, submitted, failed, and more. Each delivery is HMAC-signed with your webhook secret so you can verify it came from us.

The partner portal at api.gofile.co.uk gives your team:

• API keys — issue sandbox and live pairs, see last use, rotate and revoke.
• Request logs — every signed request with its status, error code, mode, duration and request id. Signature failures appear too, which is exactly what you need when you are getting HMAC wrong at 2am.
• Webhook deliveries — status, response code and retry schedule per event.
• Usage — requests and filings charted by day, split by mode.
• Billing — invoices, payment methods and your plan.

Pricing

Prices exclude VAT. Filing fees are added to your next monthly invoice. No per-client fees, no minimum volume, and no charge for sandbox filing — you only pay when a real return reaches HMRC.

What’s next

Version 1 is VAT, because that is where MTD is mandatory and volume is highest. The same model — one clean call, a hosted approval, a receipt — is designed to extend to the rest of UK compliance filing.

MTD for Income Tax is the natural next surface, and it is where the value of a simplified API is greatest: HMRC’s own ITSA interface spans a large number of endpoints and shapes, and we intend to collapse that into the same rational surface Connect gives you for VAT. If your roadmap depends on a specific tax or timeline, tell us — partner demand decides the order.

Get started