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)
`associatedCompanies`	number	Number of associated companies in the period (integer, 0–99, optional). Affects marginal relief thresholds. Forced to 0 for dormant filings.
`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,"associatedCompanies":1,"includePnlInAccounts":true}'

Create Amendment

POST/filing/create

Creates an amendment for an existing filing. When isAmendment is true, the original filing's data is copied automatically.

Parameter (Body)	Type	Description
`companyId`	number	WeFile internal company ID
`periodStart`	string	ISO date string
`periodEnd`	string	ISO date string
`isAmendment`	boolean	Set to true to create an amendment
`amendmentOfFilingId`	number	The ID of the original filing to amend

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,"isAmendment":true,"amendmentOfFilingId":123}'

Create Direct Amendment

POST/filing/create

Creates an amendment filing without referencing an existing filing in WeFile. Use this when the original return was filed through another provider (e.g. TaxCalc, TaxFiler) or when you don't have the original filing ID in WeFile. Set isAmendment to true and omit amendmentOfFilingId.

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?
`isAmendment`	boolean	Set to true (must be true)
`directorName`	string	Full name of the signing director (optional)
`numberOfEmployees`	number	Average number of employees (integer, min 0) (optional)
`associatedCompanies`	number	Number of associated companies in the period (integer, 0–99, optional). Affects marginal relief thresholds. Forced to 0 for dormant filings.
`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,"isAmendment":true}'

NoteUnlike linked amendments, direct amendments start with empty financial data. You must save all P&L, balance sheet, and credentials data before submitting.

Save Filing

POST/filing/save

Updates filing data (P&L, Balance Sheet, Credentials, Filing Types) and optionally triggers payment transition if status set to "in_progress". When isDormant is set to true, numberOfEmployees and associatedCompanies are automatically forced to 0.

Parameter (Body)	Type	Description
`filingId`	number	WeFile filing ID
`profitLossData`	object	See Schemas (Supports `disallowableExpenses` number field, defaults to 0, which is added back to trading profit for corporation tax calculation).
`balanceSheetData`	object	See Schemas
`previousProfitLossData`	object	Previous period P&L data for comparative figures (optional).
`previousBalanceSheetData`	object	Previous period balance sheet data for comparative figures (optional).
`taxCalculation`	object	Tax calculation override data (optional; system auto-calculates if omitted).
`credentialsData`	object	See Schemas. Includes optional `boardApprovalDate` (DD/MM/YYYY) — the date the board approved the accounts. Defaults to the period end date if omitted.
`notesData`	array	Array of custom notes to include in financial statements. Each note is an object with `title` (string, max 200 chars) and `body` (string, max 5000 chars). Maximum 20 notes. See Important Notes.
`filingTypes`	object	Filing type selection, e.g. `{ "ct600": true, "accounts": true }`. Required before submission.
`status`	string	Target status (e.g., in_progress)
`accountType`	string	e.g., micro-entity
`includePnlInAccounts`	boolean	Include PNL?
`isDormant`	boolean	Mark filing as dormant. When set to true, numberOfEmployees is automatically forced to 0.
`numberOfEmployees`	number	Average number of employees (integer, min 0) (optional)
`associatedCompanies`	number	Number of associated companies in the period (integer, 0–99, optional). Forced to 0 when isDormant is true.

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.

Note: The £50,000 and £250,000 thresholds are divided by (1 + number of associated companies) before being pro-rated for the period length. For example, with 1 associated company, the lower limit becomes £25,000 and the upper limit becomes £125,000. If associatedCompanies is not provided, it defaults to 0 (no associated companies).

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).

Profit & Loss Data Fields

The accepted profitLossData fields are:

turnover: Total turnover/revenue
costOfRawMaterials: Cost of raw materials, purchases, cost of sales
staffCosts: Staff costs / employee costs
depreciation: Depreciation and other amounts written off assets
otherCharges: Administrative expenses, other charges
interestIncome: Interest receivable and similar income
capitalAllowances: Capital allowances (AIA) - tax adjustment to reduce taxable profit
lossesBroughtForward: Trading losses brought forward from prior periods
disallowableExpenses: Disallowable expenses (add back to trading profit for tax)
propertyBusinessIncome: Income from property business activities (CT600 Box 190)
grossChargeableGains: Gross chargeable gains from capital disposals (CT600 Box 210)
allowableLosses: Allowable capital losses to set against gains (CT600 Box 215)
qualifyingDonations: Qualifying charitable donations deductible from profits (CT600 Box 305). Capped at available profits before donations.

