Daten

DATEN

shareholders_deep

Max

Tiefe Gesellschafter (shareholders_deep) zeigt, wer an einem Unternehmen beteiligt ist: mit welchem Anteil, mit welchen Geschäftsanteilen und deren Nummern, seit wann jemand verzeichnet ist und was sich mit der jüngsten Gesellschafterliste geändert hat, dazu die früheren Listen. Grundlage sind die beim Handelsregister eingereichten Gesellschafterlisten und Gründungsdokumente.

Nur mit Max: 80 Credits pro Abruf, zusätzlich zum Grundpreis von 5 Credits. Die 80 Credits fallen nur an, wenn aktuelle Gesellschafter geliefert werden. Im API-Playground ausprobieren →

Abruf

Ergänze Deinen Abruf von fetch-organization um feature=shareholders_deep und übergib als q die entity_id des Unternehmens.

cURL

curl -G 'https://handelsregister.ai/api/v1/fetch-organization' \
     -H 'x-api-key: YOUR_API_KEY' \
     --data-urlencode 'q=b4a3c2d1e5f697887a6b5c4d3e2f1a0b' \
     --data-urlencode 'feature=shareholders_deep'

Situation	Antwort	Credits für das Feature
Nicht angefragt oder Dein Plan ist nicht Max	kein Schlüssel shareholders_deep	0
Keine aktuellen Angaben zu Gesellschaftern, etwa bei einer AG	"shareholders_deep": null	0
Sonst	der Block wie unten beschrieben	80, bei leerem entries 0

Beispiel

{
  "entity_id": "b4a3c2d1e5f697887a6b5c4d3e2f1a0b",
  "name": "Beispielwerk Analytics GmbH",
  "shareholders_deep": {
    "record": {"date": "2025-03-15", "source": "SHAREHOLDER_LIST"},
    "share_capital": {"value": 50000, "currency": "EUR",
                      "basis": "REPORTED"},
    "entries": [
      {
        "holder": {
          "entity_id": "d4c3b2a1f6e5a7b8c9d0e1f2a3b4c5d6",
          "type": "ORGANIZATION",
          "name": "Beispielwerk Holding GmbH",
          "legal_form": "GmbH",
          "status": "ACTIVE",
          "city": "München",
          "country": "DEU",
          "registration": {"court": "München",
                           "register_type": "HRB",
                           "register_number": "12345"},
          "registration_text": null
        },
        "role": "SHAREHOLDER",
        "ownership": {
          "percentage": 75,
          "percentage_basis": "REPORTED",
          "nominal_amount": {"value": 37500, "currency": "EUR"},
          "share_count": 2,
          "share_ranges": [
            {"from": 2, "to": 2, "count": 1,
             "nominal_value": {"value": 12500, "currency": "EUR"}},
            {"from": 3, "to": 3, "count": 1,
             "nominal_value": {"value": 25000, "currency": "EUR"}}
          ]
        },
        "since": "2025-03-15",
        "since_basis": "ENTRY_RECORDED"
      },
      {
        "holder": {
          "entity_id": "f1e2d3c4b5a69788a7b6c5d4e3f2a1b0",
          "type": "PERSON",
          "name": "Max Mustermann",
          "birth_date": "1985-07-14",
          "city": "München",
          "country": "DEU"
        },
        "role": "SHAREHOLDER",
        "ownership": {
          "percentage": 25,
          "percentage_basis": "REPORTED",
          "nominal_amount": {"value": 12500, "currency": "EUR"},
          "share_count": 1,
          "share_ranges": [
            {"from": 1, "to": 1, "count": 1,
             "nominal_value": {"value": 12500, "currency": "EUR"}}
          ]
        },
        "since": "2019-06-03",
        "since_basis": "EARLIEST_RECORD"
      }
    ],
    "history": [
      {
        "record": {"date": "2019-06-03",
                   "source": "SHAREHOLDER_LIST"},
        "share_capital": {"value": 25000, "currency": "EUR",
                          "basis": "REPORTED"},
        "entries": [
          {
            "holder": {
              "entity_id": "f1e2d3c4b5a69788a7b6c5d4e3f2a1b0",
              "type": "PERSON",
              "name": "Max Mustermann",
              "birth_date": "1985-07-14",
              "city": "München",
              "country": null
            },
            "role": "SHAREHOLDER",
            "ownership": {
              "percentage": 100,
              "percentage_basis": "REPORTED",
              "nominal_amount": {"value": 25000,
                                 "currency": "EUR"},
              "share_count": 2,
              "share_ranges": [
                {"from": 1, "to": 2, "count": 2,
                 "nominal_value": {"value": 12500,
                                   "currency": "EUR"}}
              ]
            },
            "since": "2019-06-03",
            "since_basis": "EARLIEST_RECORD"
          }
        ]
      }
    ],
    "changes": {
      "compared_to": "2019-06-03",
      "joined": [
        {
          "holder": {
            "entity_id": "d4c3b2a1f6e5a7b8c9d0e1f2a3b4c5d6",
            "type": "ORGANIZATION",
            "name": "Beispielwerk Holding GmbH"
          },
          "percentage": 75
        }
      ],
      "left": [],
      "changed": [
        {
          "holder": {
            "entity_id": "f1e2d3c4b5a69788a7b6c5d4e3f2a1b0",
            "type": "PERSON",
            "name": "Max Mustermann"
          },
          "percentage_before": 100,
          "percentage_after": 25
        }
      ]
    }
  }
}

