Shareholders and shareholdings – Documentation

Feature
Feature	What it returns	Credits	Available
shareholders	Shareholders: the current shareholders with their shares and earlier shareholder lists	5	every account · Beta
shareholders_deep	Deep Shareholders: holders with share numbers, since when they hold shares and what changed last	80	Max
ubos	Beneficial owners (UBO): the people behind the company, calculated from the shareholder lists	10	every account · Beta
shareholdings	Shareholdings: companies in which the company itself holds shares	5	every account · Beta

Shareholders by legal form

What the register says about the owners depends on the legal form. The table shows what you typically get.

Legal form
Legal form	Shareholders in the response
GmbH, UG	All shareholders from the shareholder list under § 40 GmbHG, with nominal amount and share of the share capital (Stammkapital), plus earlier lists.
AG, SE, KGaA	Only in individual cases, because shareholders of an AG are not in any public register.
GmbH & Co. KG	The limited partners (Kommanditisten) from the register with their liability amount, partly also the general partner GmbH.
KG, OHG	The registered partners: for a KG the general partners (Komplementäre) and limited partners, for an OHG the partners with personal liability.
e.K.	The owner.
eG	None. The member list of a cooperative is not public.
PartG	The registered partners.

Shareholder lists are often scanned documents in many layouts. We extract them automatically. We use the latest technology for this and invest a lot in quality; individual errors are still possible.

Shareholders

The feature shareholders returns the current shareholders: for a GmbH from the newest shareholder list, for partnerships and sole traders from the register. It costs 5 credits, but only when it names current shareholders. If it only returns earlier lists, it costs nothing.

Each entry in entries describes a person or a company. A person has first_name, last_name and birth_date, a company entity_name, country_code and registration_reference.

curl -G "https://handelsregister.ai/api/v1/fetch-organization" \
  -H "x-api-key: YOUR_API_KEY" \
  --data-urlencode 'q=Hetzner Online GmbH' \
  --data-urlencode 'feature=shareholders'

import requests

response = requests.get(
    "https://handelsregister.ai/api/v1/fetch-organization",
    headers={"x-api-key": "YOUR_API_KEY"},
    params={
        "q": "Hetzner Online GmbH",
        "feature": ["shareholders"],
    },
)
data = response.json()

const url = new URL("https://handelsregister.ai/api/v1/fetch-organization");
url.searchParams.append("q", "Hetzner Online GmbH");
url.searchParams.append("feature", "shareholders");

const response = await fetch(url, {
  headers: { "x-api-key": "YOUR_API_KEY" },
});
const data = await response.json();

Field
Field	Meaning	Example	Availability
shareholdersobject\|null	The company's shareholders: current state in entries, earlier states in history.Empty when no shareholders are known, for example for an AG or eG`shareholders` · Beta	–	mostly: GmbH, UG, GmbH & Co. KG, KG, OHG, e.K., PartG rarely: AG, SE, KGaA never: eG
shareholders.entriesarray	The current shareholders, one entry per person or company.	–	as above
shareholders.entries[].shareholderobject	Who holds the share: a person or a company, with the fields below.	–	as above
shareholders.entries[].shareholder.entity_idstring\|null	ID of the person or company, for its own person profile or company profile.Empty when the shareholder could not be matched with certainty	`"dd1cfcd3a25b5a63d549d768e2fcaaaf"`	as above
shareholders.entries[].shareholder.first_namestring	First name of a person, with all registered first names.	–	always: e.K. mostly: GmbH, UG, GmbH & Co. KG, KG, OHG, PartG rarely: AG, SE, KGaA never: eG
shareholders.entries[].shareholder.last_namestring	Last name of a person.	–	as above
shareholders.entries[].shareholder.birth_datestring\|null	Date of birth of a person, in the format YYYY-MM-DD.Empty when the document gives no date of birth	–	as above
shareholders.entries[].shareholder.entity_namestring	Name of a company that is a shareholder.	`"ENSoXX GmbH"`	mostly: GmbH, UG, GmbH & Co. KG rarely: AG, SE, KGaA, KG, OHG never: e.K., eG, PartG
shareholders.entries[].shareholder.country_codestring\|null	Country of a company as a three-letter ISO code (ISO 3166-1 alpha-3), for example DEU.	`"DEU"`	as above
shareholders.entries[].shareholder.registration_referencestring\|null	Register entry of a company as text, as it appears in the document.Empty when the document gives no register entry, often for foreign companies	`"AG Ansbach HRB 6105"`	as above
shareholders.entries[].shareholder.addressstring\|null	Address, place of residence or seat as text, as it appears in the document.Empty when the document gives no address	`"Gunzenhausen"`	mostly: GmbH, UG, GmbH & Co. KG, KG, OHG, e.K., PartG rarely: AG, SE, KGaA never: eG
shareholders.entries[].contributionobject\|null	The amount of the shareholding with amount and currency: for a GmbH the nominal amount of the shares, for limited partners the registered liability amount (Haftsumme).Empty when no amount is registered, for example for partners with personal liability or the owner of an e.K	–	mostly: GmbH, UG, GmbH & Co. KG partly: KG, OHG rarely: AG, SE, KGaA never: e.K., eG, PartG
shareholders.entries[].contribution_rationumber\|null	Share of the capital as a decimal: 1 means 100 %, 0.245 means 24.5 %.Empty when no share can be derived, for example for partnerships	`0.945`	mostly: GmbH, UG rarely: AG, SE, KGaA, GmbH & Co. KG, KG, OHG never: e.K., eG, PartG
shareholders.entries[].roleobject	The role: label as a fixed code, plus de and en with a long and a short name, for example Kommanditist and Kom.	–	mostly: GmbH, UG, GmbH & Co. KG, KG, OHG, e.K., PartG rarely: AG, SE, KGaA never: eG
shareholders.entries[].role.labelstring	The role as a fixed code. New values can be added.Values: `SHAREHOLDER` shareholder according to the shareholder list, `LIMITED_PARTNER` limited partner (Kommanditist), `FULLY_LIABLE_PARTNER` partner with personal liability (persönlich haftender Gesellschafter), `PARTNER` partner of a PartG, `OWNER` owner of an e.K.	`"SHAREHOLDER"`	as above
shareholders.total_capitalobject\|null	The capital according to the shareholder list, with amount and currency, the basis for contribution_ratio.Empty when the list gives no capital, and for partnerships	–	mostly: GmbH, UG rarely: AG, SE, KGaA, GmbH & Co. KG, KG, OHG never: e.K., eG, PartG

