MCP API

Developers

Server

Server name diya-submit, version 0.1.1.

The hosted endpoint speaks streamable HTTP and signs in with OAuth:

https://submit.diyaccounting.co.uk/mcp

The same tools run locally over stdio from the npm package @diy-accounting-uk/diya-submit or the image ghcr.io/diy-accounting-uk/diya-submit-mcp. The hosted production endpoint registers the tools tagged below; other environments register more.

Tools (40)

add_client

Adds one client to the practice's list, over the deployed API. Every identifier is optional, but a given one must match its HMRC or Companies House format.

ParameterTypeRequiredMeaning
displayNamestringyesThe client's name as the practice knows them, 1 to 200 characters
vrnstringnoVAT registration number, 9 digits
ninostringnoNational Insurance number
utrstringnoUnique Taxpayer Reference, 10 digits
companyNumberstringnoCompanies House company number, 8 characters
Input schema (JSON Schema) 
{
  "type": "object",
  "properties": {
    "displayName": {
      "type": "string",
      "description": "The client's name as the practice knows them, 1 to 200 characters"
    },
    "vrn": {
      "description": "VAT registration number, 9 digits",
      "type": "string"
    },
    "nino": {
      "description": "National Insurance number",
      "type": "string"
    },
    "utr": {
      "description": "Unique Taxpayer Reference, 10 digits",
      "type": "string"
    },
    "companyNumber": {
      "description": "Companies House company number, 8 characters",
      "type": "string"
    }
  },
  "required": [
    "displayName"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}
client_authorisation_status

One client's current authorisation status for one HMRC service, over the deployed API: re-reads a pending invitation's own status, or HMRC's relationships endpoint when none is pending. Uses the session's HMRC authorisation: call request_hmrc_authorisation with services agent first if this tool says none is held.

ParameterTypeRequiredMeaning
clientIdstringyesThe client's id
service"MTD-VAT" | "MTD-IT"yesThe HMRC service to check
Input schema (JSON Schema) 
{
  "type": "object",
  "properties": {
    "clientId": {
      "type": "string",
      "description": "The client's id"
    },
    "service": {
      "type": "string",
      "enum": [
        "MTD-VAT",
        "MTD-IT"
      ],
      "description": "The HMRC service to check"
    }
  },
  "required": [
    "clientId",
    "service"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}
derive_company_tax_return

The figures the Company Tax Return form takes, from the session's loaded Company book: the accounting period, the computation figures (depreciation, amortisation, entertaining, capital allowances, franked investment income, losses brought forward), the profit and loss account from the engine's published statements, and the book's own trading profit and Corporation Tax as a working sheet for a check. Refuses a book that is not a Company book, makes a trading loss or carries net non-trading loan relationship debits. With a path, also writes the answer as the JSON file the Company Tax Return page's "Fill from your books" card reads.

ParameterTypeRequiredMeaning
pathstringnoWhere to write the answer as JSON for the Company Tax Return page's import
Input schema (JSON Schema) 
{
  "type": "object",
  "properties": {
    "path": {
      "description": "Where to write the answer as JSON for the Company Tax Return page's import",
      "type": "string"
    }
  },
  "$schema": "http://json-schema.org/draft-07/schema#"
}
derive_itsa_annual_submission

The year's allowances and adjustments for HMRC's Self Employment Business API annual submission from the loaded self-employed book, restricted to the fields HMRC accepts for that tax year. With a path, also writes the answer as the JSON file hmrc/itsa/annualSubmission.html imports.

ParameterTypeRequiredMeaning
taxYearstringnoOverride the tax year the book's dates imply, as 2025-26
pathstringnoWhere to write the answer as JSON for the annual submission page's import
Input schema (JSON Schema) 
{
  "type": "object",
  "properties": {
    "taxYear": {
      "description": "Override the tax year the book's dates imply, as 2025-26",
      "type": "string"
    },
    "path": {
      "description": "Where to write the answer as JSON for the annual submission page's import",
      "type": "string"
    }
  },
  "$schema": "http://json-schema.org/draft-07/schema#"
}
derive_itsa_quarterly_update

One period of HMRC's Self Employment Business API from the loaded self-employed book: the period's own figures in a tax year filed as dated period summaries, a running total from 6 April in a year filed as cumulative period summaries (2025-26 on). Picks the period by periodEndDate among the year's four (standard quarters by default); with no periodEndDate answers every period. A field the book cannot source is omitted, never sent as zero.

ParameterTypeRequiredMeaning
periodEndDatestringnoThe period's end date, YYYY-MM-DD, as HMRC's obligation names it
quarterlyPeriodType"standard" | "calendar"nostandard (6 April quarters, the default) or calendar
taxYearstringnoOverride the tax year the book's dates imply, as 2025-26
Input schema (JSON Schema) 
{
  "type": "object",
  "properties": {
    "periodEndDate": {
      "description": "The period's end date, YYYY-MM-DD, as HMRC's obligation names it",
      "type": "string"
    },
    "quarterlyPeriodType": {
      "description": "standard (6 April quarters, the default) or calendar",
      "type": "string",
      "enum": [
        "standard",
        "calendar"
      ]
    },
    "taxYear": {
      "description": "Override the tax year the book's dates imply, as 2025-26",
      "type": "string"
    }
  },
  "$schema": "http://json-schema.org/draft-07/schema#"
}
derive_micro_entity_accounts

The seven FRS 105 balance-sheet lines the accounts filing takes, from the session's loaded book: the current year from the engine's published balance sheet and the prior year from the book's opening balance, in whole pounds with capital and reserves equal to net assets, plus the period dates, the company number and name, the first director and the employee count. Refuses a book whose published or opening balance sheet does not balance.

No parameters.

Input schema (JSON Schema) 
{
  "type": "object",
  "properties": {},
  "$schema": "http://json-schema.org/draft-07/schema#"
}
derive_small_company_accounts

The figures a small company's FRS 102 section 1A accounts filing takes, from the session's loaded book: the full profit and loss account and the balance sheet sub-lines for the current year from the engine's published statements, the prior-year balance sheet from the opening balance, the tangible fixed asset note by class, the period dates, the company number and name, the directors and the employee count, in whole pounds with every subtotal holding. The book publishes no prior-year profit and loss account, so none is returned. Refuses a book whose published or opening balance sheet does not balance.

No parameters.

Input schema (JSON Schema) 
{
  "type": "object",
  "properties": {},
  "$schema": "http://json-schema.org/draft-07/schema#"
}
derive_uk_property_annual

The year's adjustments and allowances for HMRC's UK property annual submission from the loaded landlord book whose chart names the property accounts. The elections and the landlord facts are left to the annual submission page and named in leftToPage.

ParameterTypeRequiredMeaning
taxYearstringyesThe tax year, as 2025-26
Input schema (JSON Schema) 
{
  "type": "object",
  "properties": {
    "taxYear": {
      "type": "string",
      "description": "The tax year, as 2025-26"
    }
  },
  "required": [
    "taxYear"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}
derive_uk_property_period

One period of HMRC's UK property income and expenses from the loaded landlord book whose chart names the property accounts: the period's own figures, both ends inclusive; a cumulative year's running total is the same call with the period starting on 6 April. Answers the income, the expenses, the slots the book did not fill and the postings behind each figure. Refuses a period carrying both consolidated and itemised expenses.

ParameterTypeRequiredMeaning
periodStartDatestringyesThe period's first day, YYYY-MM-DD
periodEndDatestringyesThe period's last day, YYYY-MM-DD
Input schema (JSON Schema) 
{
  "type": "object",
  "properties": {
    "periodStartDate": {
      "type": "string",
      "description": "The period's first day, YYYY-MM-DD"
    },
    "periodEndDate": {
      "type": "string",
      "description": "The period's last day, YYYY-MM-DD"
    }
  },
  "required": [
    "periodStartDate",
    "periodEndDate"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}
derive_vat_return hosted, production

The nine VAT boxes for one obligation period from the session's loaded book, read from the engine's own VAT interface: the quarter ending on periodEnd (a month end the book carries), with HMRC's field names and rounding, the three months' figures, and every sales and purchases journal line that fed boxes 1, 4, 6 and 7. Refuses a book that is not VAT registered, a period the book does not carry, and a period whose lines do not reconcile with the interface.

ParameterTypeRequiredMeaning
periodEndstringyesThe obligation's period end, YYYY-MM-DD; must be a month end the book's VAT interface carries
periodStartstringnoThe obligation's period start, YYYY-MM-DD; refused unless it opens the quarter ending periodEnd
periodKeystringnoThe obligation's period key, echoed back for the submit call
Input schema (JSON Schema) 
{
  "type": "object",
  "properties": {
    "periodEnd": {
      "type": "string",
      "description": "The obligation's period end, YYYY-MM-DD; must be a month end the book's VAT interface carries"
    },
    "periodStart": {
      "description": "The obligation's period start, YYYY-MM-DD; refused unless it opens the quarter ending periodEnd",
      "type": "string"
    },
    "periodKey": {
      "description": "The obligation's period key, echoed back for the submit call",
      "type": "string"
    }
  },
  "required": [
    "periodEnd"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}
get_confirmation_statement_data_sandbox

The register data a confirmation statement form is built from -- MadeUpDate, NextDueDate, SIC codes, RegisteredEmailAddress, officers, PSCs, StatementOfCapital, Shareholdings, TradingOnMarket, DTR5Applies, the PSC exemption flags, and whether the payment period is paid -- over the deployed API. The company authentication code is not an argument: the user types it on the link request_companies_house_codes (kind confirmation-statement-data) answers, and this call names that entry by codesEntryId, which it uses up.

ParameterTypeRequiredMeaning
companyNumberstringyesThe 8-character Companies House company number
codesEntryIdstringyesThe entryId request_companies_house_codes answered, once the user has typed the codes on its link
madeUpDatestringyesThe confirmation statement's made-up date, YYYY-MM-DD
companyTypestringnoThe company type, when the gateway needs it to resolve the request
Input schema (JSON Schema) 
{
  "type": "object",
  "properties": {
    "companyNumber": {
      "type": "string",
      "description": "The 8-character Companies House company number"
    },
    "codesEntryId": {
      "type": "string",
      "description": "The entryId request_companies_house_codes answered, once the user has typed the codes on its link"
    },
    "madeUpDate": {
      "type": "string",
      "description": "The confirmation statement's made-up date, YYYY-MM-DD"
    },
    "companyType": {
      "description": "The company type, when the gateway needs it to resolve the request",
      "type": "string"
    }
  },
  "required": [
    "companyNumber",
    "codesEntryId",
    "madeUpDate"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}
get_vat_receipt hosted, production

A stored HMRC VAT receipt by its file name, over the deployed API: Submit's own copy of what it filed. To read HMRC's copy of a return by period key, use get_vat_return. clientId, when given, narrows the fetch to one of the practice's clients but does not change which receipt is read.

ParameterTypeRequiredMeaning
namestringyesThe receipt file name, including .json (submit_vat_return answers receiptId without the suffix)
clientIdstringnoA practice client's id, to check the receipt belongs to that client
Input schema (JSON Schema) 
{
  "type": "object",
  "properties": {
    "name": {
      "type": "string",
      "description": "The receipt file name, including .json (submit_vat_return answers receiptId without the suffix)"
    },
    "clientId": {
      "description": "A practice client's id, to check the receipt belongs to that client",
      "type": "string"
    }
  },
  "required": [
    "name"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}
get_vat_return hosted, production

One past VAT return as HMRC holds it, by its period key (the periodKey list_vat_obligations answers for a fulfilled obligation), over the deployed API. Use it to see what HMRC holds; to read Submit's stored copy of a return it filed, use get_vat_receipt. Uses the session's HMRC authorisation: call request_hmrc_authorisation first if this tool says none is held.

ParameterTypeRequiredMeaning
vrnstringyesVAT registration number, 9 digits
periodKeystringyesThe obligation's period key, for example 18A1
hmrcAccount"synthetic" | "live"noWhich HMRC environment to call; defaults to the session's HMRC authorisation's own
govTestScenariostringnoHMRC sandbox test scenario
Input schema (JSON Schema) 
{
  "type": "object",
  "properties": {
    "vrn": {
      "type": "string",
      "description": "VAT registration number, 9 digits"
    },
    "periodKey": {
      "type": "string",
      "description": "The obligation's period key, for example 18A1"
    },
    "hmrcAccount": {
      "description": "Which HMRC environment to call; defaults to the session's HMRC authorisation's own",
      "type": "string",
      "enum": [
        "synthetic",
        "live"
      ]
    },
    "govTestScenario": {
      "description": "HMRC sandbox test scenario",
      "type": "string"
    }
  },
  "required": [
    "vrn",
    "periodKey"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}
invite_client

Sends an HMRC Agent Authorisation invitation for one client and one service, over the deployed API. The client's own VRN or NINO comes from the client row, not from this call. Uses the session's HMRC authorisation: call request_hmrc_authorisation with services agent first if this tool says none is held.

ParameterTypeRequiredMeaning
clientIdstringyesThe client's id
service"MTD-VAT" | "MTD-IT"yesThe HMRC service to request authorisation for
knownFactstringyesThe VAT registration date (MTD-VAT) or the client's postcode (MTD-IT)
arnstringnoThe practice's HMRC agent reference number; stored for reuse when given, read back when omitted
Input schema (JSON Schema) 
{
  "type": "object",
  "properties": {
    "clientId": {
      "type": "string",
      "description": "The client's id"
    },
    "service": {
      "type": "string",
      "enum": [
        "MTD-VAT",
        "MTD-IT"
      ],
      "description": "The HMRC service to request authorisation for"
    },
    "knownFact": {
      "type": "string",
      "description": "The VAT registration date (MTD-VAT) or the client's postcode (MTD-IT)"
    },
    "arn": {
      "description": "The practice's HMRC agent reference number; stored for reuse when given, read back when omitted",
      "type": "string"
    }
  },
  "required": [
    "clientId",
    "service",
    "knownFact"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}
list_books hosted, production

List the books saved in the DIYA cloud, most recently updated first, signed in as the session's credentials. Each row carries the bookId open_book takes. With clientId, lists that practice client's books instead of the practice's own.

ParameterTypeRequiredMeaning
clientIdstringnoA practice client's id, to list that client's books instead of the practice's own
Input schema (JSON Schema) 
{
  "type": "object",
  "properties": {
    "clientId": {
      "description": "A practice client's id, to list that client's books instead of the practice's own",
      "type": "string"
    }
  },
  "$schema": "http://json-schema.org/draft-07/schema#"
}
list_clients

The signed-in practice's own client list over the deployed API: each client's id, display name, identifiers (VRN, NINO, UTR, company number) and current HMRC authorisation state per service. Archived clients are excluded.

No parameters.

Input schema (JSON Schema) 
{
  "type": "object",
  "properties": {},
  "$schema": "http://json-schema.org/draft-07/schema#"
}
list_vat_liabilities hosted, production

What HMRC says the business owes for VAT, by period, for one VRN over the deployed API. Uses the session's HMRC authorisation: call request_hmrc_authorisation first if this tool says none is held.

ParameterTypeRequiredMeaning
vrnstringyesVAT registration number, 9 digits
fromstringnoFrom date, YYYY-MM-DD; HMRC's default range when omitted
tostringnoTo date, YYYY-MM-DD; HMRC's default range when omitted
hmrcAccount"synthetic" | "live"noWhich HMRC environment to call; defaults to the session's HMRC authorisation's own
govTestScenariostringnoHMRC sandbox test scenario
Input schema (JSON Schema) 
{
  "type": "object",
  "properties": {
    "vrn": {
      "type": "string",
      "description": "VAT registration number, 9 digits"
    },
    "from": {
      "description": "From date, YYYY-MM-DD; HMRC's default range when omitted",
      "type": "string"
    },
    "to": {
      "description": "To date, YYYY-MM-DD; HMRC's default range when omitted",
      "type": "string"
    },
    "hmrcAccount": {
      "description": "Which HMRC environment to call; defaults to the session's HMRC authorisation's own",
      "type": "string",
      "enum": [
        "synthetic",
        "live"
      ]
    },
    "govTestScenario": {
      "description": "HMRC sandbox test scenario",
      "type": "string"
    }
  },
  "required": [
    "vrn"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}
list_vat_obligations hosted, production

The open and fulfilled VAT obligations HMRC holds for one VRN, or for one practice client's VRN when clientId is given instead of vrn, over the deployed API. Uses the session's HMRC authorisation: call request_hmrc_authorisation first if this tool says none is held.

ParameterTypeRequiredMeaning
vrnstringnoVAT registration number, 9 digits; required unless clientId is given
clientIdstringnoA practice client's id, to resolve vrn from the client row instead
fromstringnoFrom date, YYYY-MM-DD; defaults to the start of the current calendar year
tostringnoTo date, YYYY-MM-DD; defaults to today
status"O" | "F"noO (Open) or F (Fulfilled); both when omitted
hmrcAccount"synthetic" | "live"noWhich HMRC environment to call; defaults to the session's HMRC authorisation's own
govTestScenariostringnoHMRC sandbox test scenario
Input schema (JSON Schema) 
{
  "type": "object",
  "properties": {
    "vrn": {
      "description": "VAT registration number, 9 digits; required unless clientId is given",
      "type": "string"
    },
    "clientId": {
      "description": "A practice client's id, to resolve vrn from the client row instead",
      "type": "string"
    },
    "from": {
      "description": "From date, YYYY-MM-DD; defaults to the start of the current calendar year",
      "type": "string"
    },
    "to": {
      "description": "To date, YYYY-MM-DD; defaults to today",
      "type": "string"
    },
    "status": {
      "description": "O (Open) or F (Fulfilled); both when omitted",
      "type": "string",
      "enum": [
        "O",
        "F"
      ]
    },
    "hmrcAccount": {
      "description": "Which HMRC environment to call; defaults to the session's HMRC authorisation's own",
      "type": "string",
      "enum": [
        "synthetic",
        "live"
      ]
    },
    "govTestScenario": {
      "description": "HMRC sandbox test scenario",
      "type": "string"
    }
  },
  "$schema": "http://json-schema.org/draft-07/schema#"
}
list_vat_payments hosted, production

The VAT payments HMRC has received from the business, by date, for one VRN over the deployed API. Uses the session's HMRC authorisation: call request_hmrc_authorisation first if this tool says none is held.

ParameterTypeRequiredMeaning
vrnstringyesVAT registration number, 9 digits
fromstringnoFrom date, YYYY-MM-DD; HMRC's default range when omitted
tostringnoTo date, YYYY-MM-DD; HMRC's default range when omitted
hmrcAccount"synthetic" | "live"noWhich HMRC environment to call; defaults to the session's HMRC authorisation's own
govTestScenariostringnoHMRC sandbox test scenario
Input schema (JSON Schema) 
{
  "type": "object",
  "properties": {
    "vrn": {
      "type": "string",
      "description": "VAT registration number, 9 digits"
    },
    "from": {
      "description": "From date, YYYY-MM-DD; HMRC's default range when omitted",
      "type": "string"
    },
    "to": {
      "description": "To date, YYYY-MM-DD; HMRC's default range when omitted",
      "type": "string"
    },
    "hmrcAccount": {
      "description": "Which HMRC environment to call; defaults to the session's HMRC authorisation's own",
      "type": "string",
      "enum": [
        "synthetic",
        "live"
      ]
    },
    "govTestScenario": {
      "description": "HMRC sandbox test scenario",
      "type": "string"
    }
  },
  "required": [
    "vrn"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}
list_vat_penalties hosted, production

The VAT penalties and late-submission points HMRC holds for one VRN over the deployed API. Uses the session's HMRC authorisation: call request_hmrc_authorisation first if this tool says none is held.

ParameterTypeRequiredMeaning
vrnstringyesVAT registration number, 9 digits
fromstringnoFrom date, YYYY-MM-DD; HMRC's default range when omitted
tostringnoTo date, YYYY-MM-DD; HMRC's default range when omitted
hmrcAccount"synthetic" | "live"noWhich HMRC environment to call; defaults to the session's HMRC authorisation's own
govTestScenariostringnoHMRC sandbox test scenario
Input schema (JSON Schema) 
{
  "type": "object",
  "properties": {
    "vrn": {
      "type": "string",
      "description": "VAT registration number, 9 digits"
    },
    "from": {
      "description": "From date, YYYY-MM-DD; HMRC's default range when omitted",
      "type": "string"
    },
    "to": {
      "description": "To date, YYYY-MM-DD; HMRC's default range when omitted",
      "type": "string"
    },
    "hmrcAccount": {
      "description": "Which HMRC environment to call; defaults to the session's HMRC authorisation's own",
      "type": "string",
      "enum": [
        "synthetic",
        "live"
      ]
    },
    "govTestScenario": {
      "description": "HMRC sandbox test scenario",
      "type": "string"
    }
  },
  "required": [
    "vrn"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}
list_vat_receipts hosted, production

The receipts Submit has stored for the signed-in account, the list its receipts page shows: each row carries the name get_vat_receipt takes. Use it to find a receipt this chat did not just file. clientId narrows the list to one of the practice's clients.

ParameterTypeRequiredMeaning
clientIdstringnoA practice client's id, to list that client's receipts
Input schema (JSON Schema) 
{
  "type": "object",
  "properties": {
    "clientId": {
      "description": "A practice client's id, to list that client's receipts",
      "type": "string"
    }
  },
  "$schema": "http://json-schema.org/draft-07/schema#"
}
move_book_to_client

Move one of the practice's own books to a client's book set (during migration from sole trader to practice). Calls DIY Accounting Submit's own move route, which copies the book and every kept version, verifies each copy, then deletes the source. Refuses when the client already has a book with this id, or the practice has no such book of its own.

ParameterTypeRequiredMeaning
clientIdstringyesThe client's id
bookIdstringyesThe book's id, one of the practice's own
Input schema (JSON Schema) 
{
  "type": "object",
  "properties": {
    "clientId": {
      "type": "string",
      "description": "The client's id"
    },
    "bookId": {
      "type": "string",
      "description": "The book's id, one of the practice's own"
    }
  },
  "required": [
    "clientId",
    "bookId"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}
open_book hosted, production

Open a diya-gl book from the filesystem: a directory holding book.toml and lines.jsonl, or a single file (a DIY Accounting workbook, a package zip, a diya-gl zip, or a diya-gl JSON file). With cloud: true, opens bookId from the DIYA cloud instead (a practice client's own book with clientId), signed in as the session's credentials idToken(). Answers the product, the entity, the period covered, the line count and the book checks summary. Replaces the session's loaded book.

ParameterTypeRequiredMeaning
pathstringnoPath to the book: a directory of book.toml + lines.jsonl, or one file the engine reads; unused with cloud
cloudbooleannoOpen bookId from the DIYA cloud instead of the filesystem
bookIdstringnoThe cloud book's id; required with cloud: true
clientIdstringnoA practice client's id, to open that client's book instead of the practice's own
Input schema (JSON Schema) 
{
  "type": "object",
  "properties": {
    "path": {
      "description": "Path to the book: a directory of book.toml + lines.jsonl, or one file the engine reads; unused with cloud",
      "type": "string"
    },
    "cloud": {
      "description": "Open bookId from the DIYA cloud instead of the filesystem",
      "type": "boolean"
    },
    "bookId": {
      "description": "The cloud book's id; required with cloud: true",
      "type": "string"
    },
    "clientId": {
      "description": "A practice client's id, to open that client's book instead of the practice's own",
      "type": "string"
    }
  },
  "$schema": "http://json-schema.org/draft-07/schema#"
}
poll_submission

Accepted, rejected with reasons, or pending, for a submitted Companies House filing, over the deployed API. kind accounts is a micro-entity or small-company accounts filing (submit_micro_entity_accounts_sandbox, submit_small_company_accounts_sandbox); kind confirmation-statement is a confirmation statement (submit_confirmation_statement_sandbox).

ParameterTypeRequiredMeaning
kind"accounts" | "confirmation-statement"yesaccounts or confirmation-statement
submissionNumberstringyesThe 6-character submission number
Input schema (JSON Schema) 
{
  "type": "object",
  "properties": {
    "kind": {
      "type": "string",
      "enum": [
        "accounts",
        "confirmation-statement"
      ],
      "description": "accounts or confirmation-statement"
    },
    "submissionNumber": {
      "type": "string",
      "description": "The 6-character submission number"
    }
  },
  "required": [
    "kind",
    "submissionNumber"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}
render_confirmation_statement_sandbox

The rendered ConfirmationAndVerificationStatement body for confirmed answers, over the deployed API. Never reaches the Companies House XML Gateway; every director's personal code is masked in the rendered body before it leaves the route.

ParameterTypeRequiredMeaning
companyNumberstringyesThe 8-character Companies House company number
companyNamestringyesThe registered company name
dateSignedstringyesThe date the statement is signed, YYYY-MM-DD
reviewDatestringyesThe confirmation statement's review date, YYYY-MM-DD, not in the future
sicCodesstring[]noUp to 4 SIC codes; sent only when they have changed
statementOfCapitalobjectnoSent only when the statement of capital has changed
shareholdingsobject[]noSent only when Companies House requires it (a new shareholding, or on request)
registeredEmailAddressstringnoSent only when it has changed
lawfulPurposeStatementAcceptedbooleanyesThe user's confirmation that the company's intended future activities are lawful
stateConfirmationAcceptedbooleanyesThe user's confirmation that the information the company must deliver to the registrar is delivered and that the statement is correct as at the confirmation date
directorsobject[]yesOne verification statement row per current director
Input schema (JSON Schema) 
{
  "type": "object",
  "properties": {
    "companyNumber": {
      "type": "string",
      "description": "The 8-character Companies House company number"
    },
    "companyName": {
      "type": "string",
      "description": "The registered company name"
    },
    "dateSigned": {
      "type": "string",
      "description": "The date the statement is signed, YYYY-MM-DD"
    },
    "reviewDate": {
      "type": "string",
      "description": "The confirmation statement's review date, YYYY-MM-DD, not in the future"
    },
    "sicCodes": {
      "description": "Up to 4 SIC codes; sent only when they have changed",
      "maxItems": 4,
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "statementOfCapital": {
      "description": "Sent only when the statement of capital has changed",
      "type": "object",
      "properties": {
        "totalAmountUnpaid": {
          "type": "number"
        },
        "totalNumberOfIssuedShares": {
          "type": "number"
        },
        "shareCurrency": {
          "type": "string"
        },
        "totalAggregateNominalValue": {
          "type": "number"
        },
        "shares": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "shareClass": {
                "type": "string"
              },
              "prescribedParticulars": {
                "type": "string"
              },
              "numShares": {
                "type": "number"
              },
              "aggregateNominalValue": {
                "type": "number"
              }
            },
            "required": [
              "shareClass",
              "prescribedParticulars",
              "numShares",
              "aggregateNominalValue"
            ]
          }
        }
      },
      "required": [
        "totalAmountUnpaid",
        "totalNumberOfIssuedShares",
        "shareCurrency",
        "totalAggregateNominalValue",
        "shares"
      ]
    },
    "shareholdings": {
      "description": "Sent only when Companies House requires it (a new shareholding, or on request)",
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "shareClass": {
            "type": "string"
          },
          "numberHeld": {
            "type": "number"
          },
          "transfers": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "dateOfTransfer": {
                  "type": "string"
                },
                "numberSharesTransferred": {
                  "type": "number"
                }
              },
              "required": [
                "dateOfTransfer",
                "numberSharesTransferred"
              ]
            }
          },
          "shareholders": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "amalgamatedName": {
                  "type": "string"
                },
                "forename": {
                  "type": "string"
                },
                "surname": {
                  "type": "string"
                },
                "address": {
                  "type": "object",
                  "propertyNames": {
                    "type": "string"
                  },
                  "additionalProperties": {
                    "type": "string"
                  }
                }
              }
            }
          }
        },
        "required": [
          "shareClass",
          "numberHeld"
        ]
      }
    },
    "registeredEmailAddress": {
      "description": "Sent only when it has changed",
      "type": "string"
    },
    "lawfulPurposeStatementAccepted": {
      "type": "boolean",
      "const": true,
      "description": "The user's confirmation that the company's intended future activities are lawful"
    },
    "stateConfirmationAccepted": {
      "type": "boolean",
      "const": true,
      "description": "The user's confirmation that the information the company must deliver to the registrar is delivered and that the statement is correct as at the confirmation date"
    },
    "directors": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "title": {
            "type": "string"
          },
          "forename": {
            "type": "string"
          },
          "otherForenames": {
            "type": "string"
          },
          "surname": {
            "type": "string"
          },
          "dob": {
            "type": "string",
            "description": "YYYY-MM-DD"
          },
          "nameMismatchReason": {
            "description": "Required when the director's register name differs from Companies House's own",
            "type": "string"
          }
        },
        "required": [
          "forename",
          "surname",
          "dob"
        ]
      },
      "description": "One verification statement row per current director"
    }
  },
  "required": [
    "companyNumber",
    "companyName",
    "dateSigned",
    "reviewDate",
    "lawfulPurposeStatementAccepted",
    "stateConfirmationAccepted",
    "directors"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}
render_micro_entity_accounts_sandbox

The rendered FRS 105 micro-entity iXBRL for confirmed figures (derive_micro_entity_accounts' answer), over the deployed API. Never reaches the Companies House XML Gateway. The route never resolves a company from a practice client's row, so this tool takes companyNumber only, not clientId.

ParameterTypeRequiredMeaning
registeredOfficeobjectnoThe registered office as address parts; taken from the company's Companies House record when left out
accountantsReportobjectnoAdds the accountants' report page and files the accounts as exempt from audit with an accountants' report
companyNumberstringyesThe 8-character Companies House company number
companyNamestringyesThe registered company name
periodStartstringyesThe accounting period's start date, YYYY-MM-DD
periodEndstringyesThe accounting period's end date, YYYY-MM-DD
balanceSheetobjectyesThe seven FRS 105 lines for the current and prior year, as derive_micro_entity_accounts answers them
averageEmployeesnumberyesThe average number of employees in the period
directorobjectyesThe signing director and the date the accounts were approved
statementsAcceptedobjectyesEvery micro-entity exemption statement, confirmed true by the user before filing
Input schema (JSON Schema) 
{
  "type": "object",
  "properties": {
    "registeredOffice": {
      "description": "The registered office as address parts; taken from the company's Companies House record when left out",
      "type": "object",
      "properties": {
        "addressLine1": {
          "type": "string"
        },
        "addressLine2": {
          "type": "string"
        },
        "addressLine3": {
          "type": "string"
        },
        "cityOrTown": {
          "type": "string"
        },
        "countyRegion": {
          "type": "string"
        },
        "postalCode": {
          "type": "string"
        },
        "country": {
          "type": "string"
        }
      },
      "required": [
        "addressLine1"
      ]
    },
    "accountantsReport": {
      "description": "Adds the accountants' report page and files the accounts as exempt from audit with an accountants' report",
      "type": "object",
      "properties": {
        "accountantsName": {
          "type": "string",
          "description": "The accountancy firm's name"
        },
        "statement": {
          "type": "string",
          "description": "The statement of the scope of the accountants' report"
        }
      },
      "required": [
        "accountantsName",
        "statement"
      ]
    },
    "companyNumber": {
      "type": "string",
      "description": "The 8-character Companies House company number"
    },
    "companyName": {
      "type": "string",
      "description": "The registered company name"
    },
    "periodStart": {
      "type": "string",
      "description": "The accounting period's start date, YYYY-MM-DD"
    },
    "periodEnd": {
      "type": "string",
      "description": "The accounting period's end date, YYYY-MM-DD"
    },
    "balanceSheet": {
      "type": "object",
      "properties": {
        "currentYear": {
          "type": "object",
          "properties": {
            "fixedAssets": {
              "type": "number"
            },
            "currentAssets": {
              "type": "number"
            },
            "creditorsWithinOneYear": {
              "type": "number"
            },
            "creditorsAfterOneYear": {
              "type": "number"
            },
            "calledUpShareCapital": {
              "type": "number"
            },
            "profitAndLossAccount": {
              "type": "number"
            },
            "capitalAndReserves": {
              "type": "number"
            }
          },
          "required": [
            "fixedAssets",
            "currentAssets",
            "creditorsWithinOneYear",
            "creditorsAfterOneYear",
            "calledUpShareCapital",
            "profitAndLossAccount",
            "capitalAndReserves"
          ]
        },
        "priorYear": {
          "type": "object",
          "properties": {
            "fixedAssets": {
              "type": "number"
            },
            "currentAssets": {
              "type": "number"
            },
            "creditorsWithinOneYear": {
              "type": "number"
            },
            "creditorsAfterOneYear": {
              "type": "number"
            },
            "calledUpShareCapital": {
              "type": "number"
            },
            "profitAndLossAccount": {
              "type": "number"
            },
            "capitalAndReserves": {
              "type": "number"
            }
          },
          "required": [
            "fixedAssets",
            "currentAssets",
            "creditorsWithinOneYear",
            "creditorsAfterOneYear",
            "calledUpShareCapital",
            "profitAndLossAccount",
            "capitalAndReserves"
          ]
        }
      },
      "required": [
        "currentYear",
        "priorYear"
      ],
      "description": "The seven FRS 105 lines for the current and prior year, as derive_micro_entity_accounts answers them"
    },
    "averageEmployees": {
      "type": "number",
      "description": "The average number of employees in the period"
    },
    "director": {
      "type": "object",
      "properties": {
        "name": {
          "type": "string"
        },
        "dateApproved": {
          "type": "string",
          "description": "YYYY-MM-DD"
        }
      },
      "required": [
        "name",
        "dateApproved"
      ],
      "description": "The signing director and the date the accounts were approved"
    },
    "statementsAccepted": {
      "type": "object",
      "properties": {
        "section477Exemption": {
          "type": "boolean"
        },
        "membersNotRequiredAudit": {
          "type": "boolean"
        },
        "directorsResponsibilities": {
          "type": "boolean"
        },
        "microEntityProvisions": {
          "type": "boolean"
        }
      },
      "required": [
        "section477Exemption",
        "membersNotRequiredAudit",
        "directorsResponsibilities",
        "microEntityProvisions"
      ],
      "description": "Every micro-entity exemption statement, confirmed true by the user before filing"
    }
  },
  "required": [
    "companyNumber",
    "companyName",
    "periodStart",
    "periodEnd",
    "balanceSheet",
    "averageEmployees",
    "director",
    "statementsAccepted"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}
render_small_company_accounts_sandbox

The rendered FRS 102 section 1A small-company iXBRL for confirmed figures (derive_small_company_accounts' answer, with principalActivity and accountingPolicies added), over the deployed API. Never reaches the Companies House XML Gateway. The route never resolves a company from a practice client's row, so this tool takes companyNumber only, not clientId.

ParameterTypeRequiredMeaning
registeredOfficeobjectnoThe registered office as address parts; taken from the company's Companies House record when left out
accountantsReportobjectnoAdds the accountants' report page and files the accounts as exempt from audit with an accountants' report
companyNumberstringyesThe 8-character Companies House company number
companyNamestringyesThe registered company name
periodStartstringyesThe accounting period's start date, YYYY-MM-DD
periodEndstringyesThe accounting period's end date, YYYY-MM-DD
averageEmployeesnumberyesThe average number of employees in the period
directorobjectyesThe signing director and the date the accounts were approved
statementsAcceptedobjectyesEvery small-company statement, confirmed true by the user before filing
smallCompanyobjectyesThe figures and notes, as derive_small_company_accounts answers them plus principalActivity and accountingPolicies
Input schema (JSON Schema) 
{
  "type": "object",
  "properties": {
    "registeredOffice": {
      "description": "The registered office as address parts; taken from the company's Companies House record when left out",
      "type": "object",
      "properties": {
        "addressLine1": {
          "type": "string"
        },
        "addressLine2": {
          "type": "string"
        },
        "addressLine3": {
          "type": "string"
        },
        "cityOrTown": {
          "type": "string"
        },
        "countyRegion": {
          "type": "string"
        },
        "postalCode": {
          "type": "string"
        },
        "country": {
          "type": "string"
        }
      },
      "required": [
        "addressLine1"
      ]
    },
    "accountantsReport": {
      "description": "Adds the accountants' report page and files the accounts as exempt from audit with an accountants' report",
      "type": "object",
      "properties": {
        "accountantsName": {
          "type": "string",
          "description": "The accountancy firm's name"
        },
        "statement": {
          "type": "string",
          "description": "The statement of the scope of the accountants' report"
        }
      },
      "required": [
        "accountantsName",
        "statement"
      ]
    },
    "companyNumber": {
      "type": "string",
      "description": "The 8-character Companies House company number"
    },
    "companyName": {
      "type": "string",
      "description": "The registered company name"
    },
    "periodStart": {
      "type": "string",
      "description": "The accounting period's start date, YYYY-MM-DD"
    },
    "periodEnd": {
      "type": "string",
      "description": "The accounting period's end date, YYYY-MM-DD"
    },
    "averageEmployees": {
      "type": "number",
      "description": "The average number of employees in the period"
    },
    "director": {
      "type": "object",
      "properties": {
        "name": {
          "type": "string"
        },
        "dateApproved": {
          "type": "string",
          "description": "YYYY-MM-DD"
        }
      },
      "required": [
        "name",
        "dateApproved"
      ],
      "description": "The signing director and the date the accounts were approved"
    },
    "statementsAccepted": {
      "type": "object",
      "properties": {
        "section477Exemption": {
          "type": "boolean"
        },
        "membersNotRequiredAudit": {
          "type": "boolean"
        },
        "directorsResponsibilities": {
          "type": "boolean"
        },
        "smallCompaniesRegime": {
          "type": "boolean"
        }
      },
      "required": [
        "section477Exemption",
        "membersNotRequiredAudit",
        "directorsResponsibilities",
        "smallCompaniesRegime"
      ],
      "description": "Every small-company statement, confirmed true by the user before filing"
    },
    "smallCompany": {
      "type": "object",
      "properties": {
        "filleted": {
          "description": "True to file the filleted copy, without the profit and loss account",
          "type": "boolean"
        },
        "principalActivity": {
          "type": "string"
        },
        "accountingPolicies": {
          "type": "string"
        },
        "taxPolicy": {
          "type": "string"
        },
        "currentIncomeTaxPolicy": {
          "description": "How current tax is calculated",
          "type": "string"
        },
        "dividendPolicy": {
          "type": "string"
        },
        "goingConcernStatement": {
          "type": "string"
        },
        "revenueRecognitionPolicy": {
          "type": "string"
        },
        "tangibleFixedAssetsPolicy": {
          "type": "string"
        },
        "impairmentPolicy": {
          "type": "string"
        },
        "financialInstrumentsPolicy": {
          "type": "string"
        },
        "controllingParty": {
          "description": "Without a name, states that the company has no ultimate controlling party",
          "type": "object",
          "properties": {
            "ultimate": {
              "type": "boolean"
            },
            "name": {
              "description": "Required when the party is ultimate",
              "type": "string"
            }
          },
          "required": [
            "ultimate"
          ]
        },
        "directors": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "description": "Every director's name, at least one"
        },
        "balanceSheet": {
          "type": "object",
          "properties": {
            "currentYear": {
              "type": "object",
              "properties": {
                "fixedAssets": {
                  "type": "number"
                },
                "stocks": {
                  "type": "number"
                },
                "debtors": {
                  "type": "number"
                },
                "cashAtBank": {
                  "type": "number"
                },
                "tradeCreditors": {
                  "type": "number"
                },
                "corporationTax": {
                  "type": "number"
                },
                "otherCreditors": {
                  "type": "number"
                },
                "creditorsAfterOneYear": {
                  "type": "number"
                },
                "bankLoansOverdrafts": {
                  "description": "Whole pounds owed to a bank within one year; 0 when left out",
                  "type": "number"
                },
                "taxationSocialSecurity": {
                  "description": "Whole pounds of PAYE, National Insurance and VAT owed within one year; 0 when left out",
                  "type": "number"
                },
                "accruals": {
                  "description": "Whole pounds of accruals and deferred income due within one year; 0 when left out",
                  "type": "number"
                },
                "bankLoansAfterOneYear": {
                  "description": "The part of creditorsAfterOneYear owed to a bank; 0 when left out",
                  "type": "number"
                },
                "calledUpShareCapital": {
                  "type": "number"
                },
                "profitAndLossAccount": {
                  "type": "number"
                },
                "capitalAndReserves": {
                  "type": "number"
                }
              },
              "required": [
                "fixedAssets",
                "stocks",
                "debtors",
                "cashAtBank",
                "tradeCreditors",
                "corporationTax",
                "otherCreditors",
                "creditorsAfterOneYear",
                "calledUpShareCapital",
                "profitAndLossAccount",
                "capitalAndReserves"
              ]
            },
            "priorYear": {
              "type": "object",
              "properties": {
                "fixedAssets": {
                  "type": "number"
                },
                "stocks": {
                  "type": "number"
                },
                "debtors": {
                  "type": "number"
                },
                "cashAtBank": {
                  "type": "number"
                },
                "tradeCreditors": {
                  "type": "number"
                },
                "corporationTax": {
                  "type": "number"
                },
                "otherCreditors": {
                  "type": "number"
                },
                "creditorsAfterOneYear": {
                  "type": "number"
                },
                "bankLoansOverdrafts": {
                  "description": "Whole pounds owed to a bank within one year; 0 when left out",
                  "type": "number"
                },
                "taxationSocialSecurity": {
                  "description": "Whole pounds of PAYE, National Insurance and VAT owed within one year; 0 when left out",
                  "type": "number"
                },
                "accruals": {
                  "description": "Whole pounds of accruals and deferred income due within one year; 0 when left out",
                  "type": "number"
                },
                "bankLoansAfterOneYear": {
                  "description": "The part of creditorsAfterOneYear owed to a bank; 0 when left out",
                  "type": "number"
                },
                "calledUpShareCapital": {
                  "type": "number"
                },
                "profitAndLossAccount": {
                  "type": "number"
                },
                "capitalAndReserves": {
                  "type": "number"
                }
              },
              "required": [
                "fixedAssets",
                "stocks",
                "debtors",
                "cashAtBank",
                "tradeCreditors",
                "corporationTax",
                "otherCreditors",
                "creditorsAfterOneYear",
                "calledUpShareCapital",
                "profitAndLossAccount",
                "capitalAndReserves"
              ]
            }
          },
          "required": [
            "currentYear"
          ]
        },
        "profitAndLoss": {
          "type": "object",
          "properties": {
            "currentYear": {
              "type": "object",
              "properties": {
                "turnover": {
                  "type": "number"
                },
                "costOfSales": {
                  "type": "number"
                },
                "grossProfit": {
                  "type": "number"
                },
                "administrativeExpenses": {
                  "type": "number"
                },
                "operatingProfit": {
                  "type": "number"
                },
                "interestReceivable": {
                  "type": "number"
                },
                "profitBeforeTax": {
                  "type": "number"
                },
                "tax": {
                  "type": "number"
                },
                "profit": {
                  "type": "number"
                }
              },
              "required": [
                "turnover",
                "costOfSales",
                "grossProfit",
                "administrativeExpenses",
                "operatingProfit",
                "interestReceivable",
                "profitBeforeTax",
                "tax",
                "profit"
              ]
            },
            "priorYear": {
              "type": "object",
              "properties": {
                "turnover": {
                  "type": "number"
                },
                "costOfSales": {
                  "type": "number"
                },
                "grossProfit": {
                  "type": "number"
                },
                "administrativeExpenses": {
                  "type": "number"
                },
                "operatingProfit": {
                  "type": "number"
                },
                "interestReceivable": {
                  "type": "number"
                },
                "profitBeforeTax": {
                  "type": "number"
                },
                "tax": {
                  "type": "number"
                },
                "profit": {
                  "type": "number"
                }
              },
              "required": [
                "turnover",
                "costOfSales",
                "grossProfit",
                "administrativeExpenses",
                "operatingProfit",
                "interestReceivable",
                "profitBeforeTax",
                "tax",
                "profit"
              ]
            }
          },
          "required": [
            "currentYear"
          ]
        },
        "fixedAssetNote": {
          "type": "object",
          "propertyNames": {
            "type": "string",
            "enum": [
              "landBuildings",
              "plantMachinery",
              "furnitureFittings",
              "computerEquipment",
              "motorVehicles"
            ]
          },
          "additionalProperties": {
            "type": "object",
            "properties": {
              "costAtStart": {
                "type": "number"
              },
              "additions": {
                "type": "number"
              },
              "disposals": {
                "type": "number"
              },
              "depreciationAtStart": {
                "type": "number"
              },
              "depreciationCharge": {
                "type": "number"
              },
              "depreciationOnDisposals": {
                "type": "number"
              }
            },
            "required": [
              "costAtStart",
              "additions",
              "disposals",
              "depreciationAtStart",
              "depreciationCharge",
              "depreciationOnDisposals"
            ]
          },
          "required": [
            "landBuildings",
            "plantMachinery",
            "furnitureFittings",
            "computerEquipment",
            "motorVehicles"
          ]
        }
      },
      "required": [
        "principalActivity",
        "accountingPolicies",
        "directors",
        "balanceSheet",
        "profitAndLoss"
      ],
      "description": "The figures and notes, as derive_small_company_accounts answers them plus principalActivity and accountingPolicies"
    }
  },
  "required": [
    "companyNumber",
    "companyName",
    "periodStart",
    "periodEnd",
    "averageEmployees",
    "director",
    "statementsAccepted",
    "smallCompany"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}
request_companies_house_codes

Answers a link where the user types the Companies House codes a filing needs, so the codes never appear in the chat. Answers {entryId, url, expiresAt}: show the user the url, wait for them to say they have saved the codes, then pass entryId as codesEntryId to the filing tool. The link works for ten minutes. A single entry is used up by one filing call; ask again for a second filing. To file for several practice clients through run_for_clients, give clientIds (kind accounts or confirmation-statement-data, no companyNumber): the page then asks for one company authentication code per client by name, and each client's filing call takes only its own client's codes, so the one entryId serves the whole batch. kind accounts is for submit_micro_entity_accounts_sandbox and submit_small_company_accounts_sandbox, confirmation-statement-data for get_confirmation_statement_data_sandbox, and confirmation-statement (with directors, in the order the filing lists them) for submit_confirmation_statement_sandbox. Over the deployed API.

ParameterTypeRequiredMeaning
kind"accounts" | "confirmation-statement" | "confirmation-statement-data"yesWhich filing the codes are for
companyNumberstringnoThe 8-character Companies House company number; required unless clientIds is given
clientIdsstring[]noPractice client ids for a batch filing through run_for_clients: the page asks for one code per client
directorsobject[]noConfirmation statement only: the directors in filing order; the page asks for one personal code each
Input schema (JSON Schema) 
{
  "type": "object",
  "properties": {
    "kind": {
      "type": "string",
      "enum": [
        "accounts",
        "confirmation-statement",
        "confirmation-statement-data"
      ],
      "description": "Which filing the codes are for"
    },
    "companyNumber": {
      "description": "The 8-character Companies House company number; required unless clientIds is given",
      "type": "string"
    },
    "clientIds": {
      "description": "Practice client ids for a batch filing through run_for_clients: the page asks for one code per client",
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "directors": {
      "description": "Confirmation statement only: the directors in filing order; the page asks for one personal code each",
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "forename": {
            "type": "string"
          },
          "surname": {
            "type": "string"
          }
        },
        "required": [
          "forename",
          "surname"
        ]
      }
    }
  },
  "required": [
    "kind"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}
request_hmrc_authorisation hosted, production

Answers HMRC's sign-in link for this session, so the VAT tools can call HMRC without a token in the chat. Answers {url, expiresAt, scope, hmrcAccount}: show the user the url, wait for them to say HMRC access is granted, then call list_vat_obligations or submit_vat_return. The link works once, for ten minutes. DIY Accounting Submit keeps HMRC's tokens itself and renews the access token for the rest of the session. A second call replaces the session's authorisation. hmrcAccount synthetic is HMRC's sandbox. Over the deployed API.

ParameterTypeRequiredMeaning
services"vat" | "itsa" | "agent"[]noThe HMRC services to ask access for: vat (the default), itsa, and agent (the practice tools invite_client and client_authorisation_status)
hmrcAccount"synthetic" | "live"noWhich HMRC environment: live (the default) or synthetic
Input schema (JSON Schema) 
{
  "type": "object",
  "properties": {
    "services": {
      "description": "The HMRC services to ask access for: vat (the default), itsa, and agent (the practice tools invite_client and client_authorisation_status)",
      "type": "array",
      "items": {
        "type": "string",
        "enum": [
          "vat",
          "itsa",
          "agent"
        ]
      }
    },
    "hmrcAccount": {
      "description": "Which HMRC environment: live (the default) or synthetic",
      "type": "string",
      "enum": [
        "synthetic",
        "live"
      ]
    }
  },
  "$schema": "http://json-schema.org/draft-07/schema#"
}
run_for_clients

Runs one client-scoped tool once per client in the practice's own list (list_clients), passing each client's clientId in turn. Returns one row per client -- {clientId, displayName, ok, result or error} -- plus a summary count; one client's failure never stops the rest. tool is one of list_vat_obligations, submit_vat_return, get_vat_receipt, submit_micro_entity_accounts_sandbox, submit_small_company_accounts_sandbox, open_book, save_book. For the two accounts tools, put in args a codesEntryId that request_companies_house_codes answered for these clients' clientIds; each client's call takes its own codes from it.

ParameterTypeRequiredMeaning
tool"list_vat_obligations" | "submit_vat_return" | "get_vat_receipt" | "submit_micro_entity_accounts_sandbox" | "submit_small_company_accounts_sandbox" | "open_book" | "save_book"yesThe client-scoped tool to run for every client
argsobjectnoThat tool's other arguments; clientId is added per client and overrides any given here
Input schema (JSON Schema) 
{
  "type": "object",
  "properties": {
    "tool": {
      "type": "string",
      "enum": [
        "list_vat_obligations",
        "submit_vat_return",
        "get_vat_receipt",
        "submit_micro_entity_accounts_sandbox",
        "submit_small_company_accounts_sandbox",
        "open_book",
        "save_book"
      ],
      "description": "The client-scoped tool to run for every client"
    },
    "args": {
      "description": "That tool's other arguments; clientId is added per client and overrides any given here",
      "type": "object",
      "propertyNames": {
        "type": "string"
      },
      "additionalProperties": {}
    }
  },
  "required": [
    "tool"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}
save_book

Save the session's loaded book to the filesystem. Formats: diya-gl-dir (book.toml + lines.jsonl into a directory; the default for a path with no extension), diya-gl-zip, json, xlsx (the product's recalculating workbook) and zip (the product's package). xlsx and zip fetch the template from spreadsheets.diyaccounting.co.uk on first use. With cloud: true, writes to the DIYA cloud by bookId instead (a practice client's book set with clientId), signed in as the session's credentials; carries the if-match etag from the session's last cloud open or save of the same bookId.

ParameterTypeRequiredMeaning
pathstringnoWhere to write: a directory for diya-gl-dir, otherwise a file path; unused with cloud
format"diya-gl-dir" | "diya-gl-zip" | "json" | "xlsx" | "zip"noOne of diya-gl-dir, diya-gl-zip, json, xlsx, zip; unused with cloud
cloudbooleannoSave to the DIYA cloud by bookId instead of the filesystem
bookIdstringnoThe cloud book's id; required with cloud: true
clientIdstringnoA practice client's id, to save into that client's book set
Input schema (JSON Schema) 
{
  "type": "object",
  "properties": {
    "path": {
      "description": "Where to write: a directory for diya-gl-dir, otherwise a file path; unused with cloud",
      "type": "string"
    },
    "format": {
      "description": "One of diya-gl-dir, diya-gl-zip, json, xlsx, zip; unused with cloud",
      "type": "string",
      "enum": [
        "diya-gl-dir",
        "diya-gl-zip",
        "json",
        "xlsx",
        "zip"
      ]
    },
    "cloud": {
      "description": "Save to the DIYA cloud by bookId instead of the filesystem",
      "type": "boolean"
    },
    "bookId": {
      "description": "The cloud book's id; required with cloud: true",
      "type": "string"
    },
    "clientId": {
      "description": "A practice client's id, to save into that client's book set",
      "type": "string"
    }
  },
  "$schema": "http://json-schema.org/draft-07/schema#"
}
sign_in

Sign in to DIY Accounting Submit as the MCP's own Cognito app client: opens the pool's hosted UI in the operator's browser (or prints the URL, when it cannot open one) with a PKCE code challenge, catches the authorization code on a loopback listener, and stores the refresh token under ~/.config/diya-submit/credentials.json mode 600. Every tool that reaches the deployed API (the VAT, Companies House, practice and cloud-book tools) uses the resulting session; run this once before any of them, and again after a sign_out or once the stored refresh token has expired.

No parameters.

Input schema (JSON Schema) 
{
  "type": "object",
  "properties": {},
  "$schema": "http://json-schema.org/draft-07/schema#"
}
sign_out

Ends the MCP's own session: revokes the refresh token at Cognito, tells DIY Accounting Submit's sign-out route to close it server-side too, then deletes the local credentials file. Best-effort on both network calls, so it still clears the local session when offline or the token is already expired.

No parameters.

Input schema (JSON Schema) 
{
  "type": "object",
  "properties": {},
  "$schema": "http://json-schema.org/draft-07/schema#"
}
submit_confirmation_statement_sandbox

Files a confirmed confirmation statement through the Companies House XML Gateway, over the deployed API; returns the submission number. The company authentication code and every director's personal code are not arguments: the user types them on the link request_companies_house_codes (kind confirmation-statement, with the directors in the order given here) answers, and this call names that entry by codesEntryId, which it uses up.

ParameterTypeRequiredMeaning
companyNumberstringyesThe 8-character Companies House company number
companyNamestringyesThe registered company name
dateSignedstringyesThe date the statement is signed, YYYY-MM-DD
reviewDatestringyesThe confirmation statement's review date, YYYY-MM-DD, not in the future
sicCodesstring[]noUp to 4 SIC codes; sent only when they have changed
statementOfCapitalobjectnoSent only when the statement of capital has changed
shareholdingsobject[]noSent only when Companies House requires it (a new shareholding, or on request)
registeredEmailAddressstringnoSent only when it has changed
lawfulPurposeStatementAcceptedbooleanyesThe user's confirmation that the company's intended future activities are lawful
stateConfirmationAcceptedbooleanyesThe user's confirmation that the information the company must deliver to the registrar is delivered and that the statement is correct as at the confirmation date
directorsobject[]yesOne verification statement row per current director
codesEntryIdstringyesThe entryId request_companies_house_codes answered, once the user has typed the codes on its link
Input schema (JSON Schema) 
{
  "type": "object",
  "properties": {
    "companyNumber": {
      "type": "string",
      "description": "The 8-character Companies House company number"
    },
    "companyName": {
      "type": "string",
      "description": "The registered company name"
    },
    "dateSigned": {
      "type": "string",
      "description": "The date the statement is signed, YYYY-MM-DD"
    },
    "reviewDate": {
      "type": "string",
      "description": "The confirmation statement's review date, YYYY-MM-DD, not in the future"
    },
    "sicCodes": {
      "description": "Up to 4 SIC codes; sent only when they have changed",
      "maxItems": 4,
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "statementOfCapital": {
      "description": "Sent only when the statement of capital has changed",
      "type": "object",
      "properties": {
        "totalAmountUnpaid": {
          "type": "number"
        },
        "totalNumberOfIssuedShares": {
          "type": "number"
        },
        "shareCurrency": {
          "type": "string"
        },
        "totalAggregateNominalValue": {
          "type": "number"
        },
        "shares": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "shareClass": {
                "type": "string"
              },
              "prescribedParticulars": {
                "type": "string"
              },
              "numShares": {
                "type": "number"
              },
              "aggregateNominalValue": {
                "type": "number"
              }
            },
            "required": [
              "shareClass",
              "prescribedParticulars",
              "numShares",
              "aggregateNominalValue"
            ]
          }
        }
      },
      "required": [
        "totalAmountUnpaid",
        "totalNumberOfIssuedShares",
        "shareCurrency",
        "totalAggregateNominalValue",
        "shares"
      ]
    },
    "shareholdings": {
      "description": "Sent only when Companies House requires it (a new shareholding, or on request)",
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "shareClass": {
            "type": "string"
          },
          "numberHeld": {
            "type": "number"
          },
          "transfers": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "dateOfTransfer": {
                  "type": "string"
                },
                "numberSharesTransferred": {
                  "type": "number"
                }
              },
              "required": [
                "dateOfTransfer",
                "numberSharesTransferred"
              ]
            }
          },
          "shareholders": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "amalgamatedName": {
                  "type": "string"
                },
                "forename": {
                  "type": "string"
                },
                "surname": {
                  "type": "string"
                },
                "address": {
                  "type": "object",
                  "propertyNames": {
                    "type": "string"
                  },
                  "additionalProperties": {
                    "type": "string"
                  }
                }
              }
            }
          }
        },
        "required": [
          "shareClass",
          "numberHeld"
        ]
      }
    },
    "registeredEmailAddress": {
      "description": "Sent only when it has changed",
      "type": "string"
    },
    "lawfulPurposeStatementAccepted": {
      "type": "boolean",
      "const": true,
      "description": "The user's confirmation that the company's intended future activities are lawful"
    },
    "stateConfirmationAccepted": {
      "type": "boolean",
      "const": true,
      "description": "The user's confirmation that the information the company must deliver to the registrar is delivered and that the statement is correct as at the confirmation date"
    },
    "directors": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "title": {
            "type": "string"
          },
          "forename": {
            "type": "string"
          },
          "otherForenames": {
            "type": "string"
          },
          "surname": {
            "type": "string"
          },
          "dob": {
            "type": "string",
            "description": "YYYY-MM-DD"
          },
          "nameMismatchReason": {
            "description": "Required when the director's register name differs from Companies House's own",
            "type": "string"
          }
        },
        "required": [
          "forename",
          "surname",
          "dob"
        ]
      },
      "description": "One verification statement row per current director"
    },
    "codesEntryId": {
      "type": "string",
      "description": "The entryId request_companies_house_codes answered, once the user has typed the codes on its link"
    }
  },
  "required": [
    "companyNumber",
    "companyName",
    "dateSigned",
    "reviewDate",
    "lawfulPurposeStatementAccepted",
    "stateConfirmationAccepted",
    "directors",
    "codesEntryId"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}
