주주와 지분 – 문서 | handelsregister.ai

기능
기능	반환 내용	크레딧	이용 가능
shareholders	주주: 지분이 포함된 현재 주주와 이전 주주 명부	5	모든 계정 · 베타
shareholders_deep	심층 주주 정보: 지분 번호, 지분 보유 시작 시점, 최근 변경이 포함된 보유자	80	Max
ubos	실소유자(UBO): 주주 명부에서 계산한 회사 뒤의 인물	10	모든 계정 · 베타
shareholdings	지분 참여: 회사 자신이 지분을 가진 회사	5	모든 계정 · 베타

법적 형태별 주주

등기부가 소유자에 대해 말하는 내용은 법적 형태에 따라 달라요. 표는 대개 받는 내용을 보여 줘요.

법적 형태
법적 형태	응답의 주주
GmbH, UG	§ 40 GmbHG에 따른 주주 명부의 모든 주주, 액면가와 자본금(Stammkapital) 대비 지분 포함, 이전 명부도.
AG, SE, KGaA	AG의 주주는 어떤 공개 등기부에도 없으므로 개별 사례에서만.
GmbH & Co. KG	등기부의 유한책임사원(Kommanditisten)과 책임액, 일부는 무한책임사원 GmbH도.
KG, OHG	등기된 사원: KG는 무한책임사원(Komplementäre)과 유한책임사원, OHG는 개인적으로 무한책임을 지는 사원.
e.K.	소유자.
eG	없음. 협동조합의 조합원 명부는 공개되지 않아요.
PartG	등기된 파트너.

주주 명부는 다양한 레이아웃의 스캔 문서인 경우가 많아요. 이를 자동으로 추출해요. 이를 위해 최신 기술을 쓰고 품질에 많은 투자를 하지만, 개별 오류가 있을 수 있어요.

주주

shareholders 기능은 현재 주주를 반환해요: GmbH는 최신 주주 명부에서, 인적 회사와 개인 상인은 등기부에서. 5 크레딧가 들지만, 현재 주주를 기재할 때만이에요. 이전 명부만 반환하면 비용이 들지 않아요.

entries의 각 항목은 인물이나 회사를 설명해요. 인물에는 first_name, last_name, birth_date가, 회사에는 entity_name, country_code, 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();