With a shareholder's entity_id you fetch its own company profile or person profile. That way you follow an ownership chain level by level.

Shareholder history

shareholders.history comes at no extra cost. It contains the date of the current list and the earlier shareholder lists, newest first.

For a KG or GmbH & Co. KG, former partners are in register_ownership, with entry and exit dates from the register. For OHG, PartG and e.K. you find them in shareholders_deep.

Field
Field	Meaning	Example	Availability
shareholders.historyobject	Earlier states of the shareholders, at no extra cost.Empty when no earlier states exist; the field is then missing, for example for OHG, PartG or e.K`shareholders` · Beta	–	mostly: GmbH, UG partly: GmbH & Co. KG, KG, OHG rarely: AG, SE, KGaA never: e.K., eG, PartG
shareholders.history.current_as_ofstring\|null	Date of the shareholder list that entries comes from.Empty when the shareholders come from the register	`"2015-08-21"`	mostly: GmbH, UG rarely: AG, SE, KGaA, GmbH & Co. KG, KG, OHG never: e.K., eG, PartG
shareholders.history.pastarray	Earlier shareholder lists, newest first.Empty when only one list exists	–	as above
shareholders.history.past[].as_ofstring	Date of this shareholder list.	`"2015-07-28"`	as above
shareholders.history.past[].data.total_capitalobject\|null	The capital according to this list, with amount and currency. Older lists partly give it in DEM.	–	as above
shareholders.history.past[].data.shareholdersarray	The shareholders according to this list, with the same fields as entries.	–	as above
shareholders.history.register_ownershipobject	For KG and GmbH & Co. KG: former partners according to the register, in past.	–	partly: GmbH & Co. KG, KG, OHG never: GmbH, UG, AG, SE, KGaA, e.K., eG, PartG
shareholders.history.register_ownership.past[].shareholderobject	The former partner, with the same fields as in entries.	–	as above
shareholders.history.register_ownership.past[].roleobject	Their role, structured like role in entries.	–	as above
shareholders.history.register_ownership.past[].effective_fromstring\|null	Since when they were registered, in the format YYYY-MM-DD.	`"2022-01-07"`	as above
shareholders.history.register_ownership.past[].effective_tostring\|null	Until when they were registered.	`"2026-07-06"`	as above
shareholders.history.register_ownership.past[].effective_to_inferredboolean	true if effective_to is derived and not explicitly registered.	`false`	as above
shareholders.history.register_ownership.past[].contributionnull	Always null here.	–	as above
shareholders.history.register_ownership.past[].contribution_rationull	Always null here.	–	as above

Deep Shareholders

The feature shareholders_deep comes with the Max plan. It costs 80 credits, but only when the current document names at least one holder.

It reads all shareholder lists of a company, not just the newest one. That way it shows since when someone holds shares, what the earlier states looked like and what the last list changed.

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

import requests

response = requests.get(
    "https://handelsregister.ai/api/v1/fetch-organization",
    headers={"x-api-key": "YOUR_API_KEY"},
    params={
        "q": "Hetzner Online GmbH",
        "feature": ["shareholders_deep"],
    },
)
data = response.json()

const url = new URL("https://handelsregister.ai/api/v1/fetch-organization");
url.searchParams.append("q", "Hetzner Online GmbH");
url.searchParams.append("feature", "shareholders_deep");

