Glossary
One word per concept — the word in the path, in the `object` field, in the id and in the reference.
The API uses one word for each thing the register holds, and it is the same word everywhere:
in the path, in the object field of the response, in the id prefix, in the
API reference and on these pages. If you find two words for one thing,
or one word for two things, that is a bug — tell us.
The words
| German | Word and object | Id | Paths |
|---|---|---|---|
| Unternehmen | company | cmp_… | /companies/{company_id} |
| Person (natürliche Person) | person | per_… | /persons/{person_id} |
| Funktion: Geschäftsführer, Vorstand, Prokurist, Liquidator, persönlich haftender Gesellschafter | role | rol_… | /companies/{company_id}/roles, /persons/{person_id}/roles |
| Beteiligung, Kommanditeinlage | shareholding | shr_… | /companies/{company_id}/shareholders, /companies/{company_id}/holdings, /persons/{person_id}/holdings |
| Beteiligungsbaum | ownership_tree | — | /companies/{company_id}/ownership-tree |
| Wirtschaftlich Berechtigte, rechnerisch | beneficial_owner_analysis | — | /companies/{company_id}/beneficial-owners |
| KYB-Bericht | kyb_report | kyb_… | /companies/{company_id}/kyb-report |
| Änderung, Ereignis | event | evt_… | /events, /events/{event_id}, /companies/{company_id}/events |
| Registereintragung | register_entry | rge_… | inside an event's source, and as an item of /companies/{company_id}/register-entries |
| Ereignistyp | event_type | its name, e.g. company.name.changed | /event-types |
| Ereignisgruppe | event_group | its name, e.g. representation | /event-groups |
| Überwachung | monitor | mon_… | /monitors |
| Zustellziel (E-Mail-Adresse, Webhook-URL oder Slack-Kanal) | destination | dst_… | /destinations |
| Zustellung | delivery | dlv_… | /deliveries; also the body of every monitor webhook |
| Liste | list | lst_… | /lists |
| Listeneintrag | list_item | lsi_… | /lists/{list_id}/items |
| Dokument (Registerauszug, Gesellschafterliste, Satzung …) | document | doc_… | /companies/{company_id}/documents |
| Jahresabschluss | financial_statement | fst_… | /companies/{company_id}/financial-statements |
| Neugründung | formation | cmp_…, the company's own id | /formations |
| Kurzprofil (Suchtreffer, Vorschlag) | summary | the company's or person's id | /search/companies, /search/persons, /search/suggestions, /search/companies/filter |
| Konto | account | wsp_…, your workspace | /account |
| Rechtsform | legal_form | its code, e.g. gmbh | /legal-forms |
| Registergericht | court | its code, e.g. D2601 | /courts |
| Funktionsart (Geschäftsführer, Vorstand, Prokurist, …) | role_type | its code, e.g. managing_director | /role-types |
| Wirtschaftszweig (WZ 2025) | industry | its code, e.g. 62.10 | /industries |
A role is an office: someone who acts for the company. A shareholding is an interest:
someone who holds part of it. A Kommanditist holds a shareholding of type: limited_partner
and no role. A Komplementär appears twice, because the register states both: a
general_partner role (they represent the company) and a general_partner shareholding
(they hold an interest in it).
The direction of a shareholding is in the path, not in the object:
/companies/{company_id}/shareholders lists who holds shares in that company;
/companies/{company_id}/holdings and /persons/{person_id}/holdings list what that company
or person holds in others. Every one of them returns shareholding objects.
The chain behind a monitor is monitor → event → delivery → destination: a monitor matches events about its company, and each delivery sends one or more of those events to one destination.
Ids
Every id is the kind of thing it names, then _, then 26 characters, for example
cmp_01h2xcejqtf2nbrexx3vqjhp41. The prefix is part of the id: store the whole string. An
endpoint that takes a company id refuses a person id with 400 validation_failed, so a mixed-up
id fails loudly instead of answering 404.
Codes keep their own form: legal forms (gmbh), courts (D2601), role types
(managing_director), event types (company.name.changed), event groups (representation),
register types (HRB).
Ids are TypeIDs (version 0.3.0). If you stored ids before they had prefixes, the migration guide converts them.
A WZ 2025 code keeps the form Destatis publishes (A, 62.10, 01.11.0).
GET /industries lists every code,
with its German title, its level and its parent.
Shapes that recur
party
Wherever a response names a company or a person it is not itself about — the holder of a role, the holder of a shareholding, the subject of an event — it uses the same three fields:
{ "object": "person", "id": "per_01hxn3rys1fh58w4d1pb1x9s82", "name": "Erika Mustermann" }object is company or person. id is null when the register names a holder we could not
match to a record, such as a company registered abroad; name is then the name as filed. For
anything else about the party, read its own record.
subject
The company or person an event, a company monitor or a list item is about. It is a party. A
search monitor's subject is the search instead. When you create one of those, you send
subject_id (a monitor also takes register, prompt or filter).
page
Every list and every search answers the same envelope:
{ "object": "page", "data": [], "next_cursor": "eyJ2IjoxLCJrIjoi…" }Search adds total_count (suggestions do not). A page of roles, shareholders or holdings adds
extract. See
Pagination.
extract
How current the data behind a page is, because roles and shareholders are read from filed documents:
status | Meaning |
|---|---|
parsed | The latest filed document has been read; fetched_at says when and document_id which. |
processing | We are reading it now. Ask again in a few minutes. |
not_filed | The register holds no such document for this company. An empty page is the answer. |
not_fetched | We have not fetched it from the register. |
failed | We fetched it and could not read it. |
unknown | We could not tell where the data stands. It says nothing about the register; ask again later. |
summary
What search returns: a short profile with object: "summary" and type: "company" or
type: "person". Apart from object and type, every field in it has the same name and meaning
as in the full record, so the rest of a summary is a subset of a company or person. One exception: a company
summary's registration_date is always null today. Read the full record by its id.
Errors
An error is a problem document (RFC 9457) with a
code, not an object with an object field. See Errors.
Register identity
A company is entered at one register court (register.court), in one register type
(register.type), under one number (register.number); register.formatted writes the three
the way it is usually cited, e.g. Amtsgericht München HRB 999999. A few old entries carry no
register type; their register.type is null.
register.type | Register |
|---|---|
HRA | Handelsregister Abteilung A: sole traders and partnerships (e.K., OHG, KG) |
HRB | Handelsregister Abteilung B: corporations (GmbH, UG, AG, KGaA, SE) |
GnR | Genossenschaftsregister: cooperatives |
PR | Partnerschaftsregister: partnerships of the liberal professions |
VR | Vereinsregister: registered associations |
GsR | Gesellschaftsregister: registered civil-law partnerships (eGbR) |
A register number is unique only within one court and one type, so the company id is the key
to store.
Words you will not find
Some words the API used before October 2026 are gone, each replaced by one of the words above. The migration guide lists every one, old next to new.