WeFile API Documentation

Integrate CT600 and Companies House filing capabilities directly into your software.

Introduction

The WeFile API is organized around REST. Our API has predictable resource-oriented URLs, accepts form-encoded request bodies, returns JSON-encoded responses, and uses standard HTTP response codes, authentication, and verbs.

Base URLhttps://api.wefile.co.uk/v1

All requests and responses must use application/json content type.

Authentication

The WeFile API uses API keys to authenticate requests. You can view and manage your API keys in the API Access section of your dashboard.

Authentication to the API is performed via HTTP Headers. Provide your API key as the X-API-Key header. We provide both live (wf_live_) and test (wf_test_) keys.

bash

curl https://api.wefile.co.uk/v1/filings \
  -H "X-API-Key: wf_live_1234567890abcdef" \
  -H "Content-Type: application/json"

Keep your keys secure! Your API keys carry many privileges. Do not share your secret API keys in publicly accessible areas such as GitHub, client-side code, and so forth.

API Subscription

Access to the API requires an active Developer Package subscription. The package costs £500/year and includes up to 300 successful company filings.

Testing in the sandbox environment does not count towards your filing limit.
Only successfully submitted production filings deduct from your quota.
You can monitor your remaining quota programmatically via the account endpoints or the visual dashboard.

Test Mode

You can test your integration without affecting live data or consuming your filing quota by using a test API key.

Test keys use the wf_test_ prefix, while live keys use wf_live_.
Filings submitted with a test key are routed to the HMRC and Companies House test/sandbox environments.
Test submissions do not count towards your 300 filing quota.
Test mode is ideal for integration development, testing error handling, and verifying workflows.

bash

curl https://api.wefile.co.uk/v1/filings \
  -H "X-API-Key: wf_test_1234567890abcdef" \
  -H "Content-Type: application/json"

Companies

List Companies

GET/companies

Fetches a list of companies owned by the authenticated API user.

Parameter (Query)	Type	Description
`page`	number	Page number (default 1)
`limit`	number	Items per page (default 10)
`search`	string	Search by name or number
`status`	string	"active" or "archived"

bash

curl "https://api.wefile.co.uk/v1/companies?page=1&limit=10" -H "X-API-Key: YOUR_KEY"

json

{
  "data": [
    {
      "id": 1,
      "companyName": "ACME CORP",
      "companyNumber": "12345678",
      "registeredAddress": "1 Acme Way, London",
      "filingCount": 2
    }
  ],
  "totalCount": 1
}

Add Company

POST/company/add

Adds a company to the API user's workspace using the Companies House API to fetch details automatically.

Parameter (Body)	Type	Description
`companyNumber`	string	8-character CH number

bash

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

json

{
  "id": 2,
  "companyName": "ACME CORP",
  "companyNumber": "12345678",
  "registeredAddress": "1 Acme Way, London",
  "incorporationDate": "2020-01-01T00:00:00Z"
}

Get Periods

GET/company/periods

Fetches accounting periods for a specific company by communicating with Companies House.

Parameter (Query)	Type	Description
`companyId`	number	The internal WeFile ID of the company

bash

curl "https://api.wefile.co.uk/v1/company/periods?companyId=2" -H "X-API-Key: YOUR_KEY"

json

{
  "accountingReferenceDate": { "day": "31", "month": "12" },
  "isOverdue": false,
  "periods": [
    {
      "periodStart": "2023-01-01T00:00:00Z",
      "periodEnd": "2023-12-31T00:00:00Z",
      "isFiled": false,
      "isOverdue": false,
      "dueDate": "2024-09-30T00:00:00Z",
      "hmrcFiled": false,
      "chFiled": false,
      "isFiledOnWeFile": false
    }
  ]
}

Filings

List Filings

GET/filings

Lists all filings for the authenticated API user.

Parameter (Query)	Type	Description
`page`	number	Page number
`limit`	number	Items per page
`search`	string	Search text
`status`	string	Status filter

bash