const response = await fetch(url, {
  headers: { "x-api-key": "YOUR_API_KEY" },
});
const data = await response.json();

The document. record says where the current state comes from, share_capital gives the capital according to that document.

Field
Field	Meaning	Example	Availability
shareholders_deepobject\|null	Holders, shares, earlier documents and the last change.Empty when no current document and no registered partner is known, typical for AG, SE and eG`shareholders_deep` · from Max	–	mostly: GmbH, UG, GmbH & Co. KG, KG, OHG, e.K., PartG rarely: AG, SE, KGaA never: eG
shareholders_deep.recordobject	The document the current state comes from: date and source.	–	as above
shareholders_deep.record.datestring\|null	The date the document refers to. It is usually shortly after the change the document shows.Empty when the shareholders come from the register (`COMMERCIAL_REGISTER`)	`"2015-08-18"`	mostly: GmbH, UG rarely: AG, SE, KGaA, GmbH & Co. KG, KG, OHG never: e.K., eG, PartG
shareholders_deep.record.sourcestring	The kind of document.Values: `SHAREHOLDER_LIST` shareholder list (Gesellschafterliste), `FOUNDING_DOCUMENT` founding document, i.e. Musterprotokoll (model protocol) or Gesellschaftsvertrag (articles of association), `COMMERCIAL_REGISTER` partners or owners registered in the register	`"SHAREHOLDER_LIST"`	mostly: GmbH, UG, GmbH & Co. KG, KG, OHG, e.K., PartG rarely: AG, SE, KGaA never: eG
shareholders_deep.share_capitalobject\|null	The capital according to the document: value, currency and basis.Empty when the document gives no capital, and always for COMMERCIAL_REGISTER	–	mostly: GmbH, UG rarely: AG, SE, KGaA, GmbH & Co. KG, KG, OHG never: e.K., eG, PartG
shareholders_deep.share_capital.basisstring	Where the amount comes from.Values: `REPORTED` stated in the document, `CALCULATED` calculated from the number and nominal amount of the shares	`"REPORTED"`	as above

The holders. Each entry in entries is one line of the document, the largest share first. If someone has several lines, they appear several times in the list.

Field
Field	Meaning	Example	Availability
shareholders_deep.entriesarray	The current holders, one line of the document per entry, the largest share first.`shareholders_deep` · from Max	–	mostly: GmbH, UG, GmbH & Co. KG, KG, OHG, e.K., PartG rarely: AG, SE, KGaA never: eG
shareholders_deep.entries[].holderobject	Who holds the share. type determines which fields follow.	–	as above
shareholders_deep.entries[].holder.typestring	The kind of holder.Values: `ORGANIZATION` company or other organization, `PERSON` natural person, `JOINT` jointly held share, for example of a community of heirs, with members	`"ORGANIZATION"`	as above
shareholders_deep.entries[].holder.entity_idstring\|null	ID of the holder, for its own company profile or person profile.Empty when the holder could not be matched with certainty, and always for JOINT	`"dd1cfcd3a25b5a63d549d768e2fcaaaf"`	as above
shareholders_deep.entries[].holder.namestring	The name. For matched holders the current name, otherwise as in the document.	`"ENSoXX GmbH"`	as above
shareholders_deep.entries[].holder.birth_datestring\|null	Only for people: the date of birth.Empty when the document gives none	–	always: e.K. mostly: GmbH, UG, GmbH & Co. KG, KG, OHG, PartG rarely: AG, SE, KGaA never: eG
shareholders_deep.entries[].holder.legal_formstring\|null	Only for organizations: the legal form as text, for example GmbH or Ltd.	`"GmbH"`	mostly: GmbH, UG, GmbH & Co. KG rarely: AG, SE, KGaA, KG, OHG never: e.K., eG, PartG
shareholders_deep.entries[].holder.statusstring\|null	Only for organizations: the current status in the register.Empty when the holder is not matched, and always in the earlier documents in historyValues: `ACTIVE` active, `INACTIVE` no longer active, for example deleted or merged	`"ACTIVE"`	as above
shareholders_deep.entries[].holder.citystring\|null	Seat or place of residence.	`"Gunzenhausen"`	mostly: GmbH, UG, GmbH & Co. KG, KG, OHG, e.K., PartG rarely: AG, SE, KGaA never: eG
shareholders_deep.entries[].holder.countrystring\|null	Country as a three-letter ISO code (ISO 3166-1 alpha-3), for example DEU, AUT or LUX.	`"DEU"`	as above
shareholders_deep.entries[].holder.registrationobject\|null	Only for organizations: court, register_type and register_number.Empty when no register entry can be read, for example for many foreign companies	–	mostly: GmbH, UG, GmbH & Co. KG rarely: AG, SE, KGaA, KG, OHG never: e.K., eG, PartG
shareholders_deep.entries[].holder.registration_textstring\|null	Only for organizations: the register entry as text, when registration is missing or names no court.	`null`	rarely
shareholders_deep.entries[].rolestring	The holder's role. New values can be added.Values: `SHAREHOLDER` shareholder according to the shareholder list or founding document, `LIMITED_PARTNER` limited partner (Kommanditist), `FULLY_LIABLE_PARTNER` partner with personal liability (persönlich haftender Gesellschafter), `PARTNER` partner of a PartG, `OWNER` owner of an e.K.	`"SHAREHOLDER"`	mostly: GmbH, UG, GmbH & Co. KG, KG, OHG, e.K., PartG rarely: AG, SE, KGaA never: eG
shareholders_deep.entries[].sincestring\|null	Since when the holder holds shares. For registered partners, the date of registration.Empty when no date can be determined, and always for JOINT	`"2015-08-18"`	as above
shareholders_deep.entries[].since_basisstring\|null	How certain since is.Values: `ENTRY_RECORDED` documented from this date: the list before does not yet name the holder, `EARLIEST_RECORD` already in the oldest available document, so a shareholder since at least this date	`"ENTRY_RECORDED"`	as above