필드
필드	의미	예시	제공 빈도
shareholdersobject\|null	회사의 주주: entries에 현재 상태, history에 이전 상태.비어 있는 경우: 알려진 주주가 없음, 예: AG나 eG`shareholders` · 베타	–	대부분: GmbH, UG, GmbH & Co. KG, KG, OHG, e.K., PartG 드묾: AG, SE, KGaA 없음: eG
shareholders.entriesarray	현재 주주, 인물이나 회사마다 항목 하나.	–	위와 같음
shareholders.entries[].shareholderobject	지분을 가진 주체: 아래 필드가 있는 인물이나 회사.	–	위와 같음
shareholders.entries[].shareholder.entity_idstring\|null	인물이나 회사의 ID, 그 인물 프로필이나 회사 프로필용.비어 있는 경우: 주주를 확실하게 매칭할 수 없었음	`"dd1cfcd3a25b5a63d549d768e2fcaaaf"`	위와 같음
shareholders.entries[].shareholder.first_namestring	인물의 이름, 등기된 모든 이름 포함.	–	항상: e.K. 대부분: GmbH, UG, GmbH & Co. KG, KG, OHG, PartG 드묾: AG, SE, KGaA 없음: eG
shareholders.entries[].shareholder.last_namestring	인물의 성.	–	위와 같음
shareholders.entries[].shareholder.birth_datestring\|null	인물의 생년월일, YYYY-MM-DD 형식.비어 있는 경우: 문서에 생년월일이 없음	–	위와 같음
shareholders.entries[].shareholder.entity_namestring	주주인 회사의 이름.	`"ENSoXX GmbH"`	대부분: GmbH, UG, GmbH & Co. KG 드묾: AG, SE, KGaA, KG, OHG 없음: e.K., eG, PartG
shareholders.entries[].shareholder.country_codestring\|null	ISO 세 글자 코드(ISO 3166-1 alpha-3)로 된 회사의 국가, 예: DEU.	`"DEU"`	위와 같음
shareholders.entries[].shareholder.registration_referencestring\|null	문서에 적힌 그대로의 회사 등기, 텍스트.비어 있는 경우: 문서에 등기가 없음, 외국 회사에서 흔함	`"AG Ansbach HRB 6105"`	위와 같음
shareholders.entries[].shareholder.addressstring\|null	문서에 적힌 그대로의 주소, 거주지 또는 소재지, 텍스트.비어 있는 경우: 문서에 주소가 없음	`"Gunzenhausen"`	대부분: GmbH, UG, GmbH & Co. KG, KG, OHG, e.K., PartG 드묾: AG, SE, KGaA 없음: eG
shareholders.entries[].contributionobject\|null	amount와 currency가 담긴 지분 금액: GmbH는 지분의 액면가, 유한책임사원은 등기된 책임액(Haftsumme).비어 있는 경우: 등기된 금액이 없음, 예: 무한책임사원이나 e.K.의 소유자	–	대부분: GmbH, UG, GmbH & Co. KG 일부: KG, OHG 드묾: AG, SE, KGaA 없음: e.K., eG, PartG
shareholders.entries[].contribution_rationumber\|null	자본금 대비 지분을 소수로: 1은 100%, 0.245는 24.5%.비어 있는 경우: 지분을 도출할 수 없음, 예: 인적 회사	`0.945`	대부분: GmbH, UG 드묾: AG, SE, KGaA, GmbH & Co. KG, KG, OHG 없음: e.K., eG, PartG
shareholders.entries[].roleobject	역할: 고정 코드인 label과, 긴 이름과 짧은 이름이 담긴 de, en, 예: Kommanditist와 Kom.	–	대부분: GmbH, UG, GmbH & Co. KG, KG, OHG, e.K., PartG 드묾: AG, SE, KGaA 없음: eG
shareholders.entries[].role.labelstring	고정 코드로 된 역할. 새 값이 추가될 수 있어요.값: `SHAREHOLDER` 주주 명부상의 주주, `LIMITED_PARTNER` 유한책임사원(Kommanditist), `FULLY_LIABLE_PARTNER` 무한책임사원(persönlich haftender Gesellschafter), `PARTNER` PartG의 파트너, `OWNER` e.K.의 소유자	`"SHAREHOLDER"`	위와 같음
shareholders.total_capitalobject\|null	amount와 currency가 담긴 주주 명부상의 자본금, contribution_ratio의 기준.비어 있는 경우: 명부에 자본금이 없음, 그리고 인적 회사	–	대부분: GmbH, UG 드묾: AG, SE, KGaA, GmbH & Co. KG, KG, OHG 없음: e.K., eG, PartG

주주의 entity_id로 그 회사 프로필이나 인물 프로필을 가져와요. 이렇게 소유 사슬을 한 단계씩 따라가요.

주주 이력

shareholders.history는 추가 비용 없이 와요. 현재 명부의 날짜와 이전 주주 명부가 최신순으로 담겨요.

KG나 GmbH & Co. KG의 이전 사원은 등기부의 입사일과 퇴사일과 함께 register_ownership에 있어요. OHG, PartG, e.K.는 shareholders_deep에서 찾을 수 있어요.