curl "https://api.wefile.co.uk/v1/filings" -H "X-API-Key: YOUR_KEY"

Create Filing

POST/filing/create

Creates a new draft filing for a given company and accounting period.

Parameter (Body)	Type	Description
`companyId`	number	WeFile internal company ID
`periodStart`	string	ISO date string
`periodEnd`	string	ISO date string
`isDormant`	boolean	Is dormant accounts?
`directorName`	string	Full name of the signing director (optional)
`numberOfEmployees`	number	Average number of employees (integer, min 0) (optional)
`includePnlInAccounts`	boolean	Include Profit & Loss in Companies House accounts (optional)

bash

curl -X POST https://api.wefile.co.uk/v1/filing/create \
  -H "X-API-Key: YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"companyId":2,"periodStart":"2023-01-01","periodEnd":"2023-12-31","isDormant":false,"directorName":"John Smith","numberOfEmployees":5,"includePnlInAccounts":true}'

Save Filing

POST/filing/save

Updates filing data (P&L, Balance Sheet, Credentials) and optionally triggers payment transition if status set to "in_progress".

Parameter (Body)	Type	Description
`filingId`	number	WeFile filing ID
`profitLossData`	object	See Schemas
`balanceSheetData`	object	See Schemas
`credentialsData`	object	See Schemas
`status`	string	Target status (e.g., in_progress)
`accountType`	string	e.g., micro-entity
`includePnlInAccounts`	boolean	Include PNL?
`numberOfEmployees`	number	Average number of employees (integer, min 0) (optional)

bash

curl -X POST https://api.wefile.co.uk/v1/filing/save \
  -H "X-API-Key: YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"filingId": 123, "status": "in_progress", "profitLossData": {"turnover": 1000}}'

Submit Filing

POST/filing/submit

Submits the filing data to HMRC, Companies House, or both.

Parameter (Body)	Type	Description
`filingId`	number	WeFile filing ID
`target`	string	"hmrc", "ch", or "both"

bash

curl -X POST https://api.wefile.co.uk/v1/filing/submit \
  -H "X-API-Key: YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"filingId": 123, "target": "both"}'

Get Status

GET/filing/status

Checks overall filing status and returns submission history after forcing an inline poll to upstream systems.

Parameter (Query)	Type	Description
`filingId`	number	WeFile filing ID

bash

curl "https://api.wefile.co.uk/v1/filing/status?filingId=123" -H "X-API-Key: YOUR_KEY"

Important Notes

Automatic Tax Calculation

WeFile automatically calculates corporation tax from the Profit & Loss data — developers do NOT need to compute it. The rates are:

19% small profits rate: applies if profits are £50,000 or less.
25% main rate: applies if profits are £250,000 or more.
Marginal relief: applies to profits between £50,000 and £250,000.

If taxOnProfit is provided in profitLossData, it is stored but the system dynamically recalculates the exact tax due for the actual CT600 and iXBRL generation. For dormant companies, all tax values are automatically set to zero.

Provide only the raw figures, and WeFile handles the computed totals (e.g., gross profit, tax, and profit for the year).

json

{
  "turnover": 150000,
  "costOfSales": 45000,
  "administrativeExpenses": 20000
  // Note: grossProfit, corporationTax, and profitForTheYear are auto-calculated
}

Accounting Period Splitting

HMRC strictly requires CT600 returns to cover no more than 12 months. If the accounting period exceeds 12 months, WeFile automatically:

Splits the filing into two sub-periods (first 12 months + remainder).
Apportions P&L figures proportionally based on the number of days in each sub-period.
Duplicates the Balance Sheet for both sub-periods (as it represents a snapshot of the final position).
Generates separate CT600 submissions for each sub-period sequentially.

The developer just provides the full period data — splitting is handled transparently. For example, a period from 2023-01-01 to 2024-06-30 (18 months) is split into 2023-01-01 to 2023-12-31 (365 days) and 2024-01-01 to 2024-06-30 (182 days).

Dormant vs Trading Filings

