Data

DATA

shareholders_deep

Max

Deep Shareholders (shareholders_deep) shows who holds a company: each holder's stake and exact shares with their numbers, how long they have been on record and what the latest shareholder list changed, plus the earlier lists. It is based on the shareholder lists and founding documents filed with the Handelsregister.

Max plan only: 80 credits per request, on top of the 5-credit base price. The 80 credits are charged only when current holders are returned. Try it in the API Playground →

Request

Add feature=shareholders_deep to your fetch-organization request and pass the company's entity_id as q.

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	Response	Feature credits
Not requested, or your plan is not Max	no shareholders_deep key	0
No current ownership information, e.g. for an AG	"shareholders_deep": null	0
Otherwise	the block described below	80, or 0 if entries is empty

Example

{
  "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
        }
      ]
    }
  }
}

Fields

shareholders_deep

Key	Type	Description
record	object	Where the current state comes from: {date, source}. date is the date of the filing; null for COMMERCIAL_REGISTER.
share_capital	object \| null	The share capital according to that filing: {value, currency, basis}. null when it is neither stated nor calculable, and for COMMERCIAL_REGISTER.
entries	array<object>	The current holders, largest stake first. One entry per row of the filing, so a holder with several rows appears several times.
history	array<object>	The other filings, newest first, each with record, share_capital and entries. Holders from filings appear there as printed at the time (status null).
changes	object \| null	What changed compared with the previous filing. null when there is none or record.source is not SHAREHOLDER_LIST.

entries[]

Key	Type	Description
holder	object	Who holds the stake; see holder.
role	enum	In what capacity; see Values.
ownership	object	How much; see ownership.
since	string \| null	Date from which the holder has been on record without a break. If only the stake changes, since stays the same. Always null for JOINT.
since_basis	enum \| null	How certain since is; see Values. null when since is null.
until	string \| null	Only in the COMMERCIAL_REGISTER item of history: the date the partner left, where recorded. Absent everywhere else.

holder

Key	Type	Description
entity_id	string \| null	Stable ID when the holder was identified unambiguously, otherwise null. Always null for JOINT.
type	enum	ORGANIZATION, PERSON or JOINT. Determines which of the following fields exist.
name	string \| null	The name; in entries the current one where known, otherwise as printed. null only for a JOINT holding without a group name.
city	string \| null	ORGANIZATION and PERSON: seat or place of residence.
country	string \| null	ORGANIZATION and PERSON: country as an ISO 3166-1 alpha-3 code, e.g. DEU.
legal_form	string \| null	ORGANIZATION only: short legal form, e.g. GmbH. Free text.
status	enum \| null	ORGANIZATION only: the current register status, ACTIVE or INACTIVE. null when not identified.
registration	object \| null	ORGANIZATION only: {court, register_type, register_number}. court can be null; register_number is a string. null when no register reference can be read.
registration_text	string \| null	ORGANIZATION only: the register reference as printed when registration is null or has no court, e.g. for a foreign register. Otherwise null.
birth_date	string \| null	PERSON only: date of birth.
members	array<object>	JOINT only: the joint holders as PERSON or ORGANIZATION objects; a member's name can be null.

ownership

Key	Type	Description
percentage	number \| null	Share of the capital in percent, 0 to 100. null when not reliably known.
percentage_basis	enum \| null	Where percentage comes from; see Values. null when percentage is null.
nominal_amount	object \| null	Total nominal amount of the shares {value, currency}.
share_count	integer \| null	Number of shares. null unless fully known.
share_ranges	array<object>	The shares by number, one range per consecutive run with the same nominal value. Empty when the filing lists no individual shares.
share_ranges[].from / to	integer \| null	First and last share number. null when the filing gives no numbers.
share_ranges[].count	integer \| null	Number of shares in the range.
share_ranges[].nominal_value	object \| null	Nominal value per share {value, currency}.

changes

Key	Type	Description
compared_to	string \| null	record.date of the previous filing.
joined	array<object>	Joined: {holder, percentage}.
left	array<object>	Left: {holder, percentage}, with the stake they had.
changed	array<object>	Stake changed: {holder, percentage_before, percentage_after}.

Here holder is a short reference {entity_id, type, name}, and percentages can be null. A holder with several rows counts once. If only nominal amounts or share numbers change, joined, left and changed stay empty.

Values

Field	Value	Meaning
record.source	SHAREHOLDER_LIST	Shareholder list (Gesellschafterliste).
	FOUNDING_DOCUMENT	Founding document (Musterprotokoll or Gesellschaftsvertrag).
	COMMERCIAL_REGISTER	Holders entered in the Handelsregister.
share_capital.basis	REPORTED	Stated in the filing.
	CALCULATED	Number of shares times nominal value, because the filing states no total.
ownership.percentage_basis	REPORTED	Printed in the filing, or calculated from the nominal amount and the stated share capital.
	CALCULATED	Calculated from the number and nominal value of the shares, without confirmation in the filing.
since_basis	ENTRY_RECORDED	On record from that date: the filing before does not show the holder, or it is the date of registration.
	EARLIEST_RECORD	On record at least since that date, possibly longer.
role	SHAREHOLDER	Shareholder according to a list or founding document.
	LIMITED_PARTNER	Limited partner (Kommanditist).
	FULLY_LIABLE_PARTNER	General partner with unlimited liability (Komplementär).
	PARTNER	Partner according to the Handelsregister.
	PROPRIETOR	Proprietor according to the Handelsregister.
	OWNER	Other registered owner.
registration.register_type	HRB	Handelsregister B: GmbH, UG, AG, SE, KGaA.
	HRA	Handelsregister A: KG, OHG, e.K.
	GnR	Register of cooperatives.
	PR	Register of professional partnerships.
	VR	Register of associations.
	GsR	Register of civil-law partnerships (eGbR).

New values can be added, so handle unknown ones gracefully.

Good to know

Unknown values are null. Dates use YYYY-MM-DD; amounts are {value, currency} with currency as an ISO 4217 code or null.
percentage is the directly held share of the capital, not the share of voting rights. The percentages of one filing do not always add up to exactly 100. For the beneficial owners across all layers, use the ubos feature.
A JOINT stake belongs to the group as a whole, such as a community of heirs. Don't split it between the members or add it to their own stakes.
When entity_id is set, use it to match the same holder across entries, history and changes; names in history can be spelled differently. Pass a company holder's entity_id as q to get its own shareholders.

Compared with shareholders

The regular shareholders feature (5 credits) returns the current holders and earlier lists. Deep Shareholders adds the individual shares with their numbers (share_ranges), how long each holder has been on record (since) and what changed last (changes).