Aliases: costOfSales is accepted as an alias for costOfRawMaterials, and administrativeExpenses is accepted as an alias for otherCharges.

json

{
  "turnover": 150000,
  "costOfRawMaterials": 45000,
  "staffCosts": 8000,
  "depreciation": 3000,
  "otherCharges": 20000,
  "capitalAllowances": 5000,
  "interestIncome": 500,
  "propertyBusinessIncome": 8000,
  "grossChargeableGains": 15000,
  "allowableLosses": 3000,
  "qualifyingDonations": 2000
  // 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. The system automatically sets numberOfEmployees and associatedCompanies to 0 for dormant filings.
Trading: set isDormant: false. Must provide comprehensive profitLossData and balanceSheetData. The accountType should ideally be set to "micro-entity" or "small-company".

Filing Types Selection

Before submitting, you must set the filingTypes field on the filing via /v1/filing/save to specify which submissions to make.

For both HMRC CT600 and Companies House accounts: { "ct600": true, "accounts": true }
For HMRC CT600 only: { "ct600": true }
For Companies House accounts only: { "accounts": true }

Note: The target parameter in /v1/filing/submit controls which submissions to actually trigger, but the filing must have the corresponding filingTypes enabled. For example, submitting with target: "ch" requires filingTypes.accounts to be true.

json

{
  "filingTypes": {
    "ct600": true,
    "accounts": true
  }
}

Comparative Period Data

To include previous year comparatives in the Companies House accounts, provide previousProfitLossData and previousBalanceSheetData via /v1/filing/save.

These follow the same schema as profitLossData and balanceSheetData respectively. The system automatically calculates the previous period dates from the current filing's period start date.

Custom Notes

Users can add optional custom textual notes to their financial statements via the notesData field on /v1/filing/save. These notes appear after the three statutory notes (Accounting Policies, Basis of Preparation, Employee Information) in both the iXBRL accounts document and the PDF.

Structure: Array of objects with title (string, max 200 characters) and body (string, max 5000 characters, supports newlines for multi-paragraph notes).
Limit: Maximum 20 notes per filing.
Numbering: Notes are numbered starting from 4 in the generated documents.
Common titles: Going Concern, Related Party Transactions, Post Balance Sheet Events, Dividends.
Optional: Omit the field or set to null/empty array to exclude them.

json

{
  "notesData": [
    {
      "title": "Going Concern",
      "body": "The directors have considered the company's financial position and are satisfied that the company has adequate resources to continue in operational existence for the foreseeable future. Accordingly, the financial statements have been prepared on a going concern basis."
    },
    {
      "title": "Related Party Transactions",
      "body": "During the year the company entered into the following transactions with related parties:\n\nDirector's loan account balance at the period end was £5,000."
    }
  ]
}

Tangible Fixed Assets

The fixedAssetMovements object is an optional nested field inside balanceSheetData for Full Accounts (accountType: "full") with tangible fixed assets.

Structure: It contains two fields: categories (array) and depreciationPolicy (optional string).
Categories: Each category object has: name (string - one of "Plant & Machinery", "Motor Vehicles", "Office Equipment", "Fixtures & Fittings", "Computer Equipment", "Leasehold Improvements"), costBroughtForward (number), additions (number), disposals (number), depreciationBroughtForward (number), depreciationCharge (number), depreciationOnDisposals (number).
Calculations: The system automatically calculates Cost c/f, Dep c/f, and NBV from these inputs.
Depreciation Policy: The depreciationPolicy string appears under Accounting Policies (Note 1) in the financial statements. If omitted, a default policy text is used.
Notes Sequencing: The fixed assets note appears as Note 4 in the generated documents (after Employee Information). If custom notes are also present, they are renumbered starting from Note 5.
Condition: Only applies when accountType is "full" (i.e. "small-company" mapped to full internally) and tangibleAssets > 0 in balanceSheetData.

json

{
  "balanceSheetData": {
    "tangibleAssets": 15000,
    "fixedAssetMovements": {
      "depreciationPolicy": "Tangible fixed assets are stated at cost less depreciation. Depreciation is provided at rates calculated to write off the cost of fixed assets, less their estimated residual value, over their expected useful lives.",
      "categories": [
        {
          "name": "Plant & Machinery",
          "costBroughtForward": 10000,
          "additions": 5000,
          "disposals": 0,
          "depreciationBroughtForward": 2000,
          "depreciationCharge": 1500,
          "depreciationOnDisposals": 0
        },
        {
          "name": "Office Equipment",
          "costBroughtForward": 3000,
          "additions": 2000,
          "disposals": 500,
          "depreciationBroughtForward": 500,
          "depreciationCharge": 500,
          "depreciationOnDisposals": 200
        }
      ]
    }
  }
}

Creditors & Debtors Breakdown

The debtorsBreakdown, creditorsWithinOneYearBreakdown, and creditorsAfterOneYearBreakdown are optional nested objects inside balanceSheetData. They only apply for Full Accounts (accountType: "full" or "small-company") when the respective aggregate is > 0.

debtorsBreakdown: tradeDebtors (number), prepayments (number), otherDebtors (number)
creditorsWithinOneYearBreakdown: tradeCreditors (number), corporationTax (number), otherTaxesAndSocialSecurity (number), accrualsAndDeferredIncome (number), otherCreditors (number)
creditorsAfterOneYearBreakdown: bankLoans (number), otherCreditors (number)
Validation: The sum of the sub-items must exactly equal the parent aggregate.
Notes Sequencing: The debtors note appears after Fixed Assets (if present), and the creditors note after debtors. Custom notes are renumbered accordingly.
Optional: Omit to file with aggregate-only figures (default behavior).

json

{
  "balanceSheetData": {
    "debtors": 12000,
    "creditorsWithinOneYear": 25000,
    "creditorsAfterOneYear": 50000,
    "debtorsBreakdown": {
      "tradeDebtors": 8000,
      "prepayments": 3000,
      "otherDebtors": 1000
    },
    "creditorsWithinOneYearBreakdown": {
      "tradeCreditors": 10000,
      "corporationTax": 5000,
      "otherTaxesAndSocialSecurity": 3000,
      "accrualsAndDeferredIncome": 4000,
      "otherCreditors": 3000
    },
    "creditorsAfterOneYearBreakdown": {
      "bankLoans": 40000,
      "otherCreditors": 10000
    }
  }
}

Board Approval Date

The boardApprovalDate field in credentialsData is the date directors signed off/approved the accounts for issue.

Format: DD/MM/YYYY (e.g. "15/06/2024")
It is optional — if omitted, the period end date is used as the default.
This date appears on the statutory compliance page in both iXBRL and PDF documents as "These accounts were approved by the Board on [date]" and as the "DateAuthorisationFinancialStatementsForIssue" iXBRL fact.
It is also used as the declaration date on CT600 page 12.

json

{
  "credentialsData": {
    "boardApprovalDate": "15/06/2024"
  }
}

Agent Filing Mode

WeFile supports filing CT600 returns as an agent on behalf of client companies. When an agent files, the HMRC XML submission uses the agent's credentials and includes an Agent block in the IRheader, as required by the HMRC GovTalk specification.

Set filingMode to "agent" in credentialsData to enable agent mode.
gatewayId and gatewayPassword become the agent's Government Gateway credentials.
utrNumber still refers to the client company's Unique Taxpayer Reference.
agentReferenceId (required): The agent's HMRC reference code (e.g. 6-character alphanumeric code).
agentCompanyName (optional): The agent's firm or company name.
declarantName (required): Full name of the person at the agent firm making the declaration.
declarantStatus (required): Role of the declarant, e.g. "Tax Advisor", "Agent", "Accountant".
directorName is still required in agent mode as it appears in the iXBRL accounts.

When filingMode is omitted or set to "principal" (default), the filing uses the company's own Government Gateway credentials and the standard Company/Director XML structure. This is fully backward compatible — existing integrations require no changes.

json

{
  "credentialsData": {
    "utrNumber": "1234567890",
    "gatewayId": "AGENT_GW_ID",
    "gatewayPassword": "agent_password",
    "authCode": "222222",
    "directorName": "Client Director Name",
    "filingMode": "agent",
    "agentReferenceId": "A12345",
    "agentCompanyName": "Smith & Partners Accountants",
    "declarantName": "Jane Agent",
    "declarantStatus": "Tax Advisor"
  }
}

Submissions

List Submissions

GET/filing/submissions

Gets historical submissions (HMRC / CH) for a filing without triggering an inline poll. Includes both successful submissions and validation errors (e.g. missing auth code). Validation failures appear with status: "error" and include the error message.

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"

Generate Document

GET/filing/document/generate

Generates a filing document on-the-fly from saved filing data. Returns the document as a base64 string (for PDFs) or raw HTML (for iXBRL). This is the recommended way to retrieve documents for archiving — it does not depend on prior server-side storage.

Query Parameter	Type	Description
`filingId`	number	WeFile filing ID
`type`	string	One of: `accounts_ixbrl`, `accounts_pdf`, `tax_computation_ixbrl`, `tax_computation_pdf`, `ct600_pdf`

Response Field	Type	Description
`fileName`	string	Suggested filename (e.g. "Company - CT600 (2024-01-01 to 2024-12-31).pdf")
`mimeType`	string	MIME type (`application/pdf` or `text/html`)
`fileData`	string	Base64-encoded PDF bytes or raw iXBRL HTML string

bash

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

NoteFor PDFs, decode the base64 fileData to get the raw bytes. For iXBRL documents, fileData is the HTML string directly.

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
  "fixedAssetMovements": {
    "depreciationPolicy": "...",
    "categories": [
      {
        "name": "Plant & Machinery",
        "costBroughtForward": 0,
        "additions": 0,
        "disposals": 0,
        "depreciationBroughtForward": 0,
        "depreciationCharge": 0,
        "depreciationOnDisposals": 0
      }
    ]
  },
  "debtorsBreakdown": { // Optional: Detailed debtors breakdown for Full Accounts. Sum must equal debtors.
    "tradeDebtors": 0,
    "prepayments": 0,
    "otherDebtors": 0
  },
  "creditorsWithinOneYearBreakdown": { // Optional: Detailed creditors breakdown for Full Accounts. Sum must equal creditors.
    "tradeCreditors": 0,
    "corporationTax": 0,
    "otherTaxesAndSocialSecurity": 0,
    "accrualsAndDeferredIncome": 0,
    "otherCreditors": 0
  },
  "creditorsAfterOneYearBreakdown": { // Optional: Detailed creditors breakdown for Full Accounts. Sum must equal creditorsAfterOneYear.
    "bankLoans": 0,
    "otherCreditors": 0
  }
}

