Developer API: Authentication and Getting Started

Authentication

All API requests require your API key in the `X-API-Key` request header.

``` GET /api/v1/filings X-API-Key: tt_test_yourkey... ```

Your API key is available from the API section of your account settings. It will look like one of these:

`tt_test_...` — test (sandbox) key
`tt_live_...` — live key

Common cause of "Invalid API Key": The key must be passed in the `X-API-Key` header specifically. Passing it as a query parameter (`?api_key=...`) or in an `Authorization: Bearer ...` header will not work.

Test Keys vs Live Keys

	Test key (`tt_test_...`)	Live key (`tt_live_...`)
Reaches HMRC / Companies House	No	Yes
Filings stored	No (stateless)	Yes
Balance required	No	Yes (for submissions)
`GET /filings` returns	Empty array	Your real filings

Tip: Use your test key while developing. You can make submission requests and get realistic responses without actually filing anything or spending balance.

Do I Need to Top Up My Balance?

Only for filing submissions. Read-only endpoints like `GET /api/v1/filings` and `GET /api/v1/companies/{number}` work with any valid key, with no balance required.

When you submit a CT600 or accounts via `POST /api/v1/filings/ct600` or `POST /api/v1/filings\/accounts`, the API charges £20 per accepted filing from your balance. If your balance is too low, the submission returns a `402 INSUFFICIENT_BALANCE` error before anything is sent to HMRC.

To top up: Go to API Settings → Billing in your account. Payments are processed via Stripe. Your balance updates immediately.

Sandbox (test key) submissions do not consume balance — they are free and stateless.

Is There VAT on API Charges?

No. The £20 per accepted filing charge is the full amount — no VAT is added on top.

Troubleshooting "Invalid API Key"

If you are certain the key is correct but still getting this error, check:

Header name — Must be passed as `X-API-Key`. The header name is case-insensitive on the server — Python's `httpx`, HTTP/2 clients, and most modern libraries send headers in lowercase; the server normalises this automatically so `x-api-key` and `X-API-Key` are treated identically.
Complete key — The full key format is `tt_live_<12 chars>_<32 chars>` (four segments separated by underscores). If you copied only the key prefix without the final 32-character segment, the key will fail format validation. Check your API Settings page and copy the entire string.
No extra whitespace — Trailing or leading spaces in the key value cause failures. Copy carefully, especially from emails or terminal output.
Correct key type — Test keys (`tt_test_...`) and live keys (`tt_live_...`) are separate credentials. If your account only shows a live key, using a test key ID will fail — see FAQ below.
Key is active — Check your API Settings page confirms the key is enabled.

If the key still does not work after these checks, contact hello@clearbookstax.co.uk and we will investigate.

Common Questions

Can I use a live key for development?

We recommend using your test key for development — it is free, stateless, and safe. Live keys submit real filings to HMRC and Companies House.

I only see a live key in my account — can I get a test key?

Test and live keys are separate credentials. Some accounts are issued a live key only. If you need a test key for sandbox development, check the API Settings section of your account — if no test key is shown, contact hello@clearbookstax.co.uk to request one activated.

The `GET /filings` endpoint returns an empty array with my test key — is that correct?

Yes. Test keys run in sandbox mode, where submissions are not stored. The endpoint returns `[]` because there are no sandbox filings to list. This is expected behaviour.

How do I know my balance before submitting?

Check `GET /api/v1/balance` — it returns your current balance and price per filing.

Was this guide helpful?

Thanks for your feedback!