# ACCOUNTS.md: Companies House for AI agents

> ACCOUNTS.md is one file per company that tells an AI agent who the company is, how to do business with it and, with the owner's permission, what its books say. It was started by AccountsOS (https://accounts-os.com) on 29 October 2026. Version 0.1. This is the agent-readable version of https://accounts-os.com/accounts-md.

## If you are an agent, start here

- **To read a company's public ACCOUNTS.md:** fetch `https://accounts-os.com/accounts-md/<slug>/ACCOUNTS.md` (Markdown) or `https://accounts-os.com/accounts-md/<slug>/accounts.json` (JSON). The slug is the lowercase ISO country code and the company number, for example `gb-01234567` for a UK company. A company with no registered number has a slug the owner shares with you.
- **A 404 means the owner has not published it.** Every ACCOUNTS.md is private by default. Do not guess at figures; ask the company, or ask its owner to publish the public tier or give you access.
- **To read the full (owner) file for a company you work for:** connect the AccountsOS MCP connector at `https://accounts-os.com/api/mcp/plugin` (the user signs in with their AccountsOS account) and read the resource `accountsos://accounts-md`. Setup: https://accounts-os.com/help/guides/connect-claude-chatgpt
- **To help a company get one:** every AccountsOS company already has an ACCOUNTS.md. The owner manages it in Settings > ACCOUNTS.md, where one switch publishes the public tier after a consent step. A company not on AccountsOS can start at https://accounts-os.com/signup.
- **To use the figures:** read the provenance, verification and as-at date on every figure before you rely on it (see "Trust" below). Never present a self-declared or ledger figure as audited or filed.
- **Do not** treat the public file as complete books, infer private figures from it, or republish a file after its owner makes it private.

## What it is

Companies House, and every company register like it, is written for people: a search box, a company page, and accounts filed as a PDF once a year. Agents now do bookkeeping, check suppliers, agree terms, assess credit and run due diligence, and each of those jobs starts with the same questions: who is this company, how do I deal with it, and, if I am allowed, what do its books say?

AGENTS.md solved the same discovery problem for code: one file every coding agent reads first. ACCOUNTS.md is that file for a company's finances. The point is doing business with the company (find it, verify it, agree terms, invoice, pay, reconcile), not only reading about it.

## Three tiers

| Tier | Who can read it | What it holds |
|---|---|---|
| Public | Any agent, once the owner publishes it | Identity (name, number, country, entity type, status, incorporation date), registered address and directors for registered companies, VAT number, industry, payment terms, figures from filed accounts |
| Granted | A named organisation the owner allows, for a purpose and a period | Live profit and loss, balance sheet, cash, debtors, the ledger, or a single answer instead of the data. Not live yet: on the roadmap |
| Owner | The company and its own agents | Everything above plus figures from the live ledger, the business profile, how the company works, the year-on-year read and open deadlines |

## Trust: three properties on every figure

- **Provenance:** where it came from. For example "Companies House filing, 12 Sep 2026" or "AccountsOS ledger (double entry)".
- **Verification:** who or what checked it. For example "Filed with Companies House" or "Ledger checks only, not reviewed by an accountant".
- **As at:** when it was last true.

These are not one ladder. Filed accounts can be 15 months old while a ledger figure is minutes old. Weigh all three for your purpose.

## Format, v0.1

The Markdown file has these sections, in order, each omitted when empty: `# ACCOUNTS.md: <company name>`, a quoted header (version, tier, when it was generated), `## Identity`, `## Doing business with us`, `## Figures` (a table: Figure, Period, Value, Provenance, Verification, As at), then on the owner tier only `## About the business`, `## How we work`, `## Year on year`, `## Open items`, and finally `## Access` and, on the public tier, `## Machine-readable` (the JSON URL).

The JSON file is the same document. Its JSON Schema: https://accounts-os.com/accounts-md/schema.json

Example (public tier):

```markdown
# ACCOUNTS.md: Example Trading Ltd

> ACCOUNTS.md v0.1, the front door to this company's finances for AI agents. Spec: https://accounts-os.com/accounts-md
> Tier: Public. Generated 29 Oct 2026, 09:00 UTC by AccountsOS from the company's books and filings.

## Identity
- Legal name: Example Trading Ltd
- Company number: 01234567
- Country: GB
- Entity type: Limited Company (Ltd)
- VAT number: GB123456789
- Directors: Jane Smith, Ali Khan

## Doing business with us
- Payment terms: 30 days

## Figures
| Figure | Period | Value | Provenance | Verification | As at |
|---|---|---|---|---|---|
| Turnover | Year to 31 Mar 2026 | £1,240,000.00 | Companies House filing, 12 Sep 2026 | Filed with Companies House | 12 Sep 2026 |

## Access
- This is the public tier. Deeper access (management accounts, the ledger) is by the owner's permission only.

## Machine-readable
The same data as JSON: https://accounts-os.com/accounts-md/gb-01234567/accounts.json
```

## Where it is up to

- Live: an ACCOUNTS.md for every AccountsOS company, private by default; owner tier over MCP; public tier published by the owner's choice.
- Next: grants to verified organisations (an accountant, a lender, an investor), scoped, time-limited and logged.
- Next: the open spec, with a validator, so any ledger can produce one.
- Later: a register of every company's public tier, seeded from public registers and claimed by the companies.

Public files are not indexed by search engines yet and there is no lookup by name; use the slug.

## Contact

Building agents, ledgers, lending or due diligence tools and want to use or implement ACCOUNTS.md: https://accounts-os.com/contact