The share. ownership describes how much a holder holds: in percent, as a nominal amount and by the sequential numbers of the shares.

Field
Field	Meaning	Example	Availability
shareholders_deep.entries[].ownershipobject	The holder's share.`shareholders_deep` · from Max	–	mostly: GmbH, UG, GmbH & Co. KG, KG, OHG, e.K., PartG rarely: AG, SE, KGaA never: eG
shareholders_deep.entries[].ownership.percentagenumber\|null	Share of the capital in percent, from 0 to 100. This is the direct shareholding, not the voting rights.Empty when the share cannot be determined reliably, and always for registered partners of partnerships	`94.5`	mostly: GmbH, UG rarely: AG, SE, KGaA, GmbH & Co. KG, KG, OHG never: e.K., eG, PartG
shareholders_deep.entries[].ownership.percentage_basisstring\|null	Where percentage comes from.Values: `REPORTED` stated in the document or derived from the nominal amount and capital in the document, `CALCULATED` calculated from the number and nominal amount of the shares	`"REPORTED"`	as above
shareholders_deep.entries[].ownership.nominal_amountobject\|null	Sum of the nominal amounts with value and currency. For limited partners the registered liability amount (Haftsumme).Empty when no amount is known	–	mostly: GmbH, UG, GmbH & Co. KG partly: KG, OHG rarely: AG, SE, KGaA never: e.K., eG, PartG
shareholders_deep.entries[].ownership.share_countinteger\|null	Number of shares (Geschäftsanteile).Empty when the number is not known for all shares	`47250`	mostly: GmbH, UG rarely: AG, SE, KGaA, GmbH & Co. KG, KG, OHG never: e.K., eG, PartG
shareholders_deep.entries[].ownership.share_rangesarray	The shares by their sequential numbers in the list, one range per run of equal shares.	–	as above
shareholders_deep.entries[].ownership.share_ranges[].frominteger\|null	First sequential number of the range.	`1`	as above
shareholders_deep.entries[].ownership.share_ranges[].tointeger\|null	Last sequential number of the range.	`47250`	as above
shareholders_deep.entries[].ownership.share_ranges[].countinteger\|null	Number of shares in the range.	`47250`	as above
shareholders_deep.entries[].ownership.share_ranges[].nominal_valueobject\|null	Nominal amount per share in the range, with value and currency.	–	as above

History and changes. history contains the earlier documents with the same fields. The holders appear there as they stood in the document at the time. changes compares the current state with the previous one.

Field
Field	Meaning	Example	Availability
shareholders_deep.historyarray	The earlier documents, newest first, each with record, share_capital and entries. Former registered partners are collected in the last entry.`shareholders_deep` · from Max	–	mostly: GmbH, UG rarely: AG, SE, KGaA, GmbH & Co. KG, KG, OHG never: e.K., eG, PartG
shareholders_deep.history[].entries[].holder.membersarray	For JOINT: the joint holders of type PERSON or ORGANIZATION, with the same fields as holder.	–	rarely
shareholders_deep.history[].entries[].untilstring\|null	Only in the item of history with COMMERCIAL_REGISTER: when the partner left.	–	partly: GmbH & Co. KG, KG, OHG, PartG rarely: e.K. never: GmbH, UG, AG, SE, KGaA, eG
shareholders_deep.changesobject\|null	What changed with the current document compared to the previous one.Empty when there is no earlier document, and when the current state comes from the register or a founding document	–	mostly: GmbH, UG rarely: AG, SE, KGaA, GmbH & Co. KG, KG, OHG never: e.K., eG, PartG
shareholders_deep.changes.compared_tostring\|null	Date of the previous document.	`"2015-07-16"`	as above
shareholders_deep.changes.joinedarray	New holders: holder with entity_id, type and name, plus percentage.	–	as above
shareholders_deep.changes.leftarray	Holders who left, with the share they last had.	–	as above
shareholders_deep.changes.changedarray	Holders whose share changed.	–	as above
shareholders_deep.changes.changed[].percentage_beforenumber\|null	Share in percent in the previous document.	`100`	as above
shareholders_deep.changes.changed[].percentage_afternumber\|null	Share in percent in the current document.	`5.5`	as above