The fixedAssetMovements object is optional and only relevant for Full Accounts with tangible fixed assets. See the Important Notes section for details.

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",
  "boardApprovalDate": "15/06/2024",
  "filingMode": "principal",
  "agentReferenceId": "A12345",
  "agentCompanyName": "Smith & Partners",
  "declarantName": "Jane Agent",
  "declarantStatus": "Tax Advisor"
}

The boardApprovalDate field is optional. It represents the date the board of directors approved the accounts (format: DD/MM/YYYY). If omitted, it defaults to the period end date. This date appears on the compliance page in both iXBRL accounts and PDF documents.

When filing as an agent on behalf of a client, set filingMode to "agent". In agent mode, gatewayId and gatewayPassword should be the agent's Government Gateway credentials (not the client company's). The utrNumber always refers to the client company's UTR. The agentReferenceId, declarantName, and declarantStatus fields are required in agent mode. agentCompanyName is optional. When filingMode is omitted or set to "principal" (default), the system behaves as before — credentials are treated as the company's own Government Gateway account.

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`.

Set Filing Types

POST to `/v1/filing/save` with `filingTypes` to select CT600, Accounts, or both.

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/generate` to produce PDFs and iXBRL on demand. Alternatively, use `/v1/filing/document/list` and `/v1/filing/document/download` for stored documents.

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