필드
필드	의미	예시	제공 빈도
shareholders.historyobject	추가 비용 없는 주주의 이전 상태.비어 있는 경우: 이전 상태가 없음; 이때 필드가 없음, 예: OHG, PartG, e.K.`shareholders` · 베타	–	대부분: GmbH, UG 일부: GmbH & Co. KG, KG, OHG 드묾: AG, SE, KGaA 없음: e.K., eG, PartG
shareholders.history.current_as_ofstring\|null	entries의 출처인 주주 명부의 날짜.비어 있는 경우: 주주가 등기부에서 옴	`"2015-08-21"`	대부분: GmbH, UG 드묾: AG, SE, KGaA, GmbH & Co. KG, KG, OHG 없음: e.K., eG, PartG
shareholders.history.pastarray	이전 주주 명부, 최신순.비어 있는 경우: 명부가 하나뿐임	–	위와 같음
shareholders.history.past[].as_ofstring	이 주주 명부의 날짜.	`"2015-07-28"`	위와 같음
shareholders.history.past[].data.total_capitalobject\|null	amount와 currency가 담긴 이 명부상의 자본금. 오래된 명부는 일부 DEM으로 표시해요.	–	위와 같음
shareholders.history.past[].data.shareholdersarray	이 명부상의 주주, entries와 같은 필드.	–	위와 같음
shareholders.history.register_ownershipobject	KG와 GmbH & Co. KG: 등기부상의 이전 사원, past에.	–	일부: GmbH & Co. KG, KG, OHG 없음: GmbH, UG, AG, SE, KGaA, e.K., eG, PartG
shareholders.history.register_ownership.past[].shareholderobject	이전 사원, entries와 같은 필드.	–	위와 같음
shareholders.history.register_ownership.past[].roleobject	그 역할, entries의 role과 같은 구조.	–	위와 같음
shareholders.history.register_ownership.past[].effective_fromstring\|null	등기된 시작일, YYYY-MM-DD 형식.	`"2022-01-07"`	위와 같음
shareholders.history.register_ownership.past[].effective_tostring\|null	등기된 종료일.	`"2026-07-06"`	위와 같음
shareholders.history.register_ownership.past[].effective_to_inferredboolean	effective_to가 명시적으로 등기된 것이 아니라 추론된 것이면 true.	`false`	위와 같음
shareholders.history.register_ownership.past[].contributionnull	여기서는 항상 null.	–	위와 같음
shareholders.history.register_ownership.past[].contribution_rationull	여기서는 항상 null.	–	위와 같음

심층 주주 정보

shareholders_deep 기능은 Max 플랜에 포함돼요. 80 크레딧가 들지만, 현재 문서에 보유자가 하나 이상 기재되어 있을 때만이에요.

최신 명부만이 아니라 회사의 모든 주주 명부를 읽어요. 그래서 누가 언제부터 지분을 갖고 있는지, 이전 상태는 어땠는지, 마지막 명부가 무엇을 바꿨는지 보여 줘요.

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();

문서. record는 현재 상태가 어디서 왔는지, share_capital은 그 문서에 따른 자본금을 알려 줘요.

필드
필드	의미	예시	제공 빈도
shareholders_deepobject\|null	보유자, 지분, 이전 문서, 마지막 변경.비어 있는 경우: 현재 문서도 등기된 사원도 알려져 있지 않음, AG, SE, eG에서 흔함`shareholders_deep` · Max부터	–	대부분: GmbH, UG, GmbH & Co. KG, KG, OHG, e.K., PartG 드묾: AG, SE, KGaA 없음: eG
shareholders_deep.recordobject	현재 상태의 출처인 문서: 날짜와 출처.	–	위와 같음
shareholders_deep.record.datestring\|null	문서가 가리키는 날짜. 대개 문서가 보여 주는 변경 직후예요.비어 있는 경우: 주주가 등기부에서 옴(`COMMERCIAL_REGISTER`)	`"2015-08-18"`	대부분: GmbH, UG 드묾: AG, SE, KGaA, GmbH & Co. KG, KG, OHG 없음: e.K., eG, PartG
shareholders_deep.record.sourcestring	문서의 종류.값: `SHAREHOLDER_LIST` 주주 명부(Gesellschafterliste), `FOUNDING_DOCUMENT` 설립 서류, 즉 Musterprotokoll(표준 의정서) 또는 Gesellschaftsvertrag(정관), `COMMERCIAL_REGISTER` 등기부에 등기된 사원 또는 소유자	`"SHAREHOLDER_LIST"`	대부분: GmbH, UG, GmbH & Co. KG, KG, OHG, e.K., PartG 드묾: AG, SE, KGaA 없음: eG
shareholders_deep.share_capitalobject\|null	문서상의 자본금: value, currency, basis.비어 있는 경우: 문서에 자본금이 없음, 그리고 COMMERCIAL_REGISTER에서는 항상	–	대부분: GmbH, UG 드묾: AG, SE, KGaA, GmbH & Co. KG, KG, OHG 없음: e.K., eG, PartG
shareholders_deep.share_capital.basisstring	금액의 출처.값: `REPORTED` 문서에 기재됨, `CALCULATED` 지분 수와 액면가로 계산함	`"REPORTED"`	위와 같음