1{2  "entity_id": "94eb910fef13f94585c48c263fa446d4",3  "name": "Hetzner Online GmbH",4  "shareholders_deep": {5    "record": {6      "date": "2015-08-18",7      "source": "SHAREHOLDER_LIST"8    },9    "share_capital": {10      "value": 50000,11      "currency": "EUR",12      "basis": "REPORTED"13    },14    "entries": [15      {16        "holder": {17          "entity_id": "dd1cfcd3a25b5a63d549d768e2fcaaaf",18          "type": "ORGANIZATION",19          "name": "ENSoXX GmbH",20          "legal_form": "GmbH",21          "status": "ACTIVE",22          "city": "Gunzenhausen",23          "country": "DEU",24          "registration": {25            "court": "Ansbach",26            "register_type": "HRB",27            "register_number": "6105"28          },29          "registration_text": null30        },31        "role": "SHAREHOLDER",32        "ownership": {33          "percentage": 94.5,34          "percentage_basis": "REPORTED",35          "nominal_amount": {36            "value": 47250,37            "currency": "EUR"38          },39          "share_count": 47250,40          "share_ranges": [41            {42              "from": 1,43              "to": 47250,44              "count": 47250,45              "nominal_value": {46                "value": 1,47                "currency": "EUR"48              }49            }50          ]51        },52        "since": "2015-08-18",53        "since_basis": "ENTRY_RECORDED"54      },55      {56        "holder": {57          "entity_id": "08ed5f967956831ca6588930fd2693ed",58          "type": "PERSON",59          "name": "Max Felix Mustermann",60          "birth_date": "1976-01-15",61          "city": "Musterheim",62          "country": "DEU"63        },64        "role": "SHAREHOLDER",65        "ownership": {66          "percentage": 5.5,67          "percentage_basis": "REPORTED",68          "nominal_amount": {69            "value": 2750,70            "currency": "EUR"71          },72          "share_count": 2750,73          "share_ranges": [74            {75              "from": 47251,76              "to": 50000,77              "count": 2750,78              "nominal_value": {79                "value": 1,80                "currency": "EUR"81              }82            }83          ]84        },85        "since": "2015-07-16",86        "since_basis": "EARLIEST_RECORD"87      }88    ],89    "history": [90      {91        "record": {92          "date": "2015-07-16",93          "source": "SHAREHOLDER_LIST"94        },95        "share_capital": {96          "value": 50000,97          "currency": "EUR",98          "basis": "REPORTED"99        },100        "entries": [101          {102            "holder": {103              "entity_id": "08ed5f967956831ca6588930fd2693ed",104              "type": "PERSON",105              "name": "Max Mustermann",106              "birth_date": "1976-01-15",107              "city": null,108              "country": null109            },110            "role": "SHAREHOLDER",111            "ownership": {112              "percentage": 100,113              "percentage_basis": "REPORTED",114              "nominal_amount": {115                "value": 50000,116                "currency": "EUR"117              },118              "share_count": 50000,119              "share_ranges": [120                {121                  "from": 1,122                  "to": 50000,123                  "count": 50000,124                  "nominal_value": {125                    "value": 1,126                    "currency": "EUR"127                  }128                }129              ]130            },131            "since": "2015-07-16",132            "since_basis": "EARLIEST_RECORD"133          }134        ]135      }136    ],137    "changes": {138      "compared_to": "2015-07-16",139      "joined": [140        {141          "holder": {142            "entity_id": "dd1cfcd3a25b5a63d549d768e2fcaaaf",143            "type": "ORGANIZATION",144            "name": "ENSoXX GmbH"145          },146          "percentage": 94.5147        }148      ],149      "left": [],150      "changed": [151        {152          "holder": {153            "entity_id": "08ed5f967956831ca6588930fd2693ed",154            "type": "PERSON",155            "name": "Max Felix Mustermann"156          },157          "percentage_before": 100,158          "percentage_after": 5.5159        }160      ]161    }162  }163}

200 · Example response: Hetzner Online GmbH with the feature shareholders_deep

Compared to shareholders, shareholders_deep adds the share numbers, the date since which someone holds shares, the changes and jointly held shares with their members. For comparisons across companies and years, it is best to use the same feature throughout.

Beneficial owners

Beneficial owners are the natural persons who ultimately own a company. The feature ubos follows the shareholder lists across the ownership levels down to the people. The list names every person with a calculated share, without a minimum threshold. It costs 10 credits when it returns data.