pendingsubmittedpollingacceptedrejectederrorpreviously_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",
    "filingTypes": {
      "ct600": true,
      "accounts": true
    },
    "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,
    "associatedCompanies": 1,
    "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,
    "accountType": "small-company",
    "profitLossData": {
      "turnover": 150000,
            "costOfRawMaterials": 45000,
      "otherCharges": 20000,
      "disallowableExpenses": 1200,
      "interestIncome": 500,
      "propertyBusinessIncome": 8000,
      "grossChargeableGains": 15000,
      "allowableLosses": 3000,
      "qualifyingDonations": 2000
    }
  }'

# 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,
      "debtorsBreakdown": {
        "tradeDebtors": 8000,
        "prepayments": 3000,
        "otherDebtors": 1000
      },
      "creditorsWithinOneYearBreakdown": {
        "tradeCreditors": 10000,
        "corporationTax": 5000,
        "otherTaxesAndSocialSecurity": 3000,
        "accrualsAndDeferredIncome": 4000,
        "otherCreditors": 3000
      },
      "fixedAssetMovements": {
        "depreciationPolicy": "20% reducing balance",
        "categories": [
          {
            "name": "Plant & Machinery",
            "costBroughtForward": 10000,
            "additions": 5000,
            "disposals": 0,
            "depreciationBroughtForward": 2000,
            "depreciationCharge": 1500,
            "depreciationOnDisposals": 0
          },
          {
            "name": "Office Equipment",
            "costBroughtForward": 3000,
            "additions": 2000,
            "disposals": 500,
            "depreciationBroughtForward": 500,
            "depreciationCharge": 500,
            "depreciationOnDisposals": 200
          }
        ]
      }
    }
  }'

