Getting started with the WeFile Developer API

Overview

The WeFile Developer API is a REST API that lets you automate the preparation and submission of UK Corporation Tax (CT600) returns and Companies House statutory accounts, without using the WeFile web wizard by hand. It is aimed at software platforms embedding filing capabilities into their own product, accounting firms and bureaus filing for many clients at scale, and developers building internal tooling around company filings. If you only need to file a handful of returns yourself, the standard web dashboard is usually simpler; the API earns its keep once you need to automate, batch, or integrate filing into another system.

Who is this Developer API guide for?

This guide assumes you are comfortable making authenticated HTTP requests and working with JSON. It walks through everything you need to make your first successful call, understand the recommended filing workflow, and reach production readiness. It intentionally sticks to the endpoints, fields, and behaviour documented on the full API Reference — it does not introduce new capabilities, SDKs, or shortcuts beyond what is documented there.

What do you need before activating API access?

Before you can call the API, you need an active Developer Package subscription. This is a standalone subscription priced at £500/year and includes up to 300 successful production filings. Testing in the sandbox environment does not count towards this limit — only successfully submitted production filings deduct from your quota.

To activate access, sign in to your WeFile dashboard and open the API Access section. From there you can start the Developer Package subscription and generate your first API key. You do not need to have any companies or filings already set up in WeFile to do this; API Access is managed independently per account.

How do you create and store API keys securely?

Once your Developer Package is active, you can generate API keys from the API Access page. WeFile issues two kinds of keys: live keys, prefixed wf_live_, and test keys, prefixed wf_test_. Give each key a descriptive name (for example 'Production Server' or 'CI Testing') so you can tell them apart later.

A generated key is shown to you only once at creation time. Copy it immediately into a secure secrets manager or environment variable — WeFile stores only a hash of the key and cannot redisplay it. Never embed API keys in client-side code, mobile apps, or public repositories. If a key is ever exposed or you no longer need it, revoke it from the API Access page; this immediately invalidates it, and you can generate a replacement.

Every request must include your key in the X-API-Key HTTP header. There is no separate authentication step or token exchange — the header is checked on every call.

What base URL and request format does the API use?

The production base URL for the API is https://wefile.co.uk/_api/v1. All endpoints in the documentation are relative to this base. Every request and response uses the application/json content type: send JSON-encoded bodies, and expect JSON-encoded responses back, including for error cases.

How do you make your first API request?

A good first call is a simple authenticated GET request, since it immediately confirms your key and connectivity are working before you touch any filing data. For example, listing submissions for a filing (GET /filing/submissions) or fetching a company's periods only requires your X-API-Key header and, where relevant, a query parameter — no request body is needed. If this call returns a 401, double-check the header name and that you are using the correct key for the environment (test vs live). If it returns a 403, check that your Developer Package subscription is active and has not run out of quota.

How does the end-to-end filing workflow work?

Once your first request works, the typical integration follows a fixed sequence of calls, mirroring how a filing is built up in the WeFile wizard itself:

First, add the company using its Companies House company number. Then fetch its outstanding accounting periods to find out what actually needs filing. Next, create a filing for the relevant period. With the filing created, save the Profit & Loss data, then save the Balance Sheet data. After the financial data is in place, set the filingTypes on the filing to indicate whether you are filing the CT600, the Companies House accounts, or both. Then supply credentialsData (Government Gateway and/or Companies House authentication details). At that point the filing is ready to submit: call the submit endpoint to transmit it, and poll the status endpoint to track progress through to acceptance or rejection. Finally, once documents are available, list them and generate the specific PDF or iXBRL document you need on demand.

Each of these steps corresponds to a documented endpoint on the full API Reference, which also lists the exact request and response shapes for every field mentioned here.

How do test and live API modes differ?