If a share cannot be traced to a person, it is in unresolved_beneficial_owners with the reason. Often a company abroad holds it. Our data covers German companies, so we do not know the shareholders of a company abroad. coverage shows what percentage of the capital is traced to people and how much remains open. The two values do not always add up to 100. For the rest, the shareholder data names no holder.

The feature is charged as soon as it returns a result. This also applies when all shares are in unresolved_beneficial_owners.

curl -G "https://handelsregister.ai/api/v1/fetch-organization" \
  -H "x-api-key: YOUR_API_KEY" \
  --data-urlencode 'q=Hetzner Online GmbH' \
  --data-urlencode 'feature=ubos'

import requests

response = requests.get(
    "https://handelsregister.ai/api/v1/fetch-organization",
    headers={"x-api-key": "YOUR_API_KEY"},
    params={
        "q": "Hetzner Online GmbH",
        "feature": ["ubos"],
    },
)
data = response.json()

const url = new URL("https://handelsregister.ai/api/v1/fetch-organization");
url.searchParams.append("q", "Hetzner Online GmbH");
url.searchParams.append("feature", "ubos");

const response = await fetch(url, {
  headers: { "x-api-key": "YOUR_API_KEY" },
});
const data = await response.json();

Field
Field	Meaning	Example	Availability
ubosobject\|null	The beneficial owners, calculated from the shareholder lists across the ownership levels.Empty when no chain can be built from shareholder lists, for example for AG, eG or e.K`ubos` · Beta	–	mostly: GmbH, UG rarely: AG, SE, KGaA, GmbH & Co. KG, KG, OHG never: e.K., eG, PartG
ubos.beneficial_ownersarray	The people who own the company directly or through other companies.Empty when no share can be traced to a person	–	as above
ubos.beneficial_owners[].personobject	The person, with the fields below.	–	partly: GmbH, UG rarely: AG, SE, KGaA, GmbH & Co. KG, KG, OHG never: e.K., eG, PartG
ubos.beneficial_owners[].person.entity_idstring\|null	ID of the person, for the person profile.Empty when the person could not be matched with certainty	–	as above
ubos.beneficial_owners[].person.namestring	Full name.	–	as above
ubos.beneficial_owners[].person.name_partsobject	The name in parts: given and family, and canonical_name when known.	–	as above
ubos.beneficial_owners[].person.birth_datestring\|null	Date of birth.	–	as above
ubos.beneficial_owners[].person.locationobject\|null	Place of residence in home: city, county, state and country.Empty when no place of residence is known	–	as above
ubos.beneficial_owners[].ownership_percentagenumber	Total share of the person in percent, added up across all paths.	`50`	as above
ubos.beneficial_owners[].pathsarray	Each path to the person, with the share along that path.	–	as above
ubos.beneficial_owners[].paths[].percentagenumber	Share in percent that arrives through this path.	`50`	as above
ubos.beneficial_owners[].paths[].viaarray	The companies on this path, first the direct shareholder of the requested company (depth 1). The fields are the same as in via of the unresolved shares.Empty when the person holds shares directly	–	as above

Field
Field	Meaning	Example	Availability
ubos.unresolved_beneficial_ownersarray	Shares that could not be traced to a person.Empty when all shares are resolved`ubos` · Beta	–	mostly: GmbH, UG rarely: AG, SE, KGaA, GmbH & Co. KG, KG, OHG never: e.K., eG, PartG
ubos.unresolved_beneficial_owners[].reasonstring	Why the chain ends here. New values can be added.Values: `unlinked` the shareholder is a company that we cannot match to an entry in the German register, usually a company abroad. We do not know its shareholders, so the chain ends here, `no_further_shareholder_data` the shareholder is a German company that we know, but no shareholder list exists for it, for example a KG, `cycle` the chain leads back to a company that is already in it, for example when a company holds its own shares, `unknown` nothing is known about the shareholder, neither name nor share	`"cycle"`	as above
ubos.unresolved_beneficial_owners[].namestring\|null	Name of the shareholder where the chain ends.Empty when the reason is unknown	`"ENSoXX Holding AG"`	as above
ubos.unresolved_beneficial_owners[].entity_idstring\|null	Its ID, for its own company profile.Empty when the shareholder is not matched to a company in our data, i.e. for the reasons unlinked and unknown	`"58d67a0bb99b2bc5644cb8daba58e6a6"`	as above
ubos.unresolved_beneficial_owners[].legal_formstring\|null	Its legal form.	`"AG"`	as above
ubos.unresolved_beneficial_owners[].addressobject\|array	Its address with street, house_number, postal_code, city, county, state, country and coordinates.Empty when no address is known; the value is then an empty list []	–	as above
ubos.unresolved_beneficial_owners[].registrationobject\|array	Its register entry with court, register_type and register_number, also from foreign registers.Empty when no entry is known; the value is then an empty list []	–	as above
ubos.unresolved_beneficial_owners[].ownership_percentagenumber	The unresolved share in percent, calculated through to the requested company. It can be 0.	`0`	as above
ubos.unresolved_beneficial_owners[].viaarray	The companies the chain runs through up to here, first the direct shareholder of the requested company.Empty when the unresolved share is held directly in the requested company	–	as above
ubos.unresolved_beneficial_owners[].via[].depthinteger	The level: 1 is a direct shareholder of the requested company. Next to it are the company's name and entity_id.	`1`	as above
ubos.unresolved_beneficial_owners[].via[].step_percentagenumber	Share in percent at this level.	`94.5`	as above
ubos.coverageobject	How much of the capital is traced to people and how much remains open. The two values do not always add up to 100.	–	as above
ubos.coverage.resolved_percentagenumber	Traced to people, in percent.	`5.5`	as above
ubos.coverage.unresolved_percentagenumber	Not traced to people, in percent.	`0`	as above