보유자. entries의 각 항목은 문서의 한 줄이며, 가장 큰 지분이 먼저 와요. 한 사람이 여러 줄에 있으면 목록에 여러 번 나와요.

필드
필드	의미	예시	제공 빈도
shareholders_deep.entriesarray	현재 보유자, 항목마다 문서의 한 줄, 가장 큰 지분이 먼저.`shareholders_deep` · Max부터	–	대부분: GmbH, UG, GmbH & Co. KG, KG, OHG, e.K., PartG 드묾: AG, SE, KGaA 없음: eG
shareholders_deep.entries[].holderobject	지분을 가진 주체. type에 따라 이어지는 필드가 정해져요.	–	위와 같음
shareholders_deep.entries[].holder.typestring	보유자의 종류.값: `ORGANIZATION` 회사 또는 기타 조직, `PERSON` 자연인, `JOINT` 공동 보유 지분, 예: 상속인 공동체, members 포함	`"ORGANIZATION"`	위와 같음
shareholders_deep.entries[].holder.entity_idstring\|null	보유자의 ID, 그 회사 프로필이나 인물 프로필용.비어 있는 경우: 보유자를 확실하게 매칭할 수 없었음, 그리고 JOINT에서는 항상	`"dd1cfcd3a25b5a63d549d768e2fcaaaf"`	위와 같음
shareholders_deep.entries[].holder.namestring	이름. 매칭된 보유자는 현재 이름, 그렇지 않으면 문서에 적힌 그대로.	`"ENSoXX GmbH"`	위와 같음
shareholders_deep.entries[].holder.birth_datestring\|null	인물에만: 생년월일.비어 있는 경우: 문서에 없음	–	항상: e.K. 대부분: GmbH, UG, GmbH & Co. KG, KG, OHG, PartG 드묾: AG, SE, KGaA 없음: eG
shareholders_deep.entries[].holder.legal_formstring\|null	조직에만: 텍스트로 된 법적 형태, 예: GmbH 또는 Ltd.	`"GmbH"`	대부분: GmbH, UG, GmbH & Co. KG 드묾: AG, SE, KGaA, KG, OHG 없음: e.K., eG, PartG
shareholders_deep.entries[].holder.statusstring\|null	조직에만: 등기부상의 현재 상태.비어 있는 경우: 보유자가 매칭되지 않음, 그리고 history의 이전 문서에서는 항상값: `ACTIVE` 활성, `INACTIVE` 더 이상 활성 상태가 아님, 예: 말소 또는 합병	`"ACTIVE"`	위와 같음
shareholders_deep.entries[].holder.citystring\|null	소재지 또는 거주지.	`"Gunzenhausen"`	대부분: GmbH, UG, GmbH & Co. KG, KG, OHG, e.K., PartG 드묾: AG, SE, KGaA 없음: eG
shareholders_deep.entries[].holder.countrystring\|null	ISO 세 글자 코드(ISO 3166-1 alpha-3)로 된 국가, 예: DEU, AUT, LUX.	`"DEU"`	위와 같음
shareholders_deep.entries[].holder.registrationobject\|null	조직에만: court, register_type, register_number.비어 있는 경우: 읽을 수 있는 등기가 없음, 예: 많은 외국 회사	–	대부분: GmbH, UG, GmbH & Co. KG 드묾: AG, SE, KGaA, KG, OHG 없음: e.K., eG, PartG
shareholders_deep.entries[].holder.registration_textstring\|null	조직에만: registration이 없거나 법원을 기재하지 않을 때의 텍스트 등기.	`null`	드묾
shareholders_deep.entries[].rolestring	보유자의 역할. 새 값이 추가될 수 있어요.값: `SHAREHOLDER` 주주 명부나 설립 서류상의 주주, `LIMITED_PARTNER` 유한책임사원(Kommanditist), `FULLY_LIABLE_PARTNER` 무한책임사원(persönlich haftender Gesellschafter), `PARTNER` PartG의 파트너, `OWNER` e.K.의 소유자	`"SHAREHOLDER"`	대부분: GmbH, UG, GmbH & Co. KG, KG, OHG, e.K., PartG 드묾: AG, SE, KGaA 없음: eG
shareholders_deep.entries[].sincestring\|null	보유자가 지분을 갖기 시작한 시점. 등기된 사원은 등기일.비어 있는 경우: 날짜를 정할 수 없음, 그리고 JOINT에서는 항상	`"2015-08-18"`	위와 같음
shareholders_deep.entries[].since_basisstring\|null	since가 얼마나 확실한지.값: `ENTRY_RECORDED` 이 날짜부터 문서로 확인됨: 그 이전 명부에는 보유자가 아직 없음, `EARLIEST_RECORD` 가장 오래된 문서에 이미 있음, 그러니 최소 이 날짜부터 주주	`"ENTRY_RECORDED"`	위와 같음

