Introducing the WeFile Developer API: Automate CT600 and Companies House Filings at Scale

Since launching WeFile, we have helped thousands of companies file their CT600 corporation tax returns and Companies House annual accounts through our step-by-step filing wizard. The wizard is designed for directors and small business owners who file once or twice a year.

But we kept hearing the same request from accountancy practices, bookkeeping platforms, and software developers: "Can we plug into WeFile programmatically?"

The answer is now a resounding yes. The WeFile Developer API lets you automate the entire filing lifecycle — from adding a company and retrieving its accounting periods, through saving financial data and HMRC credentials, all the way to submitting to both HMRC and Companies House and downloading the generated documents — using simple REST calls.

The API is designed for anyone who needs to file at volume or embed filing capabilities into an existing product:

• Accountancy practices that manage dozens or hundreds of limited companies and want to submit returns directly from their practice management software.
• Bookkeeping and accounting platforms that want to offer end-to-end filing as a built-in feature, so their users never have to leave the app.
• Company formation agents that set up new limited companies and need to file the first set of dormant accounts automatically.
• In-house development teams at larger firms that want to integrate CT600 filing into internal finance systems.
• Developers and freelancers building tools for the UK small business ecosystem.

Whether you are filing for 10 companies or 300, the API handles it with the same straightforward workflow.

The API mirrors the same logical steps as the WeFile wizard, but expressed as a sequence of REST endpoints. Here is the high-level flow:

1. Add a company — POST the Companies House number. WeFile fetches the company name, registered address, and incorporation date automatically.
2. Get accounting periods — WeFile queries Companies House to determine which periods need filing and whether any are overdue.
3. Create a filing — specify the period dates and whether the company is dormant or trading.
4. Save financial data — POST the Profit & Loss and Balance Sheet figures. Corporation tax is calculated automatically — you just provide the raw numbers.
5. Save credentials — provide the HMRC Gateway ID, password, UTR, and Companies House authentication code.
6. Submit — fire the filing to HMRC, Companies House, or both in a single call.
7. Poll for status — check whether the submission has been accepted or rejected.
8. Download documents — retrieve the generated CT600 PDF, iXBRL accounts, and any other output documents.

Each step is a single API call. The entire lifecycle from company registration to document download can be scripted in under 50 lines of code.

One of the most powerful features of the API is that you do not need to calculate corporation tax yourself. Just provide the raw Profit & Loss figures — turnover, cost of sales, administrative expenses, and so on — and WeFile computes the correct tax automatically.

The calculation follows the current HMRC rates:

• 19% small profits rate for taxable profits of £50,000 or less.
• 25% main rate for taxable profits of £250,000 or more.
• Marginal relief for profits between £50,000 and £250,000, calculated using the statutory formula.

Computed fields such as gross profit, operating profit, profit on ordinary activities, and profit for the financial year are all derived automatically. For dormant companies, every income, expense, and tax field is set to zero — you only need to provide the minimal balance sheet data (typically just cash at bank and called-up share capital).

This means your integration code stays simple: send the numbers your accounting system already has, and let WeFile handle the tax maths and iXBRL tagging.