1{2  "entity_id": "94eb910fef13f94585c48c263fa446d4",3  "name": "Hetzner Online GmbH",4  "ubos": {5    "beneficial_owners": [6      {7        "person": {8          "entity_id": "08ed5f967956831ca6588930fd2693ed",9          "name": "Max Felix Mustermann",10          "birth_date": "1976-01-15",11          "name_parts": {12            "given": "Max Felix",13            "family": "Mustermann",14            "canonical_name": "Mustermann, Max Felix"15          },16          "location": {17            "home": {18              "city": "Musterheim",19              "county": "Musterheim (Landkreis)",20              "state": "Bayern",21              "country": "DEU"22            }23          }24        },25        "ownership_percentage": 5.5,26        "paths": [27          {28            "percentage": 5.5,29            "via": []30          }31        ]32      }33    ],34    "unresolved_beneficial_owners": [35      {36        "reason": "cycle",37        "entity_id": "58d67a0bb99b2bc5644cb8daba58e6a6",38        "name": "ENSoXX Holding AG",39        "legal_form": "AG",40        "address": {41          "house_number": "25",42          "street": "Industriestraße",43          "postal_code": "91710",44          "city": "Gunzenhausen",45          "county": "Weißenburg-Gunzenhausen",46          "state": "Bayern",47          "country": "DEU",48          "coordinates": {49            "latitude": 49.12483,50            "longitude": 10.7805251          }52        },53        "registration": {54          "court": "Ansbach",55          "register_type": "HRB",56          "register_number": "6211"57        },58        "ownership_percentage": 0,59        "via": [60          {61            "depth": 1,62            "name": "ENSoXX GmbH",63            "entity_id": "dd1cfcd3a25b5a63d549d768e2fcaaaf",64            "step_percentage": 94.565          },66          {67            "depth": 2,68            "name": "ENSoXX Holding AG",69            "entity_id": "58d67a0bb99b2bc5644cb8daba58e6a6",70            "step_percentage": 10071          }72        ]73      },74      {75        "reason": "unknown",76        "entity_id": null,77        "name": null,78        "legal_form": null,79        "address": [],80        "registration": [],81        "ownership_percentage": 0,82        "via": [83          {84            "depth": 1,85            "name": "ENSoXX GmbH",86            "entity_id": "dd1cfcd3a25b5a63d549d768e2fcaaaf",87            "step_percentage": 94.588          },89          {90            "depth": 2,91            "name": "ENSoXX Holding AG",92            "entity_id": "58d67a0bb99b2bc5644cb8daba58e6a6",93            "step_percentage": 10094          }95        ]96      },97      {98        "reason": "unknown",99        "entity_id": null,100        "name": null,101        "legal_form": null,102        "address": [],103        "registration": [],104        "ownership_percentage": 0,105        "via": [106          {107            "depth": 1,108            "name": "ENSoXX GmbH",109            "entity_id": "dd1cfcd3a25b5a63d549d768e2fcaaaf",110            "step_percentage": 94.5111          },112          {113            "depth": 2,114            "name": "ENSoXX Holding AG",115            "entity_id": "58d67a0bb99b2bc5644cb8daba58e6a6",116            "step_percentage": 100117          }118        ]119      }120    ],121    "coverage": {122      "resolved_percentage": 5.5,123      "unresolved_percentage": 0124    }125  }126}

200 · Example response: Hetzner Online GmbH with the feature ubos. In our example request, one person was in beneficial_owners with 5.5%. The chain through ENSoXX GmbH, Ansbach HRB 6105, ended in unresolved_beneficial_owners with the reasons cycle and unknown.

We calculate the data from the shareholder lists. Data on beneficial owners from the Transparenzregister (transparency register) has not been publicly accessible since the end of 2022.

Shareholdings

The feature shareholdings shows the other direction: which companies the requested company holds shares in. The shareholdings come from the shareholder lists of those companies. It costs 5 credits when there are shareholdings.