When creating a filing, clearly distinguish between dormant and trading activity:

Dormant: set isDormant: true at creation. No P&L data needed. Only minimal balance sheet data is required (e.g. cashAtBank, calledUpShareCapital). All income, expense, and tax figures are automatically set to zero.
Trading: set isDormant: false. Must provide comprehensive profitLossData and balanceSheetData. The accountType should ideally be set to "micro-entity" or "small-company".

Submissions

List Submissions

GET/filing/submissions

Gets historical submissions (HMRC / CH) for a filing without triggering an inline poll.

bash

curl "https://api.wefile.co.uk/v1/filing/submissions?filingId=123" -H "X-API-Key: YOUR_KEY"

Documents

List Documents

GET/filing/document/list

Lists available documents for a filing (e.g. generated PDFs, CT600 forms).

bash

curl "https://api.wefile.co.uk/v1/filing/document/list?filingId=123" -H "X-API-Key: YOUR_KEY"

Download Document

GET/filing/document/download

Downloads base64 content of a document.

bash

curl "https://api.wefile.co.uk/v1/filing/document/download?documentId=456" -H "X-API-Key: YOUR_KEY"

Data Schemas

Profit & Loss

Fields included in `profitLossData`. All monetary values must be whole GBP integers.

json

{
  "turnover": 0,
  "costOfSales": 0,
  "grossProfit": 0, // Computed automatically if absent
  "administrativeExpenses": 0,
  "distributionCosts": 0,
  "otherOperatingIncome": 0,
  "interestReceivable": 0,
  "interestPayable": 0,
  "taxOnProfit": 0
}

Balance Sheet

Fields included in `balanceSheetData`.

json

{
  "tangibleAssets": 0,
  "intangibleAssets": 0,
  "debtors": 0,
  "cashAtBank": 0,
  "creditors": 0, // Creditors falling due within 1 yr
  "creditorsAfterOneYear": 0,
  "provisionsForLiabilities": 0,
  "calledUpShareCapital": 0,
  "profitAndLossAccount": 0 // Accumulated profit
}

Credentials

Fields included in `credentialsData`. Note: directorName can also be set at filing creation time via the create endpoint.

json

{
  "utrNumber": "1234567890",
  "gatewayId": "some_id",
  "gatewayPassword": "some_password",
  "authCode": "123456", // CH Auth Code
  "directorName": "John Doe"
}

Constants & Types

Filing Types: ct600, accounts
Account Types: micro-entity, small-company, dormant

Workflow Guide

Add Company

POST to `/v1/company/add` using the CH company number.

Get Periods

GET to `/v1/company/periods` to find out what dates need filing.

Create Filing

POST to `/v1/filing/create` with the dates.

Save P&L

POST to `/v1/filing/save` with `profitLossData`.

Save Balance Sheet

POST to `/v1/filing/save` with `balanceSheetData`.

Save Credentials

POST to `/v1/filing/save` with `credentialsData` and optionally `status: "in_progress"` to lock it.

Submit

POST to `/v1/filing/submit` to transmit.

Poll Status

GET to `/v1/filing/status` to wait for acceptance or rejection.

Download Docs

GET to `/v1/filing/document/list` and `/v1/filing/document/download`.

Error Handling

Responses use the standard format: { "error": "message" }

Code	Meaning
400	Bad Request. Validation errors or common application constraints.
401	Unauthorized. Missing or invalid X-API-Key.
403	Forbidden. Subscription limit exhausted or unauthorized access to resource.
404	Not Found. Resource does not exist.
500	Internal Server Error. Upstream failure or internal issue.

Credential Recovery Workflow

If a submission fails with a credential error (e.g. invalid UTR or Gateway), the overall status transitions to requires_attention. Update credentials via /v1/filing/save and resubmit.

Filing Statuses

draftin_progressawaiting_paymentsubmittedrequires_attentioncompleted

Submission Statuses

pendingpollingacceptedrejectederrorpreviously_submitted

Rate Limits

