Duck Tax

Derive a small-company balance sheet (micro-entity, in UK terms) from raw figures and validate it. Returns the derived sheet for the current and prior year, the figures the authority would reject (negatives where it wants a positive, share capital left at nil), and whether they are complete enough to hand to a filing product. It does NOT check that the sheet balances and cannot: retained earnings is derived as the balancing figure, so both sides always agree. Do not tell anybody their sheet was checked for internal consistency. Free and instant: call it after every change to the figures. All money in major units (pounds not pence, dollars not cents). Pass lastFiledAs from lookup_company and it also warns when figures showing activity are about to be filed dormant again.

{
  "type": "object",
  "properties": {
    "jurisdiction": {
      "default": "GB",
      "description": "ISO country code. GB is the only jurisdiction with full support.",
      "type": "string",
      "enum": [
        "GB",
        "IE",
        "US",
        "AU"
      ]
    },
    "figures": {
      "type": "object",
      "properties": {
        "turnover": {
          "type": "number",
          "description": "Sales income for the year, in major currency units (pounds/euros/dollars)."
        },
        "turnoverPrior": {
          "type": "number",
          "description": "Previous year turnover. 0 for a first year."
        },
        "operatingCosts": {
          "type": "number",
          "description": "Total running costs for the year, expressed positive."
        },
        "operatingCostsPrior": {
          "type": "number",
          "description": "Previous year operating costs. 0 for a first year."
        },
        "fixedAssets": {
          "type": "number",
          "description": "Equipment and other fixed assets at net book value."
        },
        "fixedAssetsPrior": {
          "type": "number",
          "description": "Previous year fixed assets. 0 for a first year."
        },
        "cashAtBank": {
          "type": "number",
          "description": "Bank balance at the year end. Negative means an overdraft."
        },
        "cashAtBankPrior": {
          "type": "number",
          "description": "Previous year-end bank balance. 0 for a first year."
        },
        "debtors": {
          "type": "number",
          "description": "Money owed to the company at the year end."
        },
        "debtorsPrior": {
          "type": "number",
          "description": "Previous year debtors. 0 for a first year."
        },
        "creditorsWithinOneYear": {
          "type": "number",
          "description": "Money the company owes, due within a year, expressed positive. Includes director loans owed back."
        },
        "creditorsWithinOneYearPrior": {
          "type": "number",
          "description": "Previous year creditors. 0 for a first year."
        },
        "directorsLoan": {
          "default": 0,
          "type": "number",
          "description": "How much of the creditors above is owed to the company's own directors. Part of that figure, never an addition to it. Usually the largest line on a one-person company's sheet, and repayable to the director free of tax."
        },
        "directorsLoanPrior": {
          "default": 0,
          "type": "number",
          "description": "Previous year directors' loan. 0 for a first year."
        },
        "shareCapital": {
          "type": "number",
          "description": "Issued share capital or common stock, typically 1 to 100."
        },
        "shareCapitalPrior": {
          "type": "number",
          "description": "Previous year share capital. Usually the same as this year."
        }
      },
      "required": [
        "turnover",
        "turnoverPrior",
        "operatingCosts",
        "operatingCostsPrior",
        "fixedAssets",
        "fixedAssetsPrior",
        "cashAtBank",
        "cashAtBankPrior",
        "debtors",
        "debtorsPrior",
        "creditorsWithinOneYear",
        "creditorsWithinOneYearPrior",
        "directorsLoan",
        "directorsLoanPrior",
        "shareCapital",
        "shareCapitalPrior"
      ],
      "additionalProperties": false,
      "description": "The figures behind a small-company balance sheet. ALL amounts in major units."
    },
    "lastFiledAs": {
      "description": "What the last accounts were filed as, straight from lookup_company's company.lastAccountsType. Pass it through; do not guess it.",
      "type": "string"
    }
  },
  "required": [
    "jurisdiction",
    "figures"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false
}

The complete set of figures for a dormant company: share capital, the matching cash, and zeros everywhere else. The register says when the last accounts were filed dormant, and for those companies this collapses the whole form to one call. Amounts in major units.

{
  "type": "object",
  "properties": {
    "shareCapital": {
      "default": 1,
      "description": "Issued share capital in major units. 1 is the overwhelmingly common figure.",
      "type": "number",
      "exclusiveMinimum": 0
    }
  },
  "required": [
    "shareCapital"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false
}

Turn categorised bank-statement totals into balance sheet figures, applying the rules that stop an import lying: only income categories reach turnover, only expense categories reach operating costs, and the owner topping up the account is never sales. Totals are signed major units per category code; get codes from categorise_transactions.

{
  "type": "object",
  "properties": {
    "totals": {
      "type": "object",
      "propertyNames": {
        "type": "string"
      },
      "additionalProperties": {
        "type": "number"
      },
      "description": "Signed totals per category code, major units, e.g. {\"sales\": 60000, \"software\": -1200}."
    }
  },
  "required": [
    "totals"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false
}

What missing a Companies House accounts deadline costs. Given the due date, returns days remaining or overdue, the penalty band already incurred, and what the next band costs, the number that makes someone act today. UK private companies only.

{
  "type": "object",
  "properties": {
    "accountsDue": {
      "type": "string",
      "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
      "description": "The accounts due date, from lookup_company or a Companies House letter."
    }
  },
  "required": [
    "accountsDue"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false
}

The countries this server knows about and what it can actually do in each: which have a real accounts engine, which registers can be searched or looked up, the currency, and the identifiers each jurisdiction files under. Call this first when unsure.

{
  "type": "object",
  "properties": {},
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false
}

A real worked example: nil turnover, a director loan, a near-empty bank account, the simplest accounts the UK regime permits. Use it to demonstrate check_accounts or as a template for a first-year company. Amounts in major units.

{
  "type": "object",
  "properties": {},
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false
}

Look a company up on its public register (Companies House for GB, ABN Lookup for AU) by its registered number. Returns the full public record: name, status, registered office, officers, SIC codes, accounting period, plus both filing deadlines with days remaining and the late-filing penalty already incurred if overdue. Rate limited and quota-charged; cached results are free. Find the number first with search_companies.

{
  "type": "object",
  "properties": {
    "jurisdiction": {
      "default": "GB",
      "description": "ISO country code. Register access exists for GB and AU.",
      "type": "string",
      "enum": [
        "GB",
        "IE",
        "US",
        "AU"
      ]
    },
    "companyNumber": {
      "type": "string",
      "minLength": 1,
      "description": "The register identifier: GB company number (e.g. 15379140) or AU ABN."
    }
  },
  "required": [
    "jurisdiction",
    "companyNumber"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false
}

Find a company by name on its public register and get back its registered number, status and address. This is how you reach lookup_company when the person only knows the name. Free of the daily quota; lightly rate limited.

{
  "type": "object",
  "properties": {
    "jurisdiction": {
      "default": "GB",
      "description": "ISO country code. Register access exists for GB and AU.",
      "type": "string",
      "enum": [
        "GB",
        "IE",
        "US",
        "AU"
      ]
    },
    "query": {
      "type": "string",
      "minLength": 3,
      "description": "The company name, as someone would say it."
    }
  },
  "required": [
    "jurisdiction",
    "query"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false
}

Read last year's figures out of the company's last filed accounts at Companies House, ready to drop into the *Prior fields of check_accounts or save_filing. Saves typing seven numbers from a PDF and gets the comparatives exactly as filed. GB only, and only when the last accounts were filed digitally. Quota-charged; cached results are free.

{
  "type": "object",
  "properties": {
    "companyNumber": {
      "type": "string",
      "minLength": 1,
      "description": "The GB company number."
    }
  },
  "required": [
    "companyNumber"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false
}

A plain-English reading of a set of figures, written for a director who is not an accountant: what the derived balance sheet says about the company and anything that needs attention before filing. Only the derived sheet is sent to the model, no company name or number. Quota-charged; identical figures are answered from cache free.

{
  "type": "object",
  "properties": {
    "figures": {
      "type": "object",
      "properties": {
        "turnover": {
          "type": "number",
          "description": "Sales income for the year, in major currency units (pounds/euros/dollars)."
        },
        "turnoverPrior": {
          "type": "number",
          "description": "Previous year turnover. 0 for a first year."
        },
        "operatingCosts": {
          "type": "number",
          "description": "Total running costs for the year, expressed positive."
        },
        "operatingCostsPrior": {
          "type": "number",
          "description": "Previous year operating costs. 0 for a first year."
        },
        "fixedAssets": {
          "type": "number",
          "description": "Equipment and other fixed assets at net book value."
        },
        "fixedAssetsPrior": {
          "type": "number",
          "description": "Previous year fixed assets. 0 for a first year."
        },
        "cashAtBank": {
          "type": "number",
          "description": "Bank balance at the year end. Negative means an overdraft."
        },
        "cashAtBankPrior": {
          "type": "number",
          "description": "Previous year-end bank balance. 0 for a first year."
        },
        "debtors": {
          "type": "number",
          "description": "Money owed to the company at the year end."
        },
        "debtorsPrior": {
          "type": "number",
          "description": "Previous year debtors. 0 for a first year."
        },
        "creditorsWithinOneYear": {
          "type": "number",
          "description": "Money the company owes, due within a year, expressed positive. Includes director loans owed back."
        },
        "creditorsWithinOneYearPrior": {
          "type": "number",
          "description": "Previous year creditors. 0 for a first year."
        },
        "directorsLoan": {
          "default": 0,
          "type": "number",
          "description": "How much of the creditors above is owed to the company's own directors. Part of that figure, never an addition to it. Usually the largest line on a one-person company's sheet, and repayable to the director free of tax."
        },
        "directorsLoanPrior": {
          "default": 0,
          "type": "number",
          "description": "Previous year directors' loan. 0 for a first year."
        },
        "shareCapital": {
          "type": "number",
          "description": "Issued share capital or common stock, typically 1 to 100."
        },
        "shareCapitalPrior": {
          "type": "number",
          "description": "Previous year share capital. Usually the same as this year."
        }
      },
      "required": [
        "turnover",
        "turnoverPrior",
        "operatingCosts",
        "operatingCostsPrior",
        "fixedAssets",
        "fixedAssetsPrior",
        "cashAtBank",
        "cashAtBankPrior",
        "debtors",
        "debtorsPrior",
        "creditorsWithinOneYear",
        "creditorsWithinOneYearPrior",
        "directorsLoan",
        "directorsLoanPrior",
        "shareCapital",
        "shareCapitalPrior"
      ],
      "additionalProperties": false,
      "description": "The figures behind a small-company balance sheet. ALL amounts in major units."
    },
    "jurisdiction": {
      "default": "GB",
      "description": "ISO country code. Register access exists for GB and AU.",
      "type": "string",
      "enum": [
        "GB",
        "IE",
        "US",
        "AU"
      ]
    }
  },
  "required": [
    "figures",
    "jurisdiction"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false
}

Categorise bank-statement transaction descriptions into the fixed vocabulary this product maps to balance sheet lines (sales, software, owner-in, …). Send description strings only, never amounts or dates. Sum the amounts per returned category yourself, then call totals_to_figures. One statement import is one quota unit; previously seen descriptions are answered from a shared cache free.

{
  "type": "object",
  "properties": {
    "tradingType": {
      "default": "other",
      "description": "What the company does, to resolve ambiguous merchants. One of: software, consulting, creative, retail, construction, property, hospitality, other. lookup_company suggests one from the SIC codes.",
      "type": "string"
    },
    "descriptions": {
      "minItems": 1,
      "maxItems": 2000,
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "The raw description strings, one per transaction."
    }
  },
  "required": [
    "tradingType",
    "descriptions"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false
}

Whether a company can still apply to its registrar for more time to file, how many days are left to apply, and what being late costs if that window is missed. This is usually the most useful thing to tell somebody who has just found a deadline: applying is free, takes about 15 minutes, and has to be done BEFORE the deadline it extends, so the option expires on the same day the penalty starts. Returns nextAction first. It PREPARES an application and can never submit one: the application is made by a director on the registrar’s own service, which this tool links to. It does not file accounts. Give a company number to read the deadline off the register (quota-charged, cached results free), or give the dates yourself and it costs nothing.

{
  "type": "object",
  "properties": {
    "jurisdiction": {
      "default": "GB",
      "description": "ISO country code. Register access exists for GB and AU.",
      "type": "string",
      "enum": [
        "GB",
        "IE",
        "US",
        "AU"
      ]
    },
    "filing": {
      "default": "accounts",
      "description": "Which deadline. Only accounts can be extended; ask about the other and it says so.",
      "type": "string",
      "enum": [
        "accounts",
        "confirmation-statement"
      ]
    },
    "companyNumber": {
      "description": "Read the deadline and period end off the register. Omit if you supply the dates.",
      "type": "string",
      "minLength": 1
    },
    "filingDeadline": {
      "description": "The normal filing deadline, if you already have it. Skips the register request.",
      "type": "string",
      "pattern": "^\\d{4}-\\d{2}-\\d{2}$"
    },
    "periodEnd": {
      "description": "The accounting reference date. Bounds how much extra time could be granted.",
      "type": "string",
      "pattern": "^\\d{4}-\\d{2}-\\d{2}$"
    },
    "alreadyExtended": {
      "default": false,
      "description": "True if this deadline has been extended once already. Do not guess it, ask.",
      "type": "boolean"
    },
    "today": {
      "description": "Defaults to the server's date. Supply it to test a boundary.",
      "type": "string",
      "pattern": "^\\d{4}-\\d{2}-\\d{2}$"
    }
  },
  "required": [
    "jurisdiction",
    "filing",
    "alreadyExtended"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false
}

Turn a short factual account of what went wrong into the reason text for an application for more time to file accounts, framed in the terms the registrar actually applies. It uses only the facts you give it: it will not invent circumstances, and where something is missing it leaves a bracketed placeholder rather than filling it in. The person must check every sentence before using it, because they are certifying it to the registrar. Ask them what happened, do not supply it yourself. This tool does not submit the application and does not file accounts. Quota-charged as an explanation; identical input is answered from cache free.

{
  "type": "object",
  "properties": {
    "jurisdiction": {
      "default": "GB",
      "description": "ISO country code. Register access exists for GB and AU.",
      "type": "string",
      "enum": [
        "GB",
        "IE",
        "US",
        "AU"
      ]
    },
    "circumstances": {
      "type": "string",
      "minLength": 40,
      "maxLength": 2000,
      "description": "What actually happened, in the person's own words, with dates. Facts only. If you do not have this, ask them for it rather than writing it."
    },
    "whyItStoppedTheAccounts": {
      "description": "How the event stopped the accounts being prepared, if they have said.",
      "type": "string",
      "maxLength": 1000
    },
    "expectedReadyBy": {
      "description": "When they expect the accounts to be ready, if they have said. Never estimate it.",
      "type": "string",
      "pattern": "^\\d{4}-\\d{2}-\\d{2}$"
    }
  },
  "required": [
    "jurisdiction",
    "circumstances"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false
}

The user's saved filings, most recently touched first, with every figure in major units. This is the same list the website dashboard shows. Start here when asked about "my accounts" or "my company".

{
  "type": "object",
  "properties": {},
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false
}

Save a set of figures to the user's account, or update a saved one by passing its id from list_saved_filings. Figures in major units. The filing is saved even when validation finds problems, because a work in progress is worth keeping, and the problems come back in the response so you can raise them.

{
  "type": "object",
  "properties": {
    "id": {
      "description": "Omit to create. Pass an id from list_saved_filings to update that filing.",
      "type": "integer",
      "minimum": -9007199254740991,
      "maximum": 9007199254740991
    },
    "jurisdiction": {
      "default": "GB",
      "type": "string",
      "enum": [
        "GB",
        "IE",
        "US",
        "AU"
      ]
    },
    "label": {
      "description": "A name for the filing, e.g. \"SparkGames year to 31 Dec 2025\".",
      "type": "string"
    },
    "identifiers": {
      "description": "Register identifiers, e.g. {\"companyNumber\": \"15379140\"}. Tax references (UTR, EIN, TFN) are never stored and are silently dropped.",
      "type": "object",
      "propertyNames": {
        "type": "string"
      },
      "additionalProperties": {
        "type": "string"
      }
    },
    "figures": {
      "type": "object",
      "properties": {
        "turnover": {
          "type": "number",
          "description": "Sales income for the year, in major currency units (pounds/euros/dollars)."
        },
        "turnoverPrior": {
          "type": "number",
          "description": "Previous year turnover. 0 for a first year."
        },
        "operatingCosts": {
          "type": "number",
          "description": "Total running costs for the year, expressed positive."
        },
        "operatingCostsPrior": {
          "type": "number",
          "description": "Previous year operating costs. 0 for a first year."
        },
        "fixedAssets": {
          "type": "number",
          "description": "Equipment and other fixed assets at net book value."
        },
        "fixedAssetsPrior": {
          "type": "number",
          "description": "Previous year fixed assets. 0 for a first year."
        },
        "cashAtBank": {
          "type": "number",
          "description": "Bank balance at the year end. Negative means an overdraft."
        },
        "cashAtBankPrior": {
          "type": "number",
          "description": "Previous year-end bank balance. 0 for a first year."
        },
        "debtors": {
          "type": "number",
          "description": "Money owed to the company at the year end."
        },
        "debtorsPrior": {
          "type": "number",
          "description": "Previous year debtors. 0 for a first year."
        },
        "creditorsWithinOneYear": {
          "type": "number",
          "description": "Money the company owes, due within a year, expressed positive. Includes director loans owed back."
        },
        "creditorsWithinOneYearPrior": {
          "type": "number",
          "description": "Previous year creditors. 0 for a first year."
        },
        "directorsLoan": {
          "default": 0,
          "type": "number",
          "description": "How much of the creditors above is owed to the company's own directors. Part of that figure, never an addition to it. Usually the largest line on a one-person company's sheet, and repayable to the director free of tax."
        },
        "directorsLoanPrior": {
          "default": 0,
          "type": "number",
          "description": "Previous year directors' loan. 0 for a first year."
        },
        "shareCapital": {
          "type": "number",
          "description": "Issued share capital or common stock, typically 1 to 100."
        },
        "shareCapitalPrior": {
          "type": "number",
          "description": "Previous year share capital. Usually the same as this year."
        }
      },
      "required": [
        "turnover",
        "turnoverPrior",
        "operatingCosts",
        "operatingCostsPrior",
        "fixedAssets",
        "fixedAssetsPrior",
        "cashAtBank",
        "cashAtBankPrior",
        "debtors",
        "debtorsPrior",
        "creditorsWithinOneYear",
        "creditorsWithinOneYearPrior",
        "directorsLoan",
        "directorsLoanPrior",
        "shareCapital",
        "shareCapitalPrior"
      ],
      "additionalProperties": false,
      "description": "The figures behind a small-company balance sheet. ALL amounts in major units."
    },
    "categoryTotals": {
      "description": "Where the figures came from, when a bank statement fed them: signed major-unit totals per category code from categorise_transactions.",
      "type": "object",
      "propertyNames": {
        "type": "string"
      },
      "additionalProperties": {
        "type": "number"
      }
    }
  },
  "required": [
    "jurisdiction",
    "figures"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false
}

Delete one saved filing by id, permanently. Confirm with the person before calling this; there is no undo and no trash.

{
  "type": "object",
  "properties": {
    "id": {
      "type": "integer",
      "minimum": -9007199254740991,
      "maximum": 9007199254740991,
      "description": "The id from list_saved_filings."
    }
  },
  "required": [
    "id"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false
}

Watch a company by its register number and get reminded before its filing deadlines. Which channels are actually available depends on the server: the reply reports what will really be sent, and it can be nothing at all, so read it rather than assuming. No saved filing is needed: this is for the deadline itself, which matters months before any figures exist. Reminders go out on a ladder of days before the deadline (default 90, 60, 30, 14, 7, 1), and each one states the company, the deadline, the date, the days remaining and the penalty for missing it. Calling this again updates the settings and un-mutes a company that was untracked.

{
  "type": "object",
  "properties": {
    "jurisdiction": {
      "default": "GB",
      "description": "ISO country code. Deadline reminders exist where the register publishes deadlines.",
      "type": "string",
      "enum": [
        "GB",
        "IE",
        "US",
        "AU"
      ]
    },
    "companyNumber": {
      "type": "string",
      "minLength": 1,
      "description": "The register identifier: GB company number (e.g. 15379140) or AU ABN."
    },
    "email": {
      "default": true,
      "description": "Send reminders to the account email address.",
      "type": "boolean"
    },
    "push": {
      "default": true,
      "description": "Send reminders as web push to signed-in browsers.",
      "type": "boolean"
    },
    "remindDaysBefore": {
      "description": "Days before the deadline to warn, e.g. [60, 14, 1]. Omit to use this server’s default ladder. Only the tightest rung that applies is ever sent, so a long ladder does not mean a burst of messages.",
      "maxItems": 12,
      "type": "array",
      "items": {
        "type": "integer",
        "minimum": 1,
        "maximum": 3650
      }
    }
  },
  "required": [
    "jurisdiction",
    "companyNumber",
    "email",
    "push"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false
}

Every company this user gets deadline reminders about, including the ones implied by their saved filings. Shows the next accounts deadline and days remaining where a register record is already cached. Free: this never contacts a register.

{
  "type": "object",
  "properties": {},
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false
}

Stop sending deadline reminders about a company. This mutes rather than forgets, which is the only thing that holds: a company implied by a saved filing would otherwise be re-added by the next scan. track_company_deadlines un-mutes it again.

{
  "type": "object",
  "properties": {
    "jurisdiction": {
      "default": "GB",
      "description": "ISO country code. Deadline reminders exist where the register publishes deadlines.",
      "type": "string",
      "enum": [
        "GB",
        "IE",
        "US",
        "AU"
      ]
    },
    "companyNumber": {
      "type": "string",
      "minLength": 1,
      "description": "The register identifier, as in track_company_deadlines."
    }
  },
  "required": [
    "jurisdiction",
    "companyNumber"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false
}

What this deployment can actually do right now: which integrations are configured, whether your token is valid, and how much of each daily quota you have left. Call it when a tool refuses and you want to know whether the feature is off or used up.

{
  "type": "object",
  "properties": {},
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false
}