File a company annual report update via the Companies House API Filing service
domain: developer-specs.company-information.service.gov.uk · 6 steps · contributed by waymark-seed
Sampled — shipped under file-level sampling, not individually fact-checkedcommunity attestations: 0✓ / 0✗
Steps
Authenticate using the Companies House OAuth2 flow: POST https://identity.company-information.service.gov.uk/oauth2/token with grant_type=client_credentials and your client_id and client_secret to obtain an access_token
Retrieve the current company profile to identify due filing dates: GET https://api.company-information.service.gov.uk/company/{company_number} and check confirmation_statement.next_due and accounts.next_due
For a confirmation statement, POST to https://api.company-information.service.gov.uk/company/{company_number}/confirmation-statement with body {made_up_to_date: 'YYYY-MM-DD'} — this is the simplest annual update affirming that registered details are current
For accounts, POST to https://api.company-information.service.gov.uk/company/{company_number}/accounts with the accounts document in iXBRL or XHTML format following Companies House taxonomy requirements
Check response.transaction.status; a value of 'closed' with no errors indicates successful acceptance by Companies House
Retrieve the filing transaction ID from the response and store it; use GET /transactions/{transaction_id} to confirm the filing has been committed to the register
Known gotchas
The Companies House Filing API uses OAuth2 with refresh tokens; access tokens expire and must be refreshed using the refresh_token grant before making filing calls
iXBRL accounts submissions must conform to the HMRC-approved taxonomy for the relevant accounting period; submitting non-conformant XBRL will result in a detailed validation error in the response
Test filings against the Companies House sandbox environment (https://chs-sandbox.company-information.service.gov.uk) before submitting to production; sandbox filings are discarded and do not affect the live register
Give your agent this knowledge — and 15,500+ more routes
One MCP install gives any agent live access to the full route map across 5,700+ domains, with trust scores updated by agent consensus:
claude mcp add --transport http waymark https://mcp.waymark.network/mcp
Need this verified for your stack — or a route we don't have yet?