submit_itsa_annual_submission

Files the year's allowances and adjustments for HMRC's Self Employment Business API annual submission (derive_itsa_annual_submission's figures, once the user has confirmed them) over the deployed API. Uses the session's HMRC authorisation for the itsa service: call request_hmrc_authorisation with services ["itsa"] first if this tool says none is held.

ParameterTypeRequiredMeaning
ninostringyesThe customer's National Insurance number
businessIdstringyesThe self-employment business id HMRC holds, for example XAIS12345678901
taxYearstringyesThe tax year, as 2025-26
adjustmentsobjectnoAdjustments by field, as derive_itsa_annual_submission answers them
allowancesobjectnoAllowances by field, as derive_itsa_annual_submission answers them
nonFinancialsobjectnoThe non-financial facts HMRC takes, when the year needs them
hmrcAccount"synthetic" | "live"noWhich HMRC environment to call; defaults to the session's HMRC authorisation's own
govTestScenariostringnoHMRC sandbox test scenario
runFraudPreventionHeaderValidationbooleanno
Input schema (JSON Schema) 
{
  "type": "object",
  "properties": {
    "nino": {
      "type": "string",
      "description": "The customer's National Insurance number"
    },
    "businessId": {
      "type": "string",
      "description": "The self-employment business id HMRC holds, for example XAIS12345678901"
    },
    "taxYear": {
      "type": "string",
      "description": "The tax year, as 2025-26"
    },
    "adjustments": {
      "description": "Adjustments by field, as derive_itsa_annual_submission answers them",
      "type": "object",
      "propertyNames": {
        "type": "string"
      },
      "additionalProperties": {
        "type": "number"
      }
    },
    "allowances": {
      "description": "Allowances by field, as derive_itsa_annual_submission answers them",
      "type": "object",
      "propertyNames": {
        "type": "string"
      },
      "additionalProperties": {
        "type": "number"
      }
    },
    "nonFinancials": {
      "description": "The non-financial facts HMRC takes, when the year needs them",
      "type": "object",
      "propertyNames": {
        "type": "string"
      },
      "additionalProperties": {}
    },
    "hmrcAccount": {
      "description": "Which HMRC environment to call; defaults to the session's HMRC authorisation's own",
      "type": "string",
      "enum": [
        "synthetic",
        "live"
      ]
    },
    "govTestScenario": {
      "description": "HMRC sandbox test scenario",
      "type": "string"
    },
    "runFraudPreventionHeaderValidation": {
      "type": "boolean"
    }
  },
  "required": [
    "nino",
    "businessId",
    "taxYear"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}
submit_itsa_quarterly_update

Files one period of HMRC's Self Employment Business API (derive_itsa_quarterly_update's figures, once the user has confirmed them) over the deployed API. In a tax year filed as cumulative period summaries (2025-26 on) the figures are the running total from 6 April and the period dates are optional; in earlier years they are required. Uses the session's HMRC authorisation for the itsa service: call request_hmrc_authorisation with services ["itsa"] first if this tool says none is held.

ParameterTypeRequiredMeaning
ninostringyesThe customer's National Insurance number
businessIdstringyesThe self-employment business id HMRC holds, for example XAIS12345678901
taxYearstringyesThe tax year, as 2025-26
periodStartDatestringnoThe period's start, YYYY-MM-DD
periodEndDatestringnoThe period's end, YYYY-MM-DD
periodIncomeobjectnoIncome by field, as derive_itsa_quarterly_update answers it
periodExpensesobjectnoExpenses by field, as derive_itsa_quarterly_update answers it
periodDisallowableExpensesobjectnoDisallowable expenses by field, as derive_itsa_quarterly_update answers it
hmrcAccount"synthetic" | "live"noWhich HMRC environment to call; defaults to the session's HMRC authorisation's own
govTestScenariostringnoHMRC sandbox test scenario
runFraudPreventionHeaderValidationbooleanno
Input schema (JSON Schema) 
{
  "type": "object",
  "properties": {
    "nino": {
      "type": "string",
      "description": "The customer's National Insurance number"
    },
    "businessId": {
      "type": "string",
      "description": "The self-employment business id HMRC holds, for example XAIS12345678901"
    },
    "taxYear": {
      "type": "string",
      "description": "The tax year, as 2025-26"
    },
    "periodStartDate": {
      "description": "The period's start, YYYY-MM-DD",
      "type": "string"
    },
    "periodEndDate": {
      "description": "The period's end, YYYY-MM-DD",
      "type": "string"
    },
    "periodIncome": {
      "description": "Income by field, as derive_itsa_quarterly_update answers it",
      "type": "object",
      "propertyNames": {
        "type": "string"
      },
      "additionalProperties": {
        "type": "number"
      }
    },
    "periodExpenses": {
      "description": "Expenses by field, as derive_itsa_quarterly_update answers it",
      "type": "object",
      "propertyNames": {
        "type": "string"
      },
      "additionalProperties": {
        "type": "number"
      }
    },
    "periodDisallowableExpenses": {
      "description": "Disallowable expenses by field, as derive_itsa_quarterly_update answers it",
      "type": "object",
      "propertyNames": {
        "type": "string"
      },
      "additionalProperties": {
        "type": "number"
      }
    },
    "hmrcAccount": {
      "description": "Which HMRC environment to call; defaults to the session's HMRC authorisation's own",
      "type": "string",
      "enum": [
        "synthetic",
        "live"
      ]
    },
    "govTestScenario": {
      "description": "HMRC sandbox test scenario",
      "type": "string"
    },
    "runFraudPreventionHeaderValidation": {
      "type": "boolean"
    }
  },
  "required": [
    "nino",
    "businessId",
    "taxYear"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}
submit_micro_entity_accounts_sandbox

Files confirmed micro-entity accounts through the Companies House XML Gateway, over the deployed API, for companyNumber or, when clientId is given instead, for that practice client's own company number; returns the submission number. The company authentication code is not an argument: the user types it on the link request_companies_house_codes answers, and this call names that entry by codesEntryId. A single entry is used up by this call; a batch entry (clientIds) gives up only this clientId's codes, so run_for_clients can pass one codesEntryId for every client.

ParameterTypeRequiredMeaning
registeredOfficeobjectnoThe registered office as address parts; taken from the company's Companies House record when left out
accountantsReportobjectnoAdds the accountants' report page and files the accounts as exempt from audit with an accountants' report
companyNumberstringnoRequired unless clientId is given
companyNamestringyesThe registered company name
periodStartstringyesThe accounting period's start date, YYYY-MM-DD
periodEndstringyesThe accounting period's end date, YYYY-MM-DD
balanceSheetobjectyesThe seven FRS 105 lines for the current and prior year, as derive_micro_entity_accounts answers them
averageEmployeesnumberyesThe average number of employees in the period
directorobjectyesThe signing director and the date the accounts were approved
statementsAcceptedobjectyesEvery micro-entity exemption statement, confirmed true by the user before filing
clientIdstringnoA practice client's id, to resolve companyNumber from the client row instead
codesEntryIdstringyesThe entryId request_companies_house_codes answered, once the user has typed the codes on its link
Input schema (JSON Schema) 
{
  "type": "object",
  "properties": {
    "registeredOffice": {
      "description": "The registered office as address parts; taken from the company's Companies House record when left out",
      "type": "object",
      "properties": {
        "addressLine1": {
          "type": "string"
        },
        "addressLine2": {
          "type": "string"
        },
        "addressLine3": {
          "type": "string"
        },
        "cityOrTown": {
          "type": "string"
        },
        "countyRegion": {
          "type": "string"
        },
        "postalCode": {
          "type": "string"
        },
        "country": {
          "type": "string"
        }
      },
      "required": [
        "addressLine1"
      ]
    },
    "accountantsReport": {
      "description": "Adds the accountants' report page and files the accounts as exempt from audit with an accountants' report",
      "type": "object",
      "properties": {
        "accountantsName": {
          "type": "string",
          "description": "The accountancy firm's name"
        },
        "statement": {
          "type": "string",
          "description": "The statement of the scope of the accountants' report"
        }
      },
      "required": [
        "accountantsName",
        "statement"
      ]
    },
    "companyNumber": {
      "description": "Required unless clientId is given",
      "type": "string"
    },
    "companyName": {
      "type": "string",
      "description": "The registered company name"
    },
    "periodStart": {
      "type": "string",
      "description": "The accounting period's start date, YYYY-MM-DD"
    },
    "periodEnd": {
      "type": "string",
      "description": "The accounting period's end date, YYYY-MM-DD"
    },
    "balanceSheet": {
      "type": "object",
      "properties": {
        "currentYear": {
          "type": "object",
          "properties": {
            "fixedAssets": {
              "type": "number"
            },
            "currentAssets": {
              "type": "number"
            },
            "creditorsWithinOneYear": {
              "type": "number"
            },
            "creditorsAfterOneYear": {
              "type": "number"
            },
            "calledUpShareCapital": {
              "type": "number"
            },
            "profitAndLossAccount": {
              "type": "number"
            },
            "capitalAndReserves": {
              "type": "number"
            }
          },
          "required": [
            "fixedAssets",
            "currentAssets",
            "creditorsWithinOneYear",
            "creditorsAfterOneYear",
            "calledUpShareCapital",
            "profitAndLossAccount",
            "capitalAndReserves"
          ]
        },
        "priorYear": {
          "type": "object",
          "properties": {
            "fixedAssets": {
              "type": "number"
            },
            "currentAssets": {
              "type": "number"
            },
            "creditorsWithinOneYear": {
              "type": "number"
            },
            "creditorsAfterOneYear": {
              "type": "number"
            },
            "calledUpShareCapital": {
              "type": "number"
            },
            "profitAndLossAccount": {
              "type": "number"
            },
            "capitalAndReserves": {
              "type": "number"
            }
          },
          "required": [
            "fixedAssets",
            "currentAssets",
            "creditorsWithinOneYear",
            "creditorsAfterOneYear",
            "calledUpShareCapital",
            "profitAndLossAccount",
            "capitalAndReserves"
          ]
        }
      },
      "required": [
        "currentYear",
        "priorYear"
      ],
      "description": "The seven FRS 105 lines for the current and prior year, as derive_micro_entity_accounts answers them"
    },
    "averageEmployees": {
      "type": "number",
      "description": "The average number of employees in the period"
    },
    "director": {
      "type": "object",
      "properties": {
        "name": {
          "type": "string"
        },
        "dateApproved": {
          "type": "string",
          "description": "YYYY-MM-DD"
        }
      },
      "required": [
        "name",
        "dateApproved"
      ],
      "description": "The signing director and the date the accounts were approved"
    },
    "statementsAccepted": {
      "type": "object",
      "properties": {
        "section477Exemption": {
          "type": "boolean"
        },
        "membersNotRequiredAudit": {
          "type": "boolean"
        },
        "directorsResponsibilities": {
          "type": "boolean"
        },
        "microEntityProvisions": {
          "type": "boolean"
        }
      },
      "required": [
        "section477Exemption",
        "membersNotRequiredAudit",
        "directorsResponsibilities",
        "microEntityProvisions"
      ],
      "description": "Every micro-entity exemption statement, confirmed true by the user before filing"
    },
    "clientId": {
      "description": "A practice client's id, to resolve companyNumber from the client row instead",
      "type": "string"
    },
    "codesEntryId": {
      "type": "string",
      "description": "The entryId request_companies_house_codes answered, once the user has typed the codes on its link"
    }
  },
  "required": [
    "companyName",
    "periodStart",
    "periodEnd",
    "balanceSheet",
    "averageEmployees",
    "director",
    "statementsAccepted",
    "codesEntryId"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}
submit_small_company_accounts_sandbox

Files confirmed small-company accounts through the Companies House XML Gateway, over the deployed API, for companyNumber or, when clientId is given instead, for that practice client's own company number; returns the submission number. The company authentication code is not an argument: the user types it on the link request_companies_house_codes answers (kind accounts), and this call names that entry by codesEntryId. A single entry is used up by this call; a batch entry (clientIds) gives up only this clientId's codes, so run_for_clients can pass one codesEntryId for every client. poll_submission with kind accounts reaches the outcome.

ParameterTypeRequiredMeaning
registeredOfficeobjectnoThe registered office as address parts; taken from the company's Companies House record when left out
accountantsReportobjectnoAdds the accountants' report page and files the accounts as exempt from audit with an accountants' report
companyNumberstringnoRequired unless clientId is given
companyNamestringyesThe registered company name
periodStartstringyesThe accounting period's start date, YYYY-MM-DD
periodEndstringyesThe accounting period's end date, YYYY-MM-DD
averageEmployeesnumberyesThe average number of employees in the period
directorobjectyesThe signing director and the date the accounts were approved
statementsAcceptedobjectyesEvery small-company statement, confirmed true by the user before filing
smallCompanyobjectyesThe figures and notes, as derive_small_company_accounts answers them plus principalActivity and accountingPolicies
clientIdstringnoA practice client's id, to resolve companyNumber from the client row instead
codesEntryIdstringyesThe entryId request_companies_house_codes answered, once the user has typed the codes on its link
Input schema (JSON Schema) 
{
  "type": "object",
  "properties": {
    "registeredOffice": {
      "description": "The registered office as address parts; taken from the company's Companies House record when left out",
      "type": "object",
      "properties": {
        "addressLine1": {
          "type": "string"
        },
        "addressLine2": {
          "type": "string"
        },
        "addressLine3": {
          "type": "string"
        },
        "cityOrTown": {
          "type": "string"
        },
        "countyRegion": {
          "type": "string"
        },
        "postalCode": {
          "type": "string"
        },
        "country": {
          "type": "string"
        }
      },
      "required": [
        "addressLine1"
      ]
    },
    "accountantsReport": {
      "description": "Adds the accountants' report page and files the accounts as exempt from audit with an accountants' report",
      "type": "object",
      "properties": {
        "accountantsName": {
          "type": "string",
          "description": "The accountancy firm's name"
        },
        "statement": {
          "type": "string",
          "description": "The statement of the scope of the accountants' report"
        }
      },
      "required": [
        "accountantsName",
        "statement"
      ]
    },
    "companyNumber": {
      "description": "Required unless clientId is given",
      "type": "string"
    },
    "companyName": {
      "type": "string",
      "description": "The registered company name"
    },
    "periodStart": {
      "type": "string",
      "description": "The accounting period's start date, YYYY-MM-DD"
    },
    "periodEnd": {
      "type": "string",
      "description": "The accounting period's end date, YYYY-MM-DD"
    },
    "averageEmployees": {
      "type": "number",
      "description": "The average number of employees in the period"
    },
    "director": {
      "type": "object",
      "properties": {
        "name": {
          "type": "string"
        },
        "dateApproved": {
          "type": "string",
          "description": "YYYY-MM-DD"
        }
      },
      "required": [
        "name",
        "dateApproved"
      ],
      "description": "The signing director and the date the accounts were approved"
    },
    "statementsAccepted": {
      "type": "object",
      "properties": {
        "section477Exemption": {
          "type": "boolean"
        },
        "membersNotRequiredAudit": {
          "type": "boolean"
        },
        "directorsResponsibilities": {
          "type": "boolean"
        },
        "smallCompaniesRegime": {
          "type": "boolean"
        }
      },
      "required": [
        "section477Exemption",
        "membersNotRequiredAudit",
        "directorsResponsibilities",
        "smallCompaniesRegime"
      ],
      "description": "Every small-company statement, confirmed true by the user before filing"
    },
    "smallCompany": {
      "type": "object",
      "properties": {
        "filleted": {
          "description": "True to file the filleted copy, without the profit and loss account",
          "type": "boolean"
        },
        "principalActivity": {
          "type": "string"
        },
        "accountingPolicies": {
          "type": "string"
        },
        "taxPolicy": {
          "type": "string"
        },
        "currentIncomeTaxPolicy": {
          "description": "How current tax is calculated",
          "type": "string"
        },
        "dividendPolicy": {
          "type": "string"
        },
        "goingConcernStatement": {
          "type": "string"
        },
        "revenueRecognitionPolicy": {
          "type": "string"
        },
        "tangibleFixedAssetsPolicy": {
          "type": "string"
        },
        "impairmentPolicy": {
          "type": "string"
        },
        "financialInstrumentsPolicy": {
          "type": "string"
        },
        "controllingParty": {
          "description": "Without a name, states that the company has no ultimate controlling party",
          "type": "object",
          "properties": {
            "ultimate": {
              "type": "boolean"
            },
            "name": {
              "description": "Required when the party is ultimate",
              "type": "string"
            }
          },
          "required": [
            "ultimate"
          ]
        },
        "directors": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "description": "Every director's name, at least one"
        },
        "balanceSheet": {
          "type": "object",
          "properties": {
            "currentYear": {
              "type": "object",
              "properties": {
                "fixedAssets": {
                  "type": "number"
                },
                "stocks": {
                  "type": "number"
                },
                "debtors": {
                  "type": "number"
                },
                "cashAtBank": {
                  "type": "number"
                },
                "tradeCreditors": {
                  "type": "number"
                },
                "corporationTax": {
                  "type": "number"
                },
                "otherCreditors": {
                  "type": "number"
                },
                "creditorsAfterOneYear": {
                  "type": "number"
                },
                "bankLoansOverdrafts": {
                  "description": "Whole pounds owed to a bank within one year; 0 when left out",
                  "type": "number"
                },
                "taxationSocialSecurity": {
                  "description": "Whole pounds of PAYE, National Insurance and VAT owed within one year; 0 when left out",
                  "type": "number"
                },
                "accruals": {
                  "description": "Whole pounds of accruals and deferred income due within one year; 0 when left out",
                  "type": "number"
                },
                "bankLoansAfterOneYear": {
                  "description": "The part of creditorsAfterOneYear owed to a bank; 0 when left out",
                  "type": "number"
                },
                "calledUpShareCapital": {
                  "type": "number"
                },
                "profitAndLossAccount": {
                  "type": "number"
                },
                "capitalAndReserves": {
                  "type": "number"
                }
              },
              "required": [
                "fixedAssets",
                "stocks",
                "debtors",
                "cashAtBank",
                "tradeCreditors",
                "corporationTax",
                "otherCreditors",
                "creditorsAfterOneYear",
                "calledUpShareCapital",
                "profitAndLossAccount",
                "capitalAndReserves"
              ]
            },
            "priorYear": {
              "type": "object",
              "properties": {
                "fixedAssets": {
                  "type": "number"
                },
                "stocks": {
                  "type": "number"
                },
                "debtors": {
                  "type": "number"
                },
                "cashAtBank": {
                  "type": "number"
                },
                "tradeCreditors": {
                  "type": "number"
                },
                "corporationTax": {
                  "type": "number"
                },
                "otherCreditors": {
                  "type": "number"
                },
                "creditorsAfterOneYear": {
                  "type": "number"
                },
                "bankLoansOverdrafts": {
                  "description": "Whole pounds owed to a bank within one year; 0 when left out",
                  "type": "number"
                },
                "taxationSocialSecurity": {
                  "description": "Whole pounds of PAYE, National Insurance and VAT owed within one year; 0 when left out",
                  "type": "number"
                },
                "accruals": {
                  "description": "Whole pounds of accruals and deferred income due within one year; 0 when left out",
                  "type": "number"
                },
                "bankLoansAfterOneYear": {
                  "description": "The part of creditorsAfterOneYear owed to a bank; 0 when left out",
                  "type": "number"
                },
                "calledUpShareCapital": {
                  "type": "number"
                },
                "profitAndLossAccount": {
                  "type": "number"
                },
                "capitalAndReserves": {
                  "type": "number"
                }
              },
              "required": [
                "fixedAssets",
                "stocks",
                "debtors",
                "cashAtBank",
                "tradeCreditors",
                "corporationTax",
                "otherCreditors",
                "creditorsAfterOneYear",
                "calledUpShareCapital",
                "profitAndLossAccount",
                "capitalAndReserves"
              ]
            }
          },
          "required": [
            "currentYear"
          ]
        },
        "profitAndLoss": {
          "type": "object",
          "properties": {
            "currentYear": {
              "type": "object",
              "properties": {
                "turnover": {
                  "type": "number"
                },
                "costOfSales": {
                  "type": "number"
                },
                "grossProfit": {
                  "type": "number"
                },
                "administrativeExpenses": {
                  "type": "number"
                },
                "operatingProfit": {
                  "type": "number"
                },
                "interestReceivable": {
                  "type": "number"
                },
                "profitBeforeTax": {
                  "type": "number"
                },
                "tax": {
                  "type": "number"
                },
                "profit": {
                  "type": "number"
                }
              },
              "required": [
                "turnover",
                "costOfSales",
                "grossProfit",
                "administrativeExpenses",
                "operatingProfit",
                "interestReceivable",
                "profitBeforeTax",
                "tax",
                "profit"
              ]
            },
            "priorYear": {
              "type": "object",
              "properties": {
                "turnover": {
                  "type": "number"
                },
                "costOfSales": {
                  "type": "number"
                },
                "grossProfit": {
                  "type": "number"
                },
                "administrativeExpenses": {
                  "type": "number"
                },
                "operatingProfit": {
                  "type": "number"
                },
                "interestReceivable": {
                  "type": "number"
                },
                "profitBeforeTax": {
                  "type": "number"
                },
                "tax": {
                  "type": "number"
                },
                "profit": {
                  "type": "number"
                }
              },
              "required": [
                "turnover",
                "costOfSales",
                "grossProfit",
                "administrativeExpenses",
                "operatingProfit",
                "interestReceivable",
                "profitBeforeTax",
                "tax",
                "profit"
              ]
            }
          },
          "required": [
            "currentYear"
          ]
        },
        "fixedAssetNote": {
          "type": "object",
          "propertyNames": {
            "type": "string",
            "enum": [
              "landBuildings",
              "plantMachinery",
              "furnitureFittings",
              "computerEquipment",
              "motorVehicles"
            ]
          },
          "additionalProperties": {
            "type": "object",
            "properties": {
              "costAtStart": {
                "type": "number"
              },
              "additions": {
                "type": "number"
              },
              "disposals": {
                "type": "number"
              },
              "depreciationAtStart": {
                "type": "number"
              },
              "depreciationCharge": {
                "type": "number"
              },
              "depreciationOnDisposals": {
                "type": "number"
              }
            },
            "required": [
              "costAtStart",
              "additions",
              "disposals",
              "depreciationAtStart",
              "depreciationCharge",
              "depreciationOnDisposals"
            ]
          },
          "required": [
            "landBuildings",
            "plantMachinery",
            "furnitureFittings",
            "computerEquipment",
            "motorVehicles"
          ]
        }
      },
      "required": [
        "principalActivity",
        "accountingPolicies",
        "directors",
        "balanceSheet",
        "profitAndLoss"
      ],
      "description": "The figures and notes, as derive_small_company_accounts answers them plus principalActivity and accountingPolicies"
    },
    "clientId": {
      "description": "A practice client's id, to resolve companyNumber from the client row instead",
      "type": "string"
    },
    "codesEntryId": {
      "type": "string",
      "description": "The entryId request_companies_house_codes answered, once the user has typed the codes on its link"
    }
  },
  "required": [
    "companyName",
    "periodStart",
    "periodEnd",
    "averageEmployees",
    "director",
    "statementsAccepted",
    "smallCompany",
    "codesEntryId"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}
submit_vat_return hosted, production

Files the nine VAT boxes the user has confirmed (derive_vat_return's hmrc fields) over the deployed API, for vatNumber or, when clientId is given instead, for that practice client's own VRN. Boxes 3 and 5 are HMRC's own totals and are not sent; the route derives them. Uses the session's HMRC authorisation: call request_hmrc_authorisation first if this tool says none is held.

ParameterTypeRequiredMeaning
vatNumberstringnoVAT registration number, 9 digits; required unless clientId is given
clientIdstringnoA practice client's id, to resolve vatNumber from the client row instead
periodStartstringyesThe obligation's period start, YYYY-MM-DD
periodEndstringyesThe obligation's period end, YYYY-MM-DD
vatDueSalesnumberyesBox 1
vatDueAcquisitionsnumberyesBox 2
vatReclaimedCurrPeriodnumberyesBox 4
totalValueSalesExVATnumberyesBox 6
totalValuePurchasesExVATnumberyesBox 7
totalValueGoodsSuppliedExVATnumberyesBox 8
totalAcquisitionsExVATnumberyesBox 9
hmrcAccount"synthetic" | "live"noWhich HMRC environment to call; defaults to the session's HMRC authorisation's own
govTestScenariostringnoHMRC sandbox test scenario
runFraudPreventionHeaderValidationbooleanno
allowSyntheticObligationsbooleannoSynthetic only: file under any open obligation if the dates do not match
Input schema (JSON Schema) 
{
  "type": "object",
  "properties": {
    "vatNumber": {
      "description": "VAT registration number, 9 digits; required unless clientId is given",
      "type": "string"
    },
    "clientId": {
      "description": "A practice client's id, to resolve vatNumber from the client row instead",
      "type": "string"
    },
    "periodStart": {
      "type": "string",
      "description": "The obligation's period start, YYYY-MM-DD"
    },
    "periodEnd": {
      "type": "string",
      "description": "The obligation's period end, YYYY-MM-DD"
    },
    "vatDueSales": {
      "type": "number",
      "description": "Box 1"
    },
    "vatDueAcquisitions": {
      "type": "number",
      "description": "Box 2"
    },
    "vatReclaimedCurrPeriod": {
      "type": "number",
      "description": "Box 4"
    },
    "totalValueSalesExVAT": {
      "type": "number",
      "description": "Box 6"
    },
    "totalValuePurchasesExVAT": {
      "type": "number",
      "description": "Box 7"
    },
    "totalValueGoodsSuppliedExVAT": {
      "type": "number",
      "description": "Box 8"
    },
    "totalAcquisitionsExVAT": {
      "type": "number",
      "description": "Box 9"
    },
    "hmrcAccount": {
      "description": "Which HMRC environment to call; defaults to the session's HMRC authorisation's own",
      "type": "string",
      "enum": [
        "synthetic",
        "live"
      ]
    },
    "govTestScenario": {
      "description": "HMRC sandbox test scenario",
      "type": "string"
    },
    "runFraudPreventionHeaderValidation": {
      "type": "boolean"
    },
    "allowSyntheticObligations": {
      "description": "Synthetic only: file under any open obligation if the dates do not match",
      "type": "boolean"
    }
  },
  "required": [
    "periodStart",
    "periodEnd",
    "vatDueSales",
    "vatDueAcquisitions",
    "vatReclaimedCurrPeriod",
    "totalValueSalesExVAT",
    "totalValuePurchasesExVAT",
    "totalValueGoodsSuppliedExVAT",
    "totalAcquisitionsExVAT"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}
write_finance_package

Writes a diya-gl book and its lines as the unzipped spreadsheets package directory a completed year's package holds: one workbook for a single-file product (Basic Sole Trader, Taxi Driver), the whole named set for a multi-file one (Self Employed, Company), under outputDir in a directory named the product's own way. Reads the book from bookPath (a diya-gl-dir, or any file open_book reads) or from book and lines given directly; does not touch the session's own loaded book. Reads the workbook templates from templatePackagePath (the spreadsheets repository's app/ directory) when given, otherwise fetches them from spreadsheets.diyaccounting.co.uk on first use.

ParameterTypeRequiredMeaning
bookPathstringnoPath to the book: a directory of book.toml + lines.jsonl, or one file the engine reads
bookobjectnoA parsed book.toml, instead of bookPath
linesobject[]noParsed lines.jsonl entries, instead of bookPath
templatePackagePathstringnoThe spreadsheets repository's app/ directory, read directly instead of fetching templates over the network
outputDirstringyesThe directory the package's own named directory is written under
Input schema (JSON Schema) 
{
  "type": "object",
  "properties": {
    "bookPath": {
      "description": "Path to the book: a directory of book.toml + lines.jsonl, or one file the engine reads",
      "type": "string"
    },
    "book": {
      "description": "A parsed book.toml, instead of bookPath",
      "type": "object",
      "propertyNames": {
        "type": "string"
      },
      "additionalProperties": {}
    },
    "lines": {
      "description": "Parsed lines.jsonl entries, instead of bookPath",
      "type": "array",
      "items": {
        "type": "object",
        "propertyNames": {
          "type": "string"
        },
        "additionalProperties": {}
      }
    },
    "templatePackagePath": {
      "description": "The spreadsheets repository's app/ directory, read directly instead of fetching templates over the network",
      "type": "string"
    },
    "outputDir": {
      "type": "string",
      "description": "The directory the package's own named directory is written under"
    }
  },
  "required": [
    "outputDir"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}