지분. ownership은 보유자가 얼마나 갖고 있는지 설명해요: 퍼센트로, 액면가로, 지분의 일련번호로.

필드
필드	의미	예시	제공 빈도
shareholders_deep.entries[].ownershipobject	보유자의 지분.`shareholders_deep` · Max부터	–	대부분: GmbH, UG, GmbH & Co. KG, KG, OHG, e.K., PartG 드묾: AG, SE, KGaA 없음: eG
shareholders_deep.entries[].ownership.percentagenumber\|null	자본금 대비 지분(%), 0~100. 의결권이 아니라 직접 지분이에요.비어 있는 경우: 지분을 확실하게 정할 수 없음, 그리고 인적 회사의 등기된 사원에서는 항상	`94.5`	대부분: GmbH, UG 드묾: AG, SE, KGaA, GmbH & Co. KG, KG, OHG 없음: e.K., eG, PartG
shareholders_deep.entries[].ownership.percentage_basisstring\|null	percentage의 출처.값: `REPORTED` 문서에 기재되었거나 문서의 액면가와 자본금에서 도출함, `CALCULATED` 지분 수와 액면가로 계산함	`"REPORTED"`	위와 같음
shareholders_deep.entries[].ownership.nominal_amountobject\|null	value와 currency가 담긴 액면가 합계. 유한책임사원은 등기된 책임액(Haftsumme).비어 있는 경우: 알려진 금액이 없음	–	대부분: GmbH, UG, GmbH & Co. KG 일부: KG, OHG 드묾: AG, SE, KGaA 없음: e.K., eG, PartG
shareholders_deep.entries[].ownership.share_countinteger\|null	지분(Geschäftsanteile) 수.비어 있는 경우: 모든 지분의 수를 알 수는 없음	`47250`	대부분: GmbH, UG 드묾: AG, SE, KGaA, GmbH & Co. KG, KG, OHG 없음: e.K., eG, PartG
shareholders_deep.entries[].ownership.share_rangesarray	명부의 일련번호로 본 지분, 같은 지분이 이어지는 구간마다 범위 하나.	–	위와 같음
shareholders_deep.entries[].ownership.share_ranges[].frominteger\|null	범위의 첫 일련번호.	`1`	위와 같음
shareholders_deep.entries[].ownership.share_ranges[].tointeger\|null	범위의 마지막 일련번호.	`47250`	위와 같음
shareholders_deep.entries[].ownership.share_ranges[].countinteger\|null	범위 안의 지분 수.	`47250`	위와 같음
shareholders_deep.entries[].ownership.share_ranges[].nominal_valueobject\|null	value와 currency가 담긴 범위 안 지분당 액면가.	–	위와 같음

이력과 변경. history에는 같은 필드로 된 이전 문서가 담겨요. 보유자는 당시 문서에 적힌 그대로 나와요. changes는 현재 상태를 이전 상태와 비교해요.

