The data model
The six things this API talks about, and what each one actually means.
The German commercial register is not a database. It is ~170 courts keeping their own books, in prose, with their own conventions. Everything this API returns is an interpretation of those books, and the words below mean something specific.
Reading this page once will save you from most of the surprises.
Company
A company is one entry in one court's register — identified by court, register
prefix (HRA, HRB, GnR, PR, VR) and register number.
That is narrower than "a business". A group with branches registered at three courts is
three companies here, each with its own id, because that is how the register holds it.
Siemens Aktiengesellschaft Zweigniederlassung Rostock is a separate register entry from
Siemens Aktiengesellschaft.
Each company has a stable id (a UUID). Register numbers are not unique on their own
— HRB 670 exists at most courts — so the id is the only safe key to store.
Person
A person is a natural person named in a register entry: a managing director, a board member, a holder of Prokura, a shareholder, a partner.
Register entries name people by name, and frequently by name and city and date of birth. People are matched across companies where the register gives enough to match on. Where it does not, the same human may appear as two persons. Treat a person id as "this named role holder", not as a verified identity.
Role
A role joins a person to a company for a period: Geschäftsführer, Vorstand,
Prokurist, Liquidator, persönlich haftender Gesellschafter. Roles start and end,
and the register records both, so a role that has ended is still part of the record.
Shareholding
A shareholding is a stake one party holds in a company, taken from the shareholder list (Gesellschafterliste) a GmbH must file. The holder may be a person or another company — which is what makes ownership chains possible.
Shareholder lists are filed as documents, not as data. What you get back is what was extracted from the most recent filed list, which may be years old, and which may not exist at all. See Ownership.
Document
A document is a filing: the register extract (Registerauszug), the list of shareholders, the articles of association, an annual account. Documents are fetched from the register on demand and extracted into data.
Event
An event is a detected change to a company: a new name, a new address, a change of capital, a director appointed or removed. Events are what a monitoring subscription delivers.
Two words that mean less than you think
`status` and `is_active`
These describe the register entry, not the business. A company whose entry has been
deleted (gelöscht) is TERMINATED. A company in liquidation is still ACTIVE — the
entry is live, the business is winding up. And be aware that the company record endpoint
and the search endpoint currently derive this field differently and disagree; see
Companies.