HMRC requires that a CT600 return covers no more than 12 months. If a company has an accounting period longer than 12 months (common for first-year companies whose incorporation date doesn't align with their year-end), the API handles the split transparently.

When you create a filing with, say, an 18-month period from 1 January 2024 to 30 June 2025, WeFile automatically:

1. Splits the period into two sub-periods — the first 12 months (1 Jan 2024 – 31 Dec 2024) and the remainder (1 Jan 2025 – 30 Jun 2025).
2. Apportions the Profit & Loss figures proportionally based on the number of days in each sub-period.
3. Duplicates the Balance Sheet for both sub-periods, since it represents a point-in-time snapshot of the company's financial position at period end.
4. Generates and submits two separate CT600 returns to HMRC, sequentially.

From the developer's perspective, this is completely transparent. You provide one set of data for the full period, and WeFile does the rest.

The API supports both dormant and trading company filings. The distinction is made at filing creation time:

Dormant Companies

Set isDormant: true when creating the filing. No Profit & Loss data is needed. You only need to provide minimal Balance Sheet data — typically cashAtBank and calledUpShareCapital. All income, expense, and tax figures are automatically zeroed out. This is the simplest filing type, often completed in just four API calls (add company, create filing, save balance sheet with credentials, submit).

Trading Companies

Set isDormant: false. You must provide comprehensive Profit & Loss data (turnover, cost of sales, administrative expenses, etc.) and a full Balance Sheet. The account type should be set to micro-entity or small-company depending on the company's size thresholds. WeFile validates that the balance sheet balances before allowing submission.

The API uses API key authentication via the X-API-Key HTTP header. You can generate and manage your keys from the API Access dashboard.

WeFile provides two types of keys:

• Live keys (prefixed wf_live_) — submit to the real HMRC and Companies House production environments. Each successful submission counts towards your filing quota.
• Test keys (prefixed wf_test_) — submit to HMRC and Companies House sandbox/test environments. Test submissions do not count towards your quota, making them ideal for development and integration testing.

You can have multiple active keys at the same time, rotate them as needed, and revoke any key instantly from the dashboard.

The Developer API Package is a standalone annual subscription:

• £500 per year
• Up to 300 successful filings per subscription period
• Test mode submissions are free and unlimited

The API subscription is completely independent of the standard WeFile accountant membership (£250/year, 100 filings). You can hold both subscriptions simultaneously if you want to use the web wizard for some companies and the API for others.

You can monitor your remaining quota from the API Access dashboard or programmatically through the API itself. If you exhaust your 300-filing limit, you can renew the subscription immediately to continue filing.

The API returns standard HTTP status codes and structured JSON error messages. Key codes include:

• 400 Bad Request — validation errors or missing required fields.
• 401 Unauthorized — missing or invalid API key.
• 403 Forbidden — subscription expired or filing quota exhausted.
• 404 Not Found — the requested resource does not exist.
• 429 Too Many Requests — rate limit exceeded (100 requests per minute per key).

Filing status transitions follow a clear lifecycle: draft → in_progress → submitted → completed (or requires_attention if a credential error occurs). If HMRC or Companies House rejects a submission due to incorrect credentials, you can update them via the save endpoint and resubmit — no need to recreate the filing.

Here is a minimal example that files dormant accounts for a company in just a few API calls:

# 1. Add the company
curl -X POST https://api.wefile.co.uk/v1/company/add \
  -H "X-API-Key: wf_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"companyNumber":"12345678"}'

# 2. Get accounting periods
curl "https://api.wefile.co.uk/v1/company/periods?companyId=2" \
  -H "X-API-Key: wf_live_YOUR_KEY"

# 3. Create a dormant filing
curl -X POST https://api.wefile.co.uk/v1/filing/create \
  -H "X-API-Key: wf_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"companyId":2,"periodStart":"2025-01-01","periodEnd":"2025-12-31","isDormant":true,"directorName":"Jane Smith"}'

# 4. Save balance sheet + credentials, then submit
curl -X POST https://api.wefile.co.uk/v1/filing/save \
  -H "X-API-Key: wf_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"filingId":123,"status":"in_progress","balanceSheetData":{"cashAtBank":100,"calledUpShareCapital":100},"credentialsData":{"utrNumber":"1234567890","gatewayId":"user123","gatewayPassword":"pass123","authCode":"222222"}}'

# 5. Submit to both HMRC and Companies House
curl -X POST https://api.wefile.co.uk/v1/filing/submit \
  -H "X-API-Key: wf_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"filingId":123,"target":"both"}'

That is five API calls from start to finish. The entire process can run unattended in a cron job or be triggered by a button in your own application.

The API accepts financial data as JSON objects. Here are the key schemas:

Profit & Loss (profitLossData)

All monetary values are whole GBP integers (pence are not used):

• turnover — total revenue / sales
• costOfSales — direct costs of goods or services sold
• administrativeExpenses — overheads, salaries, rent, etc.
• distributionCosts — delivery, marketing costs
• otherOperatingIncome — grants, miscellaneous income
• interestReceivable — bank interest earned
• interestPayable — loan interest paid
• taxOnProfit — optional; auto-calculated if omitted

Balance Sheet (balanceSheetData)

• tangibleAssets, intangibleAssets — fixed assets
• debtors — trade debtors and prepayments
• cashAtBank — cash and bank balances
• creditors — creditors due within one year
• creditorsAfterOneYear — long-term creditors
• calledUpShareCapital — share capital issued
• profitAndLossAccount — accumulated retained profit

The balance sheet must balance: total assets must equal total liabilities plus equity. WeFile validates this before submission.

We take security seriously. Here is how the API protects your data:

• HTTPS only — all API traffic is encrypted in transit. Plain HTTP requests are rejected.
• API key scoping — each key is tied to a specific user account. Keys can be revoked instantly.
• Credential encryption — HMRC Gateway credentials and Companies House auth codes are encrypted at rest and are never included in API responses after submission.
• Short-lived sessions — the API does not maintain persistent sessions. Each request is independently authenticated.
• Rate limiting — 100 requests per minute per key to prevent abuse.
• Test isolation — test-mode submissions go to HMRC and Companies House sandbox environments and never touch live government systems.

Ready to integrate? Here is how to get up and running:

1. Create a WeFile account at wefile.co.uk if you don't have one already.
2. Subscribe to the Developer API Package from the API Access page (£500/year, 300 filings).
3. Generate your API keys — create both a test key and a live key from the API Access dashboard.
4. Read the full documentation at wefile.co.uk/api-docs — it includes endpoint references, data schemas, workflow guides, and complete curl examples for dormant and trading filings.
5. Build and test using your wf_test_ key against the sandbox environments.
6. Go live — switch to your wf_live_ key and start filing for real.

If you have questions, feature requests, or need help with your integration, our support team is available via the live chat on the bottom right of the screen or through a support ticket. We are always happy to help developers get the most out of the API.

Happy filing! 🚀