필드
필드	의미	예시	제공 빈도
shareholders_deep.historyarray	이전 문서, 최신순, 각각 record, share_capital, entries 포함. 이전에 등기된 사원은 마지막 항목에 모여 있어요.`shareholders_deep` · Max부터	–	대부분: GmbH, UG 드묾: AG, SE, KGaA, GmbH & Co. KG, KG, OHG 없음: e.K., eG, PartG
shareholders_deep.history[].entries[].holder.membersarray	JOINT의 경우: PERSON 또는 ORGANIZATION 유형의 공동 보유자, holder와 같은 필드.	–	드묾
shareholders_deep.history[].entries[].untilstring\|null	COMMERCIAL_REGISTER가 있는 history 항목에만: 사원이 떠난 시점.	–	일부: GmbH & Co. KG, KG, OHG, PartG 드묾: e.K. 없음: GmbH, UG, AG, SE, KGaA, eG
shareholders_deep.changesobject\|null	현재 문서에서 이전 문서와 비교해 바뀐 것.비어 있는 경우: 이전 문서가 없음, 그리고 현재 상태가 등기부나 설립 서류에서 온 경우	–	대부분: GmbH, UG 드묾: AG, SE, KGaA, GmbH & Co. KG, KG, OHG 없음: e.K., eG, PartG
shareholders_deep.changes.compared_tostring\|null	이전 문서의 날짜.	`"2015-07-16"`	위와 같음
shareholders_deep.changes.joinedarray	새 보유자: entity_id, type, name이 담긴 holder와 percentage.	–	위와 같음
shareholders_deep.changes.leftarray	떠난 보유자, 마지막으로 가졌던 지분 포함.	–	위와 같음
shareholders_deep.changes.changedarray	지분이 바뀐 보유자.	–	위와 같음
shareholders_deep.changes.changed[].percentage_beforenumber\|null	이전 문서의 지분(%).	`100`	위와 같음
shareholders_deep.changes.changed[].percentage_afternumber\|null	현재 문서의 지분(%).	`5.5`	위와 같음

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 · 예시 응답: shareholders_deep 기능을 쓴 Hetzner Online GmbH

shareholders와 비교해 shareholders_deep는 지분 번호, 지분 보유 시작일, 변경, 구성원이 포함된 공동 보유 지분을 더해요. 회사와 연도를 넘어 비교하려면 같은 기능을 일관되게 쓰는 것이 좋아요.

실소유자

실소유자는 최종적으로 회사를 소유하는 자연인이에요. ubos 기능은 주주 명부를 소유 단계별로 인물까지 따라가요. 목록에는 최소 기준 없이 계산된 지분이 있는 모든 인물이 기재돼요. 데이터를 반환하면 10 크레딧가 들어요.

지분을 인물까지 추적할 수 없으면 이유와 함께 unresolved_beneficial_owners에 있어요. 해외 회사가 보유한 경우가 많아요. 저희 데이터는 독일 회사를 다루므로 해외 회사의 주주는 알지 못해요. coverage는 자본금의 몇 퍼센트가 인물까지 추적되고 얼마가 남았는지 보여 줘요. 두 값의 합이 항상 100이 되지는 않아요. 나머지는 주주 데이터에 보유자가 기재되어 있지 않아요.

이 기능은 결과를 반환하면 바로 과금돼요. 모든 지분이 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();