# 5.5. Save Custom Notes (Optional)
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,
    "notesData": [
      {
        "title": "Going Concern",
        "body": "The directors have considered the company financial position and are satisfied that the company has adequate resources to continue in operational existence for the foreseeable future."
      }
    ]
  }'

# 7. 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",
    "filingTypes": {
      "ct600": true,
      "accounts": true
    },
    "credentialsData": {
      "utrNumber": "0987654321",
      "gatewayId": "user456",
      "gatewayPassword": "password456",
      "authCode": "333333",
      "boardApprovalDate": "15/06/2024"
    }
  }'

# 8. 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"
  }'

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

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

3. Amendment Filing

This example demonstrates the workflow for filing an amendment to an existing submission. It creates a filing with isAmendment: true and references the original filing via amendmentOfFilingId, then follows the standard process to update data, lock the filing, and submit.

bash

# 1. Create Amendment Filing
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,
    "isAmendment": true,
    "amendmentOfFilingId": 124
  }'

# 2. Save Updated 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": 125,
    "profitLossData": {
      "turnover": 160000,
            "costOfRawMaterials": 45000,
      "otherCharges": 20000,
      "disallowableExpenses": 800,
      "interestIncome": 500
    }
  }'

# 3. 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": 125,
    "status": "in_progress",
    "filingTypes": {
      "ct600": true,
      "accounts": true
    },
    "credentialsData": {
      "utrNumber": "0987654321",
      "gatewayId": "user456",
      "gatewayPassword": "password456",
      "authCode": "333333",
      "boardApprovalDate": "15/06/2024"
    }
  }'

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

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

4. Direct Amendment Filing

This example demonstrates filing an amendment when the original return was filed through another provider. It creates a direct amendment (isAmendment: true without amendmentOfFilingId), then follows the standard save → lock → submit workflow.

bash

# 1. Create Direct Amendment Filing
curl -X POST https://api.wefile.co.uk/v1/filing/create \
  -H "X-API-Key: YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "companyId": 4,
    "periodStart": "2023-01-01",
    "periodEnd": "2023-12-31",
    "isDormant": false,
    "isAmendment": true,
    "associatedCompanies": 2
  }'

# 2. 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": 126,
    "profitLossData": {
      "turnover": 160000,
      "costOfRawMaterials": 45000,
      "otherCharges": 20000
    }
  }'

# 3. 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": 126,
    "balanceSheetData": {
      "cashAtBank": 95000,
      "calledUpShareCapital": 100
    }
  }'

# 4. 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": 126,
    "status": "in_progress",
    "filingTypes": {
      "ct600": true,
      "accounts": true
    },
    "credentialsData": {
      "utrNumber": "0987654321",
      "gatewayId": "user456",
      "gatewayPassword": "password456",
      "authCode": "333333"
    }
  }'

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

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

5. Agent Filing

This example demonstrates filing a CT600 as an agent on behalf of a client company. The agent uses their own Government Gateway credentials, and the submission includes the agent's HMRC reference in the XML. The client company's UTR and director name are still required.

bash

# 1. Add Company (Client's 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":"11223344"}'

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

# 3. Create Filing
curl -X POST https://api.wefile.co.uk/v1/filing/create \
  -H "X-API-Key: YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "companyId": 5,
    "periodStart": "2024-04-01",
    "periodEnd": "2025-03-31",
    "isDormant": true,
    "directorName": "Client Director"
  }'

# 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": 127,
    "balanceSheetData": {
      "cashAtBank": 100,
      "calledUpShareCapital": 100
    }
  }'

# 5. Save Credentials (Agent Mode) & 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": 127,
    "status": "in_progress",
    "filingTypes": {
      "ct600": true,
      "accounts": true
    },
    "credentialsData": {
      "utrNumber": "1234567890",
      "gatewayId": "AGENT_GW_ID",
      "gatewayPassword": "agent_password",
      "authCode": "222222",
      "directorName": "Client Director",
      "filingMode": "agent",
      "agentReferenceId": "A12345",
      "agentCompanyName": "Smith & Partners",
      "declarantName": "Jane Agent",
      "declarantStatus": "Tax Advisor"
    }
  }'

# 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": 127,
    "target": "both"
  }'

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