Felder

shareholders_deep

Schlüssel	Typ	Beschreibung
record	object	Woher der aktuelle Stand stammt: {date, source}. date ist das Datum des Dokuments, bei COMMERCIAL_REGISTER null.
share_capital	object \| null	Stammkapital laut diesem Dokument: {value, currency, basis}. null, wenn es sich weder ablesen noch berechnen lässt, und bei COMMERCIAL_REGISTER.
entries	array<object>	Die aktuellen Gesellschafter, der größte Anteil zuerst. Ein Eintrag je Zeile des Dokuments: Wer mehrere Zeilen hat, erscheint mehrfach.
history	array<object>	Die übrigen Dokumente, das jüngste zuerst, jeweils mit record, share_capital und entries. Gesellschafter aus Dokumenten stehen darin so, wie sie damals gedruckt waren (status null).
changes	object \| null	Was sich gegenüber dem vorherigen Dokument geändert hat. null, wenn es keines gibt oder record.source nicht SHAREHOLDER_LIST ist.

entries[]

Schlüssel	Typ	Beschreibung
holder	object	Wer den Anteil hält, siehe holder.
role	enum	In welcher Rolle, siehe Werte.
ownership	object	Wie viel, siehe ownership.
since	string \| null	Ab wann der Gesellschafter ohne Unterbrechung verzeichnet ist. Ändert sich nur sein Anteil, bleibt since gleich. Bei JOINT immer null.
since_basis	enum \| null	Wie sicher since ist, siehe Werte. null, wenn since null ist.
until	string \| null	Nur im COMMERCIAL_REGISTER-Eintrag von history: der Tag des Ausscheidens, soweit eingetragen. Sonst fehlt der Schlüssel.

holder

Schlüssel	Typ	Beschreibung
entity_id	string \| null	Stabile ID, wenn der Gesellschafter eindeutig zugeordnet ist, sonst null. Bei JOINT immer null.
type	enum	ORGANIZATION, PERSON oder JOINT. Bestimmt, welche der folgenden Felder es gibt.
name	string \| null	Der Name; in entries der aktuelle, wenn bekannt, sonst wie gedruckt. null nur bei JOINT ohne Namen der Gemeinschaft.
city	string \| null	ORGANIZATION und PERSON: Sitz oder Wohnort.
country	string \| null	ORGANIZATION und PERSON: Land als ISO-3166-1-alpha-3-Code, z. B. DEU.
legal_form	string \| null	Nur ORGANIZATION: Rechtsform als Kurzform, z. B. GmbH. Freitext.
status	enum \| null	Nur ORGANIZATION: der aktuelle Registerstatus, ACTIVE oder INACTIVE. null, wenn nicht zugeordnet.
registration	object \| null	Nur ORGANIZATION: {court, register_type, register_number}. court kann null sein, register_number ist ein String. null, wenn kein Registerverweis lesbar ist.
registration_text	string \| null	Nur ORGANIZATION: der Registerverweis wie gedruckt, wenn registration null ist oder kein court hat, etwa bei ausländischen Registern. Sonst null.
birth_date	string \| null	Nur PERSON: Geburtsdatum.
members	array<object>	Nur JOINT: die Mitberechtigten als PERSON- oder ORGANIZATION-Objekte; ihr name kann null sein.

ownership