To ensure stability and performance, the API is rate limited. Limits are enforced per API key.

Standard Limit100 requests per minute

If you exceed this limit, the API will respond with a 429 Too Many Requests status code.

Full API Examples

1. Dormant Company Filing

This example demonstrates the complete end-to-end workflow for a dormant company. It shows creating a filing with isDormant: true, supplying minimal balance sheet data (just cash at bank and called-up share capital), and submitting it concurrently to both agencies.

bash

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

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

# 3. Create Filing (isDormant: true)
curl -X POST https://api.wefile.co.uk/v1/filing/create \
  -H "X-API-Key: YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "companyId": 2,
    "periodStart": "2023-01-01",
    "periodEnd": "2023-12-31",
    "isDormant": true,
    "directorName": "Jane Doe"
  }'

# 4. Save Balance Sheet
curl -X POST https://api.wefile.co.uk/v1/filing/save \
  -H "X-API-Key: YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "filingId": 123,
    "balanceSheetData": {
      "cashAtBank": 100,
      "calledUpShareCapital": 100
    }
  }'

# 5. Save Credentials & Lock Filing
curl -X POST https://api.wefile.co.uk/v1/filing/save \
  -H "X-API-Key: YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "filingId": 123,
    "status": "in_progress",
    "credentialsData": {
      "utrNumber": "1234567890",
      "gatewayId": "user123",
      "gatewayPassword": "password123",
      "authCode": "222222"
    }
  }'

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

# 7. Poll Status
curl "https://api.wefile.co.uk/v1/filing/status?filingId=123" \
  -H "X-API-Key: YOUR_KEY"

# 8. Download Documents (Once accepted)
curl "https://api.wefile.co.uk/v1/filing/document/list?filingId=123" \
  -H "X-API-Key: YOUR_KEY"

2. Trading Company Filing

This example demonstrates the workflow for a standard trading company. It involves creating a regular filing, saving comprehensive Profit & Loss figures, saving the accompanying Balance Sheet, locking the filing with credentials, and polling the status post-submission.

bash

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

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

# 3. Create Filing (isDormant: false)
curl -X POST https://api.wefile.co.uk/v1/filing/create \
  -H "X-API-Key: YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "companyId": 3,
    "periodStart": "2023-01-01",
    "periodEnd": "2023-12-31",
    "isDormant": false,
    "directorName": "John Smith",
    "numberOfEmployees": 5,
    "includePnlInAccounts": true
  }'

# 4. Save Profit & Loss
curl -X POST https://api.wefile.co.uk/v1/filing/save \
  -H "X-API-Key: YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "filingId": 124,
    "profitLossData": {
      "turnover": 150000,
      "costOfSales": 45000,
      "administrativeExpenses": 20000,
      "otherOperatingIncome": 500,
      "taxOnProfit": 16150
    }
  }'

# 5. Save Balance Sheet
curl -X POST https://api.wefile.co.uk/v1/filing/save \
  -H "X-API-Key: YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "filingId": 124,
    "balanceSheetData": {
      "tangibleAssets": 15000,
      "debtors": 12000,
      "cashAtBank": 85000,
      "creditors": 25000,
      "calledUpShareCapital": 100,
      "profitAndLossAccount": 86900
    }
  }'

# 6. Save Credentials & Lock Filing
curl -X POST https://api.wefile.co.uk/v1/filing/save \
  -H "X-API-Key: YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "filingId": 124,
    "status": "in_progress",
    "credentialsData": {
      "utrNumber": "0987654321",
      "gatewayId": "user456",
      "gatewayPassword": "password456",
      "authCode": "333333"
    }
  }'

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

# 8. Poll Status
curl "https://api.wefile.co.uk/v1/filing/status?filingId=124" \
  -H "X-API-Key: YOUR_KEY"

# 9. Download Documents (Once accepted)
curl "https://api.wefile.co.uk/v1/filing/document/list?filingId=124" \
  -H "X-API-Key: YOUR_KEY"