필드
필드	의미	예시	제공 빈도
ubosobject\|null	주주 명부에서 소유 단계를 따라 계산한 실소유자.비어 있는 경우: 주주 명부로 사슬을 만들 수 없음, 예: AG, eG, e.K.`ubos` · 베타	–	대부분: GmbH, UG 드묾: AG, SE, KGaA, GmbH & Co. KG, KG, OHG 없음: e.K., eG, PartG
ubos.beneficial_ownersarray	직접 또는 다른 회사를 통해 회사를 소유한 인물.비어 있는 경우: 인물까지 추적할 수 있는 지분이 없음	–	위와 같음
ubos.beneficial_owners[].personobject	아래 필드가 있는 인물.	–	일부: GmbH, UG 드묾: AG, SE, KGaA, GmbH & Co. KG, KG, OHG 없음: e.K., eG, PartG
ubos.beneficial_owners[].person.entity_idstring\|null	인물 ID, 인물 프로필용.비어 있는 경우: 인물을 확실하게 매칭할 수 없었음	–	위와 같음
ubos.beneficial_owners[].person.namestring	전체 이름.	–	위와 같음
ubos.beneficial_owners[].person.name_partsobject	구성 요소로 나눈 이름: given과 family, 알려진 경우 canonical_name.	–	위와 같음
ubos.beneficial_owners[].person.birth_datestring\|null	생년월일.	–	위와 같음
ubos.beneficial_owners[].person.locationobject\|null	home의 거주지: city, county, state, country.비어 있는 경우: 알려진 거주지가 없음	–	위와 같음
ubos.beneficial_owners[].ownership_percentagenumber	모든 경로를 합산한 인물의 총 지분(%).	`50`	위와 같음
ubos.beneficial_owners[].pathsarray	인물에 이르는 각 경로와 그 경로의 지분.	–	위와 같음
ubos.beneficial_owners[].paths[].percentagenumber	이 경로로 이어지는 지분(%).	`50`	위와 같음
ubos.beneficial_owners[].paths[].viaarray	이 경로의 회사, 요청한 회사의 직접 주주(depth 1)부터. 필드는 해소되지 않은 지분의 via와 같아요.비어 있는 경우: 인물이 직접 지분을 보유함	–	위와 같음

필드
필드	의미	예시	제공 빈도
ubos.unresolved_beneficial_ownersarray	인물까지 추적할 수 없었던 지분.비어 있는 경우: 모든 지분이 해소됨`ubos` · 베타	–	대부분: GmbH, UG 드묾: AG, SE, KGaA, GmbH & Co. KG, KG, OHG 없음: e.K., eG, PartG
ubos.unresolved_beneficial_owners[].reasonstring	사슬이 여기서 끝나는 이유. 새 값이 추가될 수 있어요.값: `unlinked` 주주가 독일 등기부의 항목과 매칭할 수 없는 회사이며, 대개 해외 회사. 그 주주를 알 수 없으므로 사슬이 여기서 끝남, `no_further_shareholder_data` 주주가 저희가 아는 독일 회사지만 주주 명부가 없음, 예: KG, `cycle` 사슬이 이미 그 안에 있는 회사로 되돌아감, 예: 회사가 자기 지분을 보유하는 경우, `unknown` 주주에 대해 이름도 지분도 알려진 것이 없음	`"cycle"`	위와 같음
ubos.unresolved_beneficial_owners[].namestring\|null	사슬이 끝나는 주주의 이름.비어 있는 경우: 이유가 unknown	`"ENSoXX Holding AG"`	위와 같음
ubos.unresolved_beneficial_owners[].entity_idstring\|null	그 ID, 회사 프로필용.비어 있는 경우: 주주가 저희 데이터의 회사와 매칭되지 않음, 즉 이유가 unlinked와 unknown인 경우	`"58d67a0bb99b2bc5644cb8daba58e6a6"`	위와 같음
ubos.unresolved_beneficial_owners[].legal_formstring\|null	그 법적 형태.	`"AG"`	위와 같음
ubos.unresolved_beneficial_owners[].addressobject\|array	street, house_number, postal_code, city, county, state, country, coordinates가 담긴 주소.비어 있는 경우: 알려진 주소가 없음; 이때 값은 빈 목록 []	–	위와 같음
ubos.unresolved_beneficial_owners[].registrationobject\|array	court, register_type, register_number가 담긴 등기, 외국 등기부 포함.비어 있는 경우: 알려진 등기가 없음; 이때 값은 빈 목록 []	–	위와 같음
ubos.unresolved_beneficial_owners[].ownership_percentagenumber	요청한 회사까지 계산한 해소되지 않은 지분(%). 0일 수 있어요.	`0`	위와 같음
ubos.unresolved_beneficial_owners[].viaarray	여기까지 사슬이 지나온 회사, 요청한 회사의 직접 주주부터.비어 있는 경우: 해소되지 않은 지분이 요청한 회사에 직접 보유됨	–	위와 같음
ubos.unresolved_beneficial_owners[].via[].depthinteger	단계: 1은 요청한 회사의 직접 주주예요. 옆에 회사 이름과 entity_id가 있어요.	`1`	위와 같음
ubos.unresolved_beneficial_owners[].via[].step_percentagenumber	이 단계의 지분(%).	`94.5`	위와 같음
ubos.coverageobject	자본금 중 인물까지 추적된 부분과 남은 부분. 두 값의 합이 항상 100이 되지는 않아요.	–	위와 같음
ubos.coverage.resolved_percentagenumber	인물까지 추적됨(%).	`5.5`	위와 같음
ubos.coverage.unresolved_percentagenumber	인물까지 추적되지 않음(%).	`0`	위와 같음

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 · 예시 응답: ubos 기능을 쓴 Hetzner Online GmbH. 예시 요청에서 한 사람이 5.5%로 beneficial_owners에 있었어요. ENSoXX GmbH, Ansbach HRB 6105를 거치는 사슬은 이유 cycle과 unknown으로 unresolved_beneficial_owners에서 끝났어요.