Schlüssel	Typ	Beschreibung
percentage	number \| null	Anteil am Kapital in Prozent, 0 bis 100. null, wenn er nicht verlässlich bekannt ist.
percentage_basis	enum \| null	Woher percentage stammt, siehe Werte. null, wenn percentage null ist.
nominal_amount	object \| null	Summe der Nennbeträge {value, currency}.
share_count	integer \| null	Zahl der Anteile. null, wenn sie nicht vollständig bekannt ist.
share_ranges	array<object>	Die Anteile nach laufender Nummer, ein Bereich je fortlaufender Folge mit gleichem Nennbetrag. Leer, wenn das Dokument keine einzelnen Anteile nennt.
share_ranges[].from / to	integer \| null	Erste und letzte Anteilsnummer. null, wenn das Dokument keine Nummern nennt.
share_ranges[].count	integer \| null	Zahl der Anteile im Bereich.
share_ranges[].nominal_value	object \| null	Nennbetrag je Anteil {value, currency}.

changes

Schlüssel	Typ	Beschreibung
compared_to	string \| null	record.date des vorherigen Dokuments.
joined	array<object>	Dazugekommen: {holder, percentage}.
left	array<object>	Ausgeschieden: {holder, percentage}, mit dem bisherigen Anteil.
changed	array<object>	Anteil geändert: {holder, percentage_before, percentage_after}.

holder ist hier ein Kurzverweis {entity_id, type, name}, und Anteile können null sein. Wer mehrere Zeilen hat, zählt einmal. Ändern sich nur Nennbeträge oder Anteilsnummern, bleiben joined, left und changed leer.

Werte

Feld	Wert	Bedeutung
record.source	SHAREHOLDER_LIST	Gesellschafterliste.
	FOUNDING_DOCUMENT	Gründungsdokument (Musterprotokoll oder Gesellschaftsvertrag).
	COMMERCIAL_REGISTER	Im Handelsregister eingetragene Gesellschafter.
share_capital.basis	REPORTED	Im Dokument angegeben.
	CALCULATED	Zahl mal Nennbetrag der Anteile, weil das Dokument keine Summe nennt.
ownership.percentage_basis	REPORTED	Im Dokument abgedruckt oder aus Nennbetrag und angegebenem Stammkapital berechnet.
	CALCULATED	Aus Zahl und Nennbetrag der Anteile berechnet, ohne Bestätigung im Dokument.
since_basis	ENTRY_RECORDED	Ab diesem Datum verzeichnet: Das Dokument davor nennt den Gesellschafter nicht, oder es ist der Tag der Eintragung.
	EARLIEST_RECORD	Mindestens seit diesem Datum verzeichnet, vielleicht länger.
role	SHAREHOLDER	Gesellschafter laut Liste oder Gründungsdokument.
	LIMITED_PARTNER	Kommanditist.
	FULLY_LIABLE_PARTNER	Komplementär, persönlich haftend.
	PARTNER	Gesellschafter laut Handelsregister.
	PROPRIETOR	Inhaber laut Handelsregister.
	OWNER	Sonstiger eingetragener Eigentümer.
registration.register_type	HRB	Handelsregister B: GmbH, UG, AG, SE, KGaA.
	HRA	Handelsregister A: KG, OHG, e. K.
	GnR	Genossenschaftsregister.
	PR	Partnerschaftsregister.
	VR	Vereinsregister.
	GsR	Gesellschaftsregister (eGbR).

Neue Werte können hinzukommen; behandle unbekannte Werte robust.

Gut zu wissen

Unbekannte Werte sind null. Datumsangaben haben das Format YYYY-MM-DD, Beträge die Form {value, currency} mit currency als ISO-4217-Code oder null.
percentage ist der direkt gehaltene Anteil am Kapital, nicht der Anteil an den Stimmrechten. Die Anteile eines Dokuments ergeben zusammen nicht immer genau 100. Die wirtschaftlich Berechtigten über alle Ebenen liefert das Feature ubos.
Ein JOINT-Anteil gehört der Gemeinschaft als Ganzes, etwa einer Erbengemeinschaft. Teile ihn nicht auf die members auf und rechne ihn nicht zu deren eigenen Anteilen.
Ist entity_id gesetzt, erkennst Du daran denselben Gesellschafter in entries, history und changes; Namen in history können anders geschrieben sein. Mit der entity_id eines Unternehmens als q rufst Du dessen eigene Gesellschafter ab.

Unterschied zu shareholders

Das reguläre Feature shareholders (5 Credits) liefert die aktuellen Gesellschafter und frühere Listen. Tiefe Gesellschafter ergänzt die einzelnen Geschäftsanteile mit ihren Nummern (share_ranges), seit wann jemand verzeichnet ist (since) und was sich zuletzt geändert hat (changes).