Glossary

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

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), 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.

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_01h455vb4pex5vsknk084sn02q", "name": "Mario Richter" }

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 monitor or a list item is about. It is a party. When you create one of those, you send subject_id.

page

Every list and every search answers the same envelope:

{ "object": "page", "data": [], "next_cursor": "eyJ2IjoxLCJrIjoi…" }

Search adds total_count. A page of shareholders adds extract. See Pagination.

extract

How current the data behind a page is, because shareholders are read from filed documents:

summary

What search returns: a short profile with object: "summary" and type: "company" or type: "person". Every field in it has the same name and meaning as in the full record, so a summary is a strict subset of a company or person. 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 292661. A few old entries carry no register type; their register.type is null.

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.