The data model
The things this API talks about, what each one means, and how they connect.
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. Each word is used for one
thing only, in the paths, the object field, the ids and the reference; the
glossary lists them side by side.
What the register holds
Company
A company (cmp_…) is one entry in one court's register — identified by court, register
type (HRA, HRB, GnR, PR, VR, GsR) 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.
Register numbers are not unique on their own — HRB 670 exists at most courts — so the id is
the only safe key to store. See Companies.
Person
A person (per_…) 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 holder", not as a verified identity. See Persons.
Role
A role (rol_…) is an office a person or a company holds at a company: 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, with
status: former. The same role object is listed from both sides:
/companies/{company_id}/roles and /persons/{person_id}/roles.
Shareholding
A shareholding (shr_…) is an interest one party holds in a company, taken from the
shareholder list (Gesellschafterliste) a GmbH must file, or from the register entry of a
partnership. The holder may be a person or another company — which is what makes ownership
chains possible. A Kommanditist's interest is a shareholding with type: limited_partner.
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; the page's extract says which. The ownership tree
(/companies/{company_id}/ownership-tree) follows linked companies for up to three levels
and computes each holder's effective percentage along that path.
GET /companies/{company_id}/beneficial-owners
is the separate computation of beneficial owners from those filings. See Ownership.
Document
A document (doc_…) is a filing: the register extract (Registerauszug), the list of
shareholders, the articles of association. Documents are fetched from the register and
extracted into data.
Financial statement
A financial statement (fst_…) is a filed set of annual accounts (Jahresabschluss) and
the figures extracted from it. See Financial statements.
Event
An event (evt_…) is one change to a company: a new name, a new address, a change of
capital, a managing director appointed or removed. Its type says which change
(company.name.changed); its subject is the company; its data holds what changed, shaped
by the type; its source is the register entry (Eintragung, rge_…) it was read from.
One register entry often states several changes — a new managing director, a new address and
new articles in one Eintragung — so one register entry can be the source of several events.
Read them across all companies at /events, or for one company at
/companies/{company_id}/events.
Formation
A formation is a company that was just entered for the first time (Neugründung). It is
addressed by its company's cmp_… id. See
Follow new formations.
What you create
These belong to your workspace, and reading or changing them is free.
- A monitor (
mon_…) watches one company for the event types you choose. - A destination (
dst_…) is where matched events are sent: an e-mail address, a webhook URL or a Slack channel, with a cadence. - A delivery (
dlv_…) is one send of one or more events to one destination. A webhook body is a delivery. The chain is monitor → event → delivery → destination; see Monitoring and Webhooks. - A list (
lst_…) is your own set of companies and persons, each one a list item (lsi_…).
How they connect
Every reference from one object to a company or person is a party:
{object, id, name}. A role's holder, a shareholding's holder and an event's subject
all have that shape, so one piece of code reads them all. Follow the id to the full record.
Every list answers a page, {object: "page", data, next_cursor}, and search answers a page
of summaries: short profiles whose fields are a strict subset of the full record. See Pagination.
A word that means less than you think
`status`
status describes the register entry, not the business. It is one of four lowercase
values: active, liquidation (the entry is live, the company is being wound up),
terminated (the entry has been deleted, gelöscht) or unknown (the register data does
not say). The company record, search results, suggestions and the structured filter derive
it with the same rule, so a company has the same status wherever you read it; see
Companies.