데이터는 주주 명부에서 계산해요. Transparenzregister(투명성 등기부)의 실소유자 데이터는 2022년 말부터 공개적으로 접근할 수 없어요.

지분 참여

shareholdings 기능은 반대 방향을 보여 줘요: 요청한 회사가 어느 회사에 지분을 갖고 있는지. 지분 보유는 그 회사들의 주주 명부에서 와요. 지분 보유가 있으면 5 크레딧가 들어요.

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();

필드
필드	의미	예시	제공 빈도
shareholdingsobject\|null	요청한 회사가 지분을 가진 회사.비어 있는 경우: 알려진 지분 보유가 없음`shareholdings` · 베타	–	대부분: AG, SE, KGaA 일부: GmbH, UG 드묾: GmbH & Co. KG, KG, OHG, e.K., eG, PartG
shareholdings.holdings.currentarray	현재 지분 보유, 회사마다 하나.	–	위와 같음
shareholdings.holdings.current[].organizationobject	지분을 보유한 대상 회사.	–	위와 같음
shareholdings.holdings.current[].organization.entity_idstring	회사 ID, 회사 프로필용.	`"63529c3a793e9f002196b4fd344e1241"`	위와 같음
shareholdings.holdings.current[].organization.namestring\|null	회사 이름.	`"Hetzner Cloud GmbH"`	위와 같음
shareholdings.holdings.current[].organization.legal_formstring\|null	회사의 법적 형태.	`"GmbH"`	위와 같음
shareholdings.holdings.current[].organization.statusstring\|null	등기부상 회사의 상태, 예: ACTIVE.	`"ACTIVE"`	위와 같음
shareholdings.holdings.current[].organization.addressobject\|array	회사 주소, 기본 데이터의 address와 같은 구조.비어 있는 경우: 알려진 주소가 없음; 이때 값은 빈 목록 []	–	위와 같음
shareholdings.holdings.current[].organization.registrationobject\|array	court, register_type, register_number가 담긴 회사 등기.비어 있는 경우: 알려진 등기가 없음; 이때 값은 빈 목록 []	–	위와 같음
shareholdings.holdings.current[].ownership.percentagenumber\|null	% 단위의 지분: 100은 100%예요.비어 있는 경우: 명부에서 지분이 나오지 않음	`100`	위와 같음
shareholdings.holdings.current[].ownership.contributionobject	amount와 currency가 담긴 지분의 액면가.	–	위와 같음
shareholdings.holdings.current[].as_ofstring	지분 보유의 출처인 주주 명부의 날짜.	`"2017-09-19"`	위와 같음
shareholdings.summary.total_currentinteger	현재 지분 보유 수.	`2`	위와 같음

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 · 예시 응답: shareholdings 기능을 쓴 Hetzner Online GmbH

인물의 지분 보유는 같은 기능으로 인물 프로필에 있어요.

그룹 구조

그룹 관계는 여러 데이터 포인트를 조합해 만들어요. shareholders와 shareholdings는 한 단계 위아래의 지분을, ubos는 사슬 끝의 인물을 보여 줘요.

기업 네트워크는 두 단계에 걸쳐 회사와 인물을 연결해요. 계열사도 포함돼요.

합병, 분할, 기타 조직 변경은 인수합병에 있어요.