curl -G "https://handelsregister.ai/api/v1/fetch-organization" \
  -H "x-api-key: YOUR_API_KEY" \
  --data-urlencode 'q=Hetzner Online GmbH' \
  --data-urlencode 'feature=shareholdings'

import requests

response = requests.get(
    "https://handelsregister.ai/api/v1/fetch-organization",
    headers={"x-api-key": "YOUR_API_KEY"},
    params={
        "q": "Hetzner Online GmbH",
        "feature": ["shareholdings"],
    },
)
data = response.json()

const url = new URL("https://handelsregister.ai/api/v1/fetch-organization");
url.searchParams.append("q", "Hetzner Online GmbH");
url.searchParams.append("feature", "shareholdings");

const response = await fetch(url, {
  headers: { "x-api-key": "YOUR_API_KEY" },
});
const data = await response.json();

Field
Field	Meaning	Example	Availability
shareholdingsobject\|null	The companies in which the requested company holds shares.Empty when no shareholding is known`shareholdings` · Beta	–	mostly: AG, SE, KGaA partly: GmbH, UG rarely: GmbH & Co. KG, KG, OHG, e.K., eG, PartG
shareholdings.holdings.currentarray	The current shareholdings, one per company.	–	as above
shareholdings.holdings.current[].organizationobject	The company in which the shares are held.	–	as above
shareholdings.holdings.current[].organization.entity_idstring	ID of the company, for its company profile.	`"63529c3a793e9f002196b4fd344e1241"`	as above
shareholdings.holdings.current[].organization.namestring\|null	Name of the company.	`"Hetzner Cloud GmbH"`	as above
shareholdings.holdings.current[].organization.legal_formstring\|null	Legal form of the company.	`"GmbH"`	as above
shareholdings.holdings.current[].organization.statusstring\|null	Status of the company in the register, for example ACTIVE.	`"ACTIVE"`	as above
shareholdings.holdings.current[].organization.addressobject\|array	Address of the company, structured like address in the basic data.Empty when no address is known; the value is then an empty list []	–	as above
shareholdings.holdings.current[].organization.registrationobject\|array	Register entry of the company with court, register_type and register_number.Empty when no entry is known; the value is then an empty list []	–	as above
shareholdings.holdings.current[].ownership.percentagenumber\|null	Share in percent: 100 means 100 %.Empty when the list yields no share	`100`	as above
shareholdings.holdings.current[].ownership.contributionobject	Nominal amount of the shares with amount and currency.	–	as above
shareholdings.holdings.current[].as_ofstring	Date of the shareholder list the shareholding comes from.	`"2017-09-19"`	as above
shareholdings.summary.total_currentinteger	Number of current shareholdings.	`2`	as above

1{2  "entity_id": "94eb910fef13f94585c48c263fa446d4",3  "name": "Hetzner Online GmbH",4  "shareholdings": {5    "holdings": {6      "current": [7        {8          "organization": {9            "entity_id": "63529c3a793e9f002196b4fd344e1241",10            "name": "Hetzner Cloud GmbH",11            "status": "ACTIVE",12            "legal_form": "GmbH",13            "address": {14              "house_number": "12A",15              "street": "Feringastraße",16              "postal_code": "85774",17              "city": "Unterföhring",18              "county": "München (Landkreis)",19              "state": "Bayern",20              "country": "DEU",21              "coordinates": {22                "latitude": 48.17815,23                "longitude": 11.6348724              }25            },26            "registration": {27              "court": "München",28              "register_type": "HRB",29              "register_number": "226782"30            }31          },32          "ownership": {33            "percentage": 100,34            "contribution": {35              "amount": 25000,36              "currency": "EUR"37            }38          },39          "as_of": "2017-09-19"40        },41        {42          "organization": {43            "entity_id": "997f1b8314b8b56573208ae2334abb1d",44            "name": "possum Projekt 1 GmbH",45            "status": "ACTIVE",46            "legal_form": "GmbH",47            "address": {48              "house_number": "169-173",49              "street": "Meisenburgstraße",50              "postal_code": "45133",51              "city": "Essen",52              "county": "Essen",53              "state": "Nordrhein-Westfalen",54              "country": "DEU",55              "coordinates": {56                "latitude": 51.40102,57                "longitude": 6.9580558              }59            },60            "registration": {61              "court": "Essen",62              "register_type": "HRB",63              "register_number": "35604"64            }65          },66          "ownership": {67            "percentage": 100,68            "contribution": {69              "amount": 25000,70              "currency": "EUR"71            }72          },73          "as_of": "2026-08-18"74        }75      ]76    },77    "summary": {78      "total_current": 279    }80  }81}

200 · Example response: Hetzner Online GmbH with the feature shareholdings

The shareholdings of a person are in the person profile, with the same feature.

Group structures

You assemble group connections from several data points. shareholders and shareholdings show the shareholdings one level up and down, ubos the people at the end of the chain.

The Company network connects companies and people across two levels. It also includes affiliated companies.

Mergers, splits and other transformations are under M&A.