You can exercise this entire workflow without risk using a test API key. Test keys route submissions to the HMRC and Companies House sandbox/test environments instead of the live ones, and submissions made with a test key do not count towards your 300-filing quota. This makes test mode the right place to build out your integration, test error handling, and rehearse the full workflow before switching to a live key for real filings. Switching between test and live is simply a matter of which key you send in the X-API-Key header — the request shapes are identical.

How are validation, tax calculations and data responsibilities handled?

WeFile automatically calculates Corporation Tax from the Profit & Loss data you supply — you should not attempt to compute or submit the tax figure yourself. The system applies the small profits rate, main rate, and marginal relief as appropriate, and recalculates the exact figure at submission time regardless of what was previously saved.

You are responsible for supplying accurate underlying figures. Pay attention to the accountType you choose (micro or full) and whether a company is dormant, since dormant filings only require minimal balance sheet data and have all income, expense, and tax figures zeroed automatically. If an accounting period is longer than 12 months, WeFile automatically splits it into HMRC-compliant sub-periods and apportions the figures — you supply the full period and do not need to split it yourself. Whatever your integration automates, build in a review step before submitting live filings, since you and your users remain responsible for the accuracy of what gets filed with HMRC and Companies House.

How does WeFile protect filing credentials?

Filing requires sensitive credentials: Government Gateway IDs and passwords, and Companies House authentication codes. These must only ever be sent from your server, never from a browser or mobile client, since they are equivalent to a login.

WeFile encrypts Gateway passwords and Companies House authentication codes at rest, and any time you read a filing back through the API, these fields are returned as [REDACTED] rather than in plain text. Posting [REDACTED] back for those fields is safely ignored, so a typical read-modify-write cycle in your integration will not accidentally overwrite or corrupt stored credentials. If you would rather not persist credentials at all, you can supply them per request at submission time instead of saving them. Any credentials you have stored can be permanently deleted via the documented credentials delete endpoint whenever you no longer need them.

How should your integration handle API errors?

Every error response follows the same shape, an object with an error message describing what went wrong. The status codes you should specifically handle are: 400 for validation errors or constraint violations in your request; 401 when the X-API-Key header is missing or invalid; 403 when your subscription quota is exhausted or you are not authorized to access a particular resource; 404 when the resource does not exist; 429 when you have exceeded the rate limit; and 500 for an internal or upstream failure.

Treat these differently. Validation errors (400) and authentication/authorization failures (401, 403) will not succeed if you simply retry the same request — fix the underlying data or credentials first. A 429 means you should back off and slow down your request rate. A 500 may be transient and worth a limited retry, but if it persists it likely indicates an upstream issue worth investigating rather than retrying indefinitely.

What is the WeFile API rate limit?

The API enforces a standard rate limit of 100 requests per minute per API key. If you exceed this, you will receive a 429 Too Many Requests response. Design any batch or bulk integration to stay comfortably under this limit, especially if you are polling filing status or generating documents for many companies in sequence.

What documents and audit records can you access?

Once a filing has been submitted, WeFile keeps a record of each submission attempt, including validation failures such as a missing or incorrect authentication code, which is useful for building an audit trail in your own system. Generated statutory documents (PDF and iXBRL) are not pre-created for every filing; instead you list what is available for a filing and then generate the specific document you need on demand. This keeps document generation aligned with the current, final state of the filing rather than an earlier draft.

How do you prepare your integration for production?

Before pointing your integration at a live key, confirm the following: your API key is stored server-side only and never exposed to clients; you have built explicit handling for 400, 401, 403, 404, 429, and 500 responses rather than treating all failures the same way; you have exercised the full add-company-to-document-generation workflow against a test key; you understand which fields WeFile calculates for you (tax) versus which you must supply accurately (P&L, balance sheet, credentials); and you have a plan for rotating or revoking API keys if one is ever compromised.

What should you do next?

This guide intentionally sticks to concepts and sequencing. For the exact request and response schemas, field-by-field validation rules, and full worked examples for every endpoint mentioned above, see the full API Documentation at /api-docs. To generate or manage your API keys and review your Developer Package subscription and remaining quota, visit /api-access.