인물과 대표권
누가 회사를 경영하고 대표하는지.
등기부에는 회사의 인물이 기재돼요: 대표이사, 이사회, Prokura 보유자, 소유자, 파트너, KG나 OHG의 사원. 회사 프로필은 related_persons 기능(경영진)으로 이들을 반환해요. 현재와 과거의 인물을 각각 역할, 기간, 대표권과 함께 받아요.
한 인물에 대해서는 인물 프로필이 더 많은 것을 반환해요: 다른 회사에서의 모든 역할, 지분, 웹 조사.
인물 가져오기
related_persons 기능을 요청하세요. 그러면 응답에 두 목록이 담긴 키 related_persons가 있어요: 오늘 역할을 맡고 있는 모든 사람의 current, 떠난 모든 사람의 past. 역할마다 별도의 항목이에요. Hetzner Online GmbH, Ansbach HRB 6089에 대한 예시 요청에서 current에는 대표이사 세 명이 있었어요. 그중 두 명은 이전 Prokura와 함께 past에도 다시 나왔어요. 예시 응답의 개인 정보는 모두 샘플 데이터예요.
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=related_persons'
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": ["related_persons"], }, ) 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", "related_persons"); const response = await fetch(url, { headers: { "x-api-key": "YOUR_API_KEY" }, }); const data = await response.json();
1{2 "name": "Hetzner Online GmbH",3 "related_persons": {4 "current": [5 {6 "entity_id": "ea3a1670232611a992727ed067216d07",7 "label": "MANAGING_DIRECTOR",8 "role": {9 "en": {10 "long": "Managing Director",11 "short": "MD"12 },13 "de": {14 "long": "Geschäftsführer",15 "short": "GF"16 }17 },18 "name": "Paul Musterwald",19 "start_date": "2019-01-04",20 "end_date": null,21 "birth_date": "1989-07-18",22 "name_parts": {23 "given": "Paul",24 "family": "Musterwald",25 "maiden": null,26 "canonical_name": "Musterwald, Paul",27 "previous_names": null28 },29 "location": {30 "home": {31 "city": "Exempelingen i. Bay."32 }33 },34 "organization_representation_scheme": {35 "current": [36 "Ist nur ein Geschäftsführer bestellt, so vertritt er die Gesellschaft allein. Sind mehrere Geschäftsführer bestellt, so wird die Gesellschaft durch zwei Geschäftsführer oder durch einen Geschäftsführer gemeinsam mit einem Prokuristen vertreten."37 ],38 "history": [39 {40 "value": [41 "Ist nur ein Vorstandsmitglied bestellt, so vertritt es die Gesellschaft allein. Sind mehrere Vorstandsmitglieder bestellt, so wird die Gesellschaft durch zwei Vorstandsmitglieder oder durch ein Vorstandsmitglied gemeinsam mit einem Prokuristen vertreten."42 ],43 "effective_from": "2002-10-15",44 "effective_to": "2015-07-28"45 },46 {47 "value": [48 "Ist nur ein Geschäftsführer bestellt, so vertritt er die Gesellschaft allein. Sind mehrere Geschäftsführer bestellt, so wird die Gesellschaft durch zwei Geschäftsführer oder durch einen Geschäftsführer gemeinsam mit einem Prokuristen vertreten."49 ],50 "effective_from": "2015-07-28",51 "effective_to": null52 }53 ]54 },55 "role_representation_scheme": {56 "current": [57 "einzelvertretungsberechtigt."58 ],59 "history": [60 {61 "value": [62 "einzelvertretungsberechtigt."63 ],64 "effective_from": "2019-01-04",65 "effective_to": null66 }67 ]68 }69 },70 {71 "entity_id": "dd7e94b41f78de4195cc70c6b0f732f3",72 "label": "MANAGING_DIRECTOR",73 "role": {74 "en": {75 "long": "Managing Director",76 "short": "MD"77 },78 "de": {79 "long": "Geschäftsführer",80 "short": "GF"81 }82 },83 "name": "Jan Musterhuber",84 "start_date": "2019-01-04",85 "end_date": null,86 "birth_date": "1955-11-06",87 "name_parts": {88 "given": "Jan",89 "family": "Musterhuber",90 "maiden": null,91 "canonical_name": "Musterhuber, Jan",92 "previous_names": null93 },94 "location": {95 "home": {96 "city": "Probeingen"97 }98 },99 "organization_representation_scheme": {100 "current": [101 "Ist nur ein Geschäftsführer bestellt, so vertritt er die Gesellschaft allein. Sind mehrere Geschäftsführer bestellt, so wird die Gesellschaft durch zwei Geschäftsführer oder durch einen Geschäftsführer gemeinsam mit einem Prokuristen vertreten."102 ],103 "history": [104 {105 "value": [106 "Ist nur ein Vorstandsmitglied bestellt, so vertritt es die Gesellschaft allein. Sind mehrere Vorstandsmitglieder bestellt, so wird die Gesellschaft durch zwei Vorstandsmitglieder oder durch ein Vorstandsmitglied gemeinsam mit einem Prokuristen vertreten."107 ],108 "effective_from": "2002-10-15",109 "effective_to": "2015-07-28"110 },111 {112 "value": [113 "Ist nur ein Geschäftsführer bestellt, so vertritt er die Gesellschaft allein. Sind mehrere Geschäftsführer bestellt, so wird die Gesellschaft durch zwei Geschäftsführer oder durch einen Geschäftsführer gemeinsam mit einem Prokuristen vertreten."114 ],115 "effective_from": "2015-07-28",116 "effective_to": null117 }118 ]119 },120 "role_representation_scheme": {121 "current": [122 "einzelvertretungsberechtigt."123 ],124 "history": [125 {126 "value": [127 "einzelvertretungsberechtigt."128 ],129 "effective_from": "2019-01-04",130 "effective_to": null131 }132 ]133 }134 },135 {136 "entity_id": "08ed5f967956831ca6588930fd2693ed",137 "label": "MANAGING_DIRECTOR",138 "role": {139 "en": {140 "long": "Managing Director",141 "short": "MD"142 },143 "de": {144 "long": "Geschäftsführer",145 "short": "GF"146 }147 },148 "name": "Max Felix Mustermann",149 "start_date": "2015-07-28",150 "end_date": null,151 "birth_date": "1976-01-15",152 "name_parts": {153 "given": "Max Felix",154 "family": "Mustermann",155 "maiden": null,156 "canonical_name": "Mustermann, Max Felix",157 "previous_names": null158 },159 "location": {160 "home": {161 "city": "Musterheim"162 }163 },164 "organization_representation_scheme": {165 "current": [166 "Ist nur ein Geschäftsführer bestellt, so vertritt er die Gesellschaft allein. Sind mehrere Geschäftsführer bestellt, so wird die Gesellschaft durch zwei Geschäftsführer oder durch einen Geschäftsführer gemeinsam mit einem Prokuristen vertreten."167 ],168 "history": [169 {170 "value": [171 "Ist nur ein Vorstandsmitglied bestellt, so vertritt es die Gesellschaft allein. Sind mehrere Vorstandsmitglieder bestellt, so wird die Gesellschaft durch zwei Vorstandsmitglieder oder durch ein Vorstandsmitglied gemeinsam mit einem Prokuristen vertreten."172 ],173 "effective_from": "2002-10-15",174 "effective_to": "2015-07-28"175 },176 {177 "value": [178 "Ist nur ein Geschäftsführer bestellt, so vertritt er die Gesellschaft allein. Sind mehrere Geschäftsführer bestellt, so wird die Gesellschaft durch zwei Geschäftsführer oder durch einen Geschäftsführer gemeinsam mit einem Prokuristen vertreten."179 ],180 "effective_from": "2015-07-28",181 "effective_to": null182 }183 ]184 },185 "role_representation_scheme": {186 "current": [187 "einzelvertretungsberechtigt; mit der Befugnis, im Namen der Gesellschaft mit sich im eigenen Namen oder als Vertreter eines Dritten Rechtsgeschäfte abzuschließen."188 ],189 "history": [190 {191 "value": [192 "einzelvertretungsberechtigt; mit der Befugnis, im Namen der Gesellschaft mit sich im eigenen Namen oder als Vertreter eines Dritten Rechtsgeschäfte abzuschließen."193 ],194 "effective_from": "2015-07-28",195 "effective_to": null196 }197 ]198 }199 }200 ],201 "past": [202 {203 "entity_id": "ea3a1670232611a992727ed067216d07",204 "label": "PROCURA",205 "role": {206 "en": {207 "long": "Procura",208 "short": "Procura"209 },210 "de": {211 "long": "Prokura",212 "short": "Prokura"213 }214 },215 "name": "Paul Musterwald",216 "start_date": "2015-07-28",217 "end_date": "2019-01-04",218 "birth_date": "1989-07-18",219 "name_parts": {220 "given": "Paul",221 "family": "Musterwald",222 "maiden": null,223 "canonical_name": "Musterwald, Paul",224 "previous_names": null225 },226 "location": {227 "home": {228 "city": "Exempelingen i. Bay."229 }230 },231 "organization_representation_scheme": {232 "latest": [233 "Ist nur ein Geschäftsführer bestellt, so vertritt er die Gesellschaft allein. Sind mehrere Geschäftsführer bestellt, so wird die Gesellschaft durch zwei Geschäftsführer oder durch einen Geschäftsführer gemeinsam mit einem Prokuristen vertreten."234 ],235 "history": [236 {237 "value": [238 "Ist nur ein Vorstandsmitglied bestellt, so vertritt es die Gesellschaft allein. Sind mehrere Vorstandsmitglieder bestellt, so wird die Gesellschaft durch zwei Vorstandsmitglieder oder durch ein Vorstandsmitglied gemeinsam mit einem Prokuristen vertreten."239 ],240 "effective_from": "2002-10-15",241 "effective_to": "2015-07-28"242 },243 {244 "value": [245 "Ist nur ein Geschäftsführer bestellt, so vertritt er die Gesellschaft allein. Sind mehrere Geschäftsführer bestellt, so wird die Gesellschaft durch zwei Geschäftsführer oder durch einen Geschäftsführer gemeinsam mit einem Prokuristen vertreten."246 ],247 "effective_from": "2015-07-28",248 "effective_to": null249 }250 ]251 },252 "role_representation_scheme": {253 "latest": [254 "Gesamtprokura gemeinsam mit einem anderen Prokuristen:"255 ],256 "history": [257 {258 "value": [259 "Gesamtprokura gemeinsam mit einem anderen Prokuristen:"260 ],261 "effective_from": "2015-07-28",262 "effective_to": "2019-01-04"263 }264 ]265 }266 },267 {268 "entity_id": "dd7e94b41f78de4195cc70c6b0f732f3",269 "label": "PROCURA",270 "role": {271 "en": {272 "long": "Procura",273 "short": "Procura"274 },275 "de": {276 "long": "Prokura",277 "short": "Prokura"278 }279 },280 "name": "Jan Musterhuber",281 "start_date": "2015-07-28",282 "end_date": "2019-01-04",283 "birth_date": "1955-11-06",284 "name_parts": {285 "given": "Jan",286 "family": "Musterhuber",287 "maiden": null,288 "canonical_name": "Musterhuber, Jan",289 "previous_names": null290 },291 "location": {292 "home": {293 "city": "Probeingen"294 }295 },296 "organization_representation_scheme": {297 "latest": [298 "Ist nur ein Geschäftsführer bestellt, so vertritt er die Gesellschaft allein. Sind mehrere Geschäftsführer bestellt, so wird die Gesellschaft durch zwei Geschäftsführer oder durch einen Geschäftsführer gemeinsam mit einem Prokuristen vertreten."299 ],300 "history": [301 {302 "value": [303 "Ist nur ein Vorstandsmitglied bestellt, so vertritt es die Gesellschaft allein. Sind mehrere Vorstandsmitglieder bestellt, so wird die Gesellschaft durch zwei Vorstandsmitglieder oder durch ein Vorstandsmitglied gemeinsam mit einem Prokuristen vertreten."304 ],305 "effective_from": "2002-10-15",306 "effective_to": "2015-07-28"307 },308 {309 "value": [310 "Ist nur ein Geschäftsführer bestellt, so vertritt er die Gesellschaft allein. Sind mehrere Geschäftsführer bestellt, so wird die Gesellschaft durch zwei Geschäftsführer oder durch einen Geschäftsführer gemeinsam mit einem Prokuristen vertreten."311 ],312 "effective_from": "2015-07-28",313 "effective_to": null314 }315 ]316 },317 "role_representation_scheme": {318 "latest": [319 "Gesamtprokura gemeinsam mit einem anderen Prokuristen:"320 ],321 "history": [322 {323 "value": [324 "Gesamtprokura gemeinsam mit einem anderen Prokuristen:"325 ],326 "effective_from": "2015-07-28",327 "effective_to": "2019-01-04"328 }329 ]330 }331 },332 {333 "entity_id": "08ed5f967956831ca6588930fd2693ed",334 "label": "BOARD",335 "role": {336 "en": {337 "long": "Board Member",338 "short": "Board"339 },340 "de": {341 "long": "Vorstandsmitglied",342 "short": "Vorstand"343 }344 },345 "name": "Max Felix Mustermann",346 "start_date": "2002-10-15",347 "end_date": "2015-07-28",348 "birth_date": "1976-01-15",349 "name_parts": {350 "given": "Max Felix",351 "family": "Mustermann",352 "maiden": null,353 "canonical_name": "Mustermann, Max Felix",354 "previous_names": null355 },356 "location": {357 "home": {358 "city": "Musterheim"359 }360 },361 "organization_representation_scheme": {362 "latest": [363 "Ist nur ein Geschäftsführer bestellt, so vertritt er die Gesellschaft allein. Sind mehrere Geschäftsführer bestellt, so wird die Gesellschaft durch zwei Geschäftsführer oder durch einen Geschäftsführer gemeinsam mit einem Prokuristen vertreten."364 ],365 "history": [366 {367 "value": [368 "Ist nur ein Vorstandsmitglied bestellt, so vertritt es die Gesellschaft allein. Sind mehrere Vorstandsmitglieder bestellt, so wird die Gesellschaft durch zwei Vorstandsmitglieder oder durch ein Vorstandsmitglied gemeinsam mit einem Prokuristen vertreten."369 ],370 "effective_from": "2002-10-15",371 "effective_to": "2015-07-28"372 },373 {374 "value": [375 "Ist nur ein Geschäftsführer bestellt, so vertritt er die Gesellschaft allein. Sind mehrere Geschäftsführer bestellt, so wird die Gesellschaft durch zwei Geschäftsführer oder durch einen Geschäftsführer gemeinsam mit einem Prokuristen vertreten."376 ],377 "effective_from": "2015-07-28",378 "effective_to": null379 }380 ]381 },382 "role_representation_scheme": {383 "latest": [384 "einzelvertretungsberechtigt; mit der Befugnis, im Namen der Gesellschaft mit sich im eigenen Namen oder als Vertreter eines Dritten Rechtsgeschäfte abzuschließen"385 ],386 "history": [387 {388 "value": [389 "einzelvertretungsberechtigt; mit der Befugnis, im Namen der Gesellschaft mit sich im eigenen Namen oder als Vertreter eines Dritten Rechtsgeschäfte abzuschließen"390 ],391 "effective_from": "2002-10-15",392 "effective_to": "2015-07-28"393 }394 ]395 }396 }397 ]398 }399}
| 필드 | 의미 | 예시 | 제공 빈도 |
|---|---|---|---|
| related_personsobject|null |
current와 past로 나뉜, 회사에 등기된 모든 인물.related_persons |
– | 항상 |
| related_persons.currentarray | 오늘 역할을 맡고 있는 인물. | – | 위와 같음 |
| related_persons.pastarray | 떠난 인물, current와 같은 필드. 두 대표 규정에서는 current 대신 latest가 있으며, 떠나기 전 마지막 버전이에요.비어 있는 경우: 등기 이후 떠난 사람이 없음 | – | 대부분 |
인물의 필드
current와 past의 모든 항목은 같은 필드를 가져요. 실시간 모드가 아니면 한 인물은 모든 회사 프로필과 인물 프로필에서 같은 entity_id를 가져요. 그래서 회사를 넘어 같은 인물을 알아볼 수 있어요. 실시간 조회에서 나온 인물은 고유한 ID를 가져요.
| 필드 | 의미 | 예시 | 제공 빈도 |
|---|---|---|---|
| related_persons.current[].entity_idstring|null |
인물 ID. 실시간 모드가 아니면 모든 회사 프로필에서 같고, 인물 프로필의 entity_id와 일치해요.related_persons |
"ea3a1670232611a992727ed067216d07" |
항상 |
| related_persons.current[].labelstring |
고정 값으로 된 역할. 다른 값도 있을 수 있어요.값: MANAGING_DIRECTOR 대표이사(Geschäftsführer), TEMPORARY_MANAGING_DIRECTOR 긴급 대표이사(Notgeschäftsführer), BOARD 이사회 구성원(Vorstand), BOARD_CHAIR 이사회 의장, DIRECTOR 집행 이사, 예: SE, PROCURA Prokura 보유자(Prokurist), LIQUIDATOR 청산인, INSOLVENCY_ADMINISTRATOR 파산 관재인, REPRESENTATIVE 상임 대리인, FULLY_LIABLE_PARTNER 무한책임사원(persönlich haftender Gesellschafter), LIMITED_PARTNER 유한책임사원(Kommanditist), PARTNER 파트너, OWNER 소유자(Inhaber), PROPRIETOR 소유자(Inhaber), TREASURER 사단의 회계 담당, SECRETARY 사단의 서기, YOUTH_WARDEN 사단의 청소년 담당, WATER_WARDEN 사단의 수상 안전 담당, OTHER 기타 역할 |
"MANAGING_DIRECTOR" |
위와 같음 |
| related_persons.current[].roleobject | 표시용 역할 이름, de와 en으로 각각 긴 형태(long)와 짧은 형태(short), 예: Geschäftsführer와 GF. | – | 위와 같음 |
| related_persons.current[].namestring | 등기부에 적힌 전체 이름. |
"Paul Musterwald" |
위와 같음 |
| related_persons.current[].name_partsobject | 정렬과 매칭을 위해 구성 요소로 나눈 이름. | – | 위와 같음 |
| related_persons.current[].name_parts.givenstring|null | 이름(given name), 여러 개면 전부. |
"Paul" |
위와 같음 |
| related_persons.current[].name_parts.familystring|null | 성. |
"Musterwald" |
위와 같음 |
| related_persons.current[].name_parts.canonical_namestring|null | 정렬과 매칭을 위한 이름, 대개 “성, 이름” 형태. |
"Musterwald, Paul" |
위와 같음 |
| related_persons.current[].name_parts.maidenstring|null | 출생 시 성.비어 있는 경우: 등기된 것이 없음 |
null |
드묾 |
| related_persons.current[].name_parts.previous_namesarray|null | 인물의 이전 이름 목록.비어 있는 경우: 등기된 것이 없음 |
null |
위와 같음 |
| related_persons.current[].titlesarray | 학위 칭호, 예: Dr. 등기된 칭호가 없으면 키가 없어요. | – | 위와 같음 |
| related_persons.current[].birth_datestring|null | 등기된 YYYY-MM-DD 형식의 생년월일.비어 있는 경우: 등기된 날짜가 없음 |
"1989-07-18" |
대부분 |
| related_persons.current[].locationobject|null | 인물의 장소. | – | 위와 같음 |
| related_persons.current[].location.home.citystring|null | 등기된 거주지. 등기부에는 전체 주소가 없어요.비어 있는 경우: 등기된 거주지가 없음 |
"Exempelingen i. Bay." |
위와 같음 |
| related_persons.current[].start_datestring|null | YYYY-MM-DD 형식의 역할 시작일.비어 있는 경우: 시작일을 알 수 없음, 예: 실시간 모드 |
"2019-01-04" |
위와 같음 |
| related_persons.current[].end_datestring|null | 역할 종료일. past의 인물에 설정돼요.비어 있는 경우: 역할이 아직 유지됨 |
null |
항상 |
대표이사와 이사회
GmbH나 UG의 대표이사(Geschäftsführer)는 레이블 MANAGING_DIRECTOR를 가져요. AG, SE, eG의 이사회(Vorstand)는 BOARD로, 그 의장은 BOARD_CHAIR로 알아봐요. 회사가 해산되면 LIQUIDATOR인 청산인이 대표를 맡아요.
역할은 항상
label로 확인하세요. role의 텍스트는 표시용이에요.
Prokura
Prokura는 거의 모든 업무에서 회사를 대표할 수 있는 등기된 대리권이에요. Prokura 보유자(Prokuristen)는 레이블 PROCURA를 가져요. 단독으로 행위할 수 있는지, 다른 사람과 공동으로만 할 수 있는지는 role_representation_scheme에 있어요. 예: “Gesamtprokura gemeinsam mit einem Vorstandsmitglied”(이사회 구성원과 공동 Prokura).
무한책임사원
KG, OHG, KGaA에서는 무한책임사원(persönlich haftende Gesellschafter)이 회사를 대표해요. 레이블은 FULLY_LIABLE_PARTNER예요. KG의 유한책임사원(Kommanditisten)은 LIMITED_PARTNER로, e.K.의 소유자는 OWNER로, PartG나 eGbR의 파트너는 PARTNER로 등기부에 있어요.
GmbH & Co. KG에서는 무한책임사원이 대개 GmbH 자체예요. 그 대표이사는 해당 GmbH의 회사 프로필에서 찾을 수 있어요.
법적 형태별 역할
회사가 어떤 역할을 갖는지는 법적 형태에서 정해져요. 표는 법적 형태별로 흔히 보이는 레이블을 보여 줘요. 모든 레이블과 의미는 위의 label에 있어요.
| 법적 형태 | 대표적인 레이블 |
|---|---|
| GmbH, UG | MANAGING_DIRECTOR, PROCURA, 청산 중에는 LIQUIDATOR |
| AG, SE | BOARD, BOARD_CHAIR, PROCURA |
| KGaA | FULLY_LIABLE_PARTNER, PROCURA |
| GmbH & Co. KG | LIMITED_PARTNER, PROCURA |
| KG, OHG | FULLY_LIABLE_PARTNER, KG는 LIMITED_PARTNER, PROCURA |
| e.K. | OWNER |
| eG | BOARD, BOARD_CHAIR, PROCURA |
| PartG, eGbR | PARTNER |
| e.V. | BOARD |
대표권
모든 인물에는 두 가지 규정이 함께 와요. role_representation_scheme은 그 인물 자신의 권한이에요. 예: “einzelvertretungsberechtigt”(단독 대표 가능). organization_representation_scheme은 회사의 일반 규정으로, 기본 데이터의 representation_scheme과 같아요. 둘 다 current와 history가 있으며, 과거 인물은 current 대신 latest를 가져요.
| 필드 | 의미 | 예시 | 제공 빈도 |
|---|---|---|---|
| related_persons.current[].role_representation_schemeobject |
인물 자신의 대표권, 예: “einzelvertretungsberechtigt”(단독 대표 가능) 또는 § 181 BGB 면제. current는 유효한 버전, history는 value, effective_from, effective_to가 담긴 변경 내역이에요.related_persons |
– |
대부분: GmbH, UG, AG, SE, KGaA, GmbH & Co. KG, KG, OHG, eG, PartG 드묾: e.K. |
| related_persons.current[].organization_representation_schemeobject | 모든 인물에 함께 담기는 회사의 일반 대표 규정. role_representation_scheme과 같은 구조예요. | – |
항상: GmbH, UG, GmbH & Co. KG, KG, OHG, eG, PartG 대부분: AG, SE, KGaA, e.K. |
실시간 모드의 인물
realtime_mode=handelsregister-default를 쓰면 related_persons 기능 없이도 현재 등기된 인물이 Handelsregister에서 바로 와요. 이때는 기능이 아니라 실시간 모드만 과금돼요. 응답에는 current만 있어요.
이 목록에서는 start_date와 end_date가 비어 있고, 이름이 더 짧을 수 있으며, 인물의 entity_id가 실시간 모드가 아닐 때와 다를 수 있어요. 인물은 이름과 생년월일로 매칭하세요.
실시간 모드와 related_persons를 함께 요청하면 current는 실시간 조회에서, past는 회사 프로필에서 와요. 이때는 기능도 과금돼요.
| 필드 | 의미 | 예시 | 제공 빈도 |
|---|---|---|---|
| related_persons.current[].name_parts.aliasesarray |
실시간 조회에서 나온 이름 표기, “성, 이름” 형태. 실시간 모드에서만.related_persons |
– | 항상 |
인물 프로필
인물 프로필(fetch-person)은 한 인물을 설명해요: 연결된 모든 회사에서의 역할, 그리고 공개 웹 출처가 그 인물에 대해 말하는 내용. 인물은 이름과, 그 인물이 역할을 맡고 있거나 맡았던 회사로 찾아요.
인물 프로필은 Plus 이상의 모든 크레딧 구독에 포함돼요. 웹을 조사하므로 요청에 10~30초가 걸리는 경우가 많아요. 클라이언트 타임아웃을 최소 120초로 설정하세요.
curl -G "https://handelsregister.ai/api/v1/fetch-person" \ -H "x-api-key: YOUR_API_KEY" \ --data-urlencode 'person_q=Max Mustermann' \ --data-urlencode 'organization_q=Hetzner Online GmbH'
import requests response = requests.get( "https://handelsregister.ai/api/v1/fetch-person", headers={"x-api-key": "YOUR_API_KEY"}, params={ "person_q": "Max Mustermann", "organization_q": "Hetzner Online GmbH", }, ) data = response.json()
const url = new URL("https://handelsregister.ai/api/v1/fetch-person"); url.searchParams.append("person_q", "Max Mustermann"); url.searchParams.append("organization_q", "Hetzner Online GmbH"); const response = await fetch(url, { headers: { "x-api-key": "YOUR_API_KEY" }, }); const data = await response.json();
1{2 "entity_id": "08ed5f967956831ca6588930fd2693ed",3 "name": "Max Felix Mustermann",4 "birth_date": "1976-01-15",5 "name_parts": {6 "given": "Max Felix",7 "family": "Mustermann",8 "maiden": null,9 "canonical_name": "Mustermann, Max Felix",10 "previous_names": null11 },12 "location": {13 "home": {14 "city": "Musterheim"15 }16 },17 "bio": "Max Felix Mustermann ist Geschäftsführer der Hetzner Online GmbH und Unternehmer im Bereich Rechenzentren.",18 "expertise": [19 "Rechenzentren",20 "Hosting"21 ],22 "contact": {23 "emails": [24 {25 "address": "[email protected]",26 "type": "organization",27 "label": "Allgemeine Unternehmenskontakt-E-Mail"28 },29 {30 "address": "[email protected]",31 "type": "organization",32 "label": "E-Mail für Produktfeedback"33 }34 ],35 "phones": [36 {37 "number": "+49374574447100",38 "type": "organization",39 "entity": "Hetzner Online GmbH",40 "label": "Öffentliche Unternehmens-Telefonnummer"41 },42 {43 "number": "+49911234226100",44 "type": "organization",45 "entity": "Hetzner Online GmbH",46 "label": "Öffentliche Unternehmens-Telefonnummer"47 },48 {49 "number": "+4998315050",50 "type": "organization",51 "entity": "Hetzner Online GmbH",52 "label": "Zentrale Unternehmensnummer"53 }54 ]55 },56 "profiles": {57 "linkedin": null,58 "other": []59 },60 "affiliations": [61 {62 "organization": "ENSoXX Holding AG",63 "relation": "Vorstandsmitglied"64 },65 {66 "organization": "Hetzner Online GmbH",67 "relation": "Geschäftsführer"68 },69 {70 "organization": "ENSoXX hilft e.V.",71 "relation": "Vorstandsmitglied"72 },73 {74 "organization": "TRAIDY UG (haftungsbeschränkt)",75 "relation": "Geschäftsführer"76 },77 {78 "organization": "HT clean energy GmbH",79 "relation": "Geschäftsführer"80 },81 {82 "organization": "DreamSoXX GmbH",83 "relation": "Geschäftsführer"84 },85 {86 "organization": "Lighthouse GmbH",87 "relation": "Prokura"88 },89 {90 "organization": "ENSoXX GmbH",91 "relation": "Geschäftsführer"92 },93 {94 "organization": "ENSoXX Invest GmbH",95 "relation": "Geschäftsführer"96 },97 {98 "organization": "Sonnenkraft Merkendorf GmbH & Co. KG",99 "relation": "Kommanditist"100 },101 {102 "organization": "Modellsportclub Gunzenhausen e.V.",103 "relation": "Vorstandsmitglied"104 },105 {106 "organization": "possum Projekt 1 GmbH",107 "relation": "Prokura"108 }109 ],110 "handelsregister_roles": [111 {112 "entity_id": "94eb910fef13f94585c48c263fa446d4",113 "name": "Hetzner Online GmbH",114 "label": "BOARD",115 "role": {116 "en": "Board Member",117 "de": "Vorstandsmitglied"118 },119 "start_date": "2002-10-15",120 "end_date": "2015-07-28"121 },122 {123 "entity_id": "0b3435f83ce8591300625100815d4583",124 "name": "Hetzner Online GmbH",125 "label": "BOARD",126 "role": {127 "en": "Board Member",128 "de": "Vorstandsmitglied"129 },130 "start_date": "2002-10-15",131 "end_date": "2015-07-28"132 },133 {134 "entity_id": "0b3435f83ce8591300625100815d4583",135 "name": "Hetzner Online GmbH",136 "label": "MANAGING_DIRECTOR",137 "role": {138 "en": "Managing Director",139 "de": "Geschäftsführer"140 },141 "start_date": "2015-07-28",142 "end_date": null143 },144 {145 "entity_id": "94eb910fef13f94585c48c263fa446d4",146 "name": "Hetzner Online GmbH",147 "label": "MANAGING_DIRECTOR",148 "role": {149 "en": "Managing Director",150 "de": "Geschäftsführer"151 },152 "start_date": "2015-07-28",153 "end_date": null154 },155 {156 "entity_id": "dd1cfcd3a25b5a63d549d768e2fcaaaf",157 "name": "ENSoXX GmbH",158 "label": "MANAGING_DIRECTOR",159 "role": {160 "en": "Managing Director",161 "de": "Geschäftsführer"162 },163 "start_date": "2015-08-14",164 "end_date": null165 },166 {167 "entity_id": "58d67a0bb99b2bc5644cb8daba58e6a6",168 "name": "ENSoXX Holding AG",169 "label": "BOARD",170 "role": {171 "en": "Board Member",172 "de": "Vorstandsmitglied"173 },174 "start_date": "2016-02-03",175 "end_date": null176 },177 {178 "entity_id": "bc1c1e106ade810eb960c779d4c752a8",179 "name": "ENSoXX hilft e.V.",180 "label": "BOARD",181 "role": {182 "en": "Board Member",183 "de": "Vorstandsmitglied"184 },185 "start_date": "2017-02-24",186 "end_date": null187 },188 {189 "entity_id": "b34f5fcc114e7d4c5fe9d5f6f8fb0d10",190 "name": "TRAIDY UG (haftungsbeschränkt)",191 "label": "MANAGING_DIRECTOR",192 "role": {193 "en": "Managing Director",194 "de": "Geschäftsführer"195 },196 "start_date": "2022-03-14",197 "end_date": null198 },199 {200 "entity_id": "4cd425f9ad57d6119f704ba53131b480",201 "name": "Modellsportclub Gunzenhausen e.V.",202 "label": "BOARD",203 "role": {204 "en": "Board Member",205 "de": "Vorstandsmitglied"206 },207 "start_date": "2023-06-06",208 "end_date": "2026-08-12"209 },210 {211 "entity_id": "0e8b1b4fc27a3ecc07d397750505e7b5",212 "name": "ENSoXX Invest GmbH",213 "label": "MANAGING_DIRECTOR",214 "role": {215 "en": "Managing Director",216 "de": "Geschäftsführer"217 },218 "start_date": "2023-12-13",219 "end_date": null220 },221 {222 "entity_id": "2ab71b59057969183dd811adf9f32ebd",223 "name": "HT clean energy GmbH",224 "label": "MANAGING_DIRECTOR",225 "role": {226 "en": "Managing Director",227 "de": "Geschäftsführer"228 },229 "start_date": "2024-08-20",230 "end_date": null231 },232 {233 "entity_id": "260286ab8baa3a8977fddd56b9361c6c",234 "name": "DreamSoXX GmbH",235 "label": "MANAGING_DIRECTOR",236 "role": {237 "en": "Managing Director",238 "de": "Geschäftsführer"239 },240 "start_date": "2025-01-13",241 "end_date": null242 },243 {244 "entity_id": "7582db1f94e1538ba8f531f6a95a7f1b",245 "name": "Lighthouse GmbH",246 "label": "PROCURA",247 "role": {248 "en": "Procura",249 "de": "Prokura"250 },251 "start_date": "2025-03-25",252 "end_date": null253 },254 {255 "entity_id": "232d2ed634eef59eb21836cc47cb5645",256 "name": "Sonnenkraft Merkendorf GmbH & Co. KG",257 "label": "LIMITED_PARTNER",258 "role": {259 "en": "Limited Partner",260 "de": "Kommanditist"261 },262 "start_date": "2026-02-18",263 "end_date": null264 },265 {266 "entity_id": "64922d416b4dd7006f3c2c62efaabd5d",267 "name": "possum Projekt 1 GmbH",268 "label": "PROCURA",269 "role": {270 "en": "Procura",271 "de": "Prokura"272 },273 "start_date": "2026-09-04",274 "end_date": null275 },276 {277 "entity_id": "997f1b8314b8b56573208ae2334abb1d",278 "name": "possum Projekt 1 GmbH",279 "label": "PROCURA",280 "role": {281 "en": "Procura",282 "de": "Prokura"283 },284 "start_date": "2026-09-04",285 "end_date": null286 }287 ],288 "meta": {289 "request_credit_cost": 15,290 "credits_remaining": 145291 }292}
인물
이름, 생년월일, 거주지는 등기부에서 와요. entity_id는 실시간 모드가 아닌 회사 프로필의 related_persons와 같아요.
| 필드 | 의미 | 예시 | 제공 빈도 |
|---|---|---|---|
| entity_idstring | 인물 ID. 실시간 모드가 아닌 회사 프로필의 related_persons에도 같은 ID가 나와요.인물 프로필 |
"08ed5f967956831ca6588930fd2693ed" |
항상 |
| namestring | 등기부에 적힌 전체 이름. |
"Max Felix Mustermann" |
위와 같음 |
| birth_datestring|null | 등기된 YYYY-MM-DD 형식의 생년월일.비어 있는 경우: 등기된 날짜가 없음 |
"1976-01-15" |
대부분 |
| name_partsobject | 구성 요소로 나눈 이름, related_persons와 같은 구조. | – | 항상 |
| name_parts.givenstring|null | 이름(given name), 여러 개면 전부. |
"Max Felix" |
위와 같음 |
| name_parts.familystring|null | 성. |
"Mustermann" |
위와 같음 |
| name_parts.canonical_namestring|null | 정렬과 매칭을 위한 이름, 대개 “성, 이름” 형태. |
"Mustermann, Max Felix" |
위와 같음 |
| name_parts.maidenstring|null | 출생 시 성.비어 있는 경우: 등기된 것이 없음 |
null |
드묾 |
| name_parts.previous_namesarray|null | 인물의 이전 이름 목록.비어 있는 경우: 등기된 것이 없음 |
null |
위와 같음 |
| locationobject | 인물의 장소. | – | 대부분 |
| location.home.citystring|null | 등기된 거주지.비어 있는 경우: 등기된 거주지가 없음 |
"Musterheim" |
위와 같음 |
역할과 연결
handelsregister_roles는 인물의 등기된 모든 역할을 회사, 기간과 함께 나열해요. 회사의 entity_id로 그 회사 프로필을 가져오세요. affiliations는 등기부와 웹에서 가져온 연결을 간단히 요약해요.
| 필드 | 의미 | 예시 | 제공 빈도 |
|---|---|---|---|
| handelsregister_rolesarray | 회사와 기간이 담긴 인물의 등기된 역할, 현재와 과거.인물 프로필 | – | 항상 |
| handelsregister_roles[].entity_idstring | 회사의 entity_id, 회사 프로필을 가져올 때 파라미터 q에. |
"0b3435f83ce8591300625100815d4583" |
위와 같음 |
| handelsregister_roles[].namestring | 회사 이름. |
"Hetzner Online GmbH" |
위와 같음 |
| handelsregister_roles[].labelstring | 고정 값으로 된 역할, related_persons의 label과 같은 값, 예: MANAGING_DIRECTOR, BOARD, PROCURA, LIMITED_PARTNER. |
"BOARD" |
위와 같음 |
| handelsregister_roles[].roleobject | 표시용 역할 이름, de와 en 텍스트. | – | 위와 같음 |
| handelsregister_roles[].start_datestring|null | YYYY-MM-DD 형식의 역할 시작일.비어 있는 경우: 시작일을 알 수 없음 |
"2002-10-15" |
대부분 |
| handelsregister_roles[].end_datestring|null | 역할 종료일.비어 있는 경우: 역할이 아직 유지됨 |
"2015-07-28" |
항상 |
| affiliationsarray | 인물과 연결된 회사, 각각 연결의 종류 포함. 등기부와 웹 출처에서 요약했어요. | – | 위와 같음 |
| affiliations[].organizationstring | 회사 이름. |
"ENSoXX Holding AG" |
위와 같음 |
| affiliations[].relationstring | 독일어 텍스트로 된 연결의 종류, 예: Geschäftsführer(대표이사), Prokura, Kommanditist(유한책임사원). |
"Vorstandsmitglied" |
위와 같음 |
웹 조사
짧은 소개, 전문 분야, 연락 채널, 출처를 공개 웹 출처에서 모아요. 얼마나 있는지는 그 인물이 웹에서 얼마나 눈에 띄는지에 달려 있어요.
| 필드 | 의미 | 예시 | 제공 빈도 |
|---|---|---|---|
| biostring|null | 한두 문장으로 된 인물의 짧은 소개, 독일어.비어 있는 경우: 웹에 인물에 관한 정보가 너무 적음(이때 null)인물 프로필 |
"Max Felix Mustermann ist Geschäftsführer der Hetzner Onl…" |
대부분 |
| expertisearray | 인물의 전문 분야와 주제 목록.비어 있는 경우: 웹에 인물에 관한 정보가 너무 적음 | – | 위와 같음 |
| contactobject | 공개된 연락 채널, emails와 phones 포함. | – | 항상 |
| contact.emailsarray | 이메일 주소 목록.비어 있는 경우: 주소를 찾지 못함 | – | 드묾 |
| contact.emails[].addressstring | 이메일 주소. |
"[email protected]" |
위와 같음 |
| contact.emails[].typestring | 주소의 종류. organization은 개인 주소가 아니라 회사 주소라는 뜻이에요. |
"organization" |
위와 같음 |
| contact.emails[].labelstring | 주소의 용도, 짧은 텍스트. |
"Allgemeine Unternehmenskontakt-E-Mail" |
위와 같음 |
| contact.phonesarray | 전화번호 목록.비어 있는 경우: 번호를 찾지 못함 | – | 위와 같음 |
| contact.phones[].numberstring | 번호, 대개 국제 형식. |
"+49374574447100" |
위와 같음 |
| contact.phones[].typestring | 번호의 종류. organization은 회사 번호라는 뜻이에요. |
"organization" |
위와 같음 |
| contact.phones[].entitystring | 번호가 속한 회사. |
"Hetzner Online GmbH" |
위와 같음 |
| contact.phones[].labelstring | 번호의 용도, 예: 대표 번호나 팩스. |
"Öffentliche Unternehmens-Telefonnummer" |
위와 같음 |
| profilesobject | 인물에 관한 웹 페이지, linkedin과 other 포함. | – | 항상 |
| profiles.linkedinstring|null | LinkedIn 프로필 주소.비어 있는 경우: 찾지 못함 |
null |
드묾 |
| profiles.otherarray | 인물에 관한 기타 페이지, 예: 언론 기사나 팀 페이지, 주소 목록.비어 있는 경우: 찾지 못함 | – | 대부분 |
이 정보는 AI가 공개 출처에서 정리해요. 이를 위해 최신 기술을 쓰고 품질에 많은 투자를 하지만, 개별 오류가 있을 수 있어요.
지분과 네트워크
두 기능이 인물 프로필을 확장해요: shareholdings는 인물이 지분을 가진 회사를 보여 줘요. network는 두 단계에 걸쳐 연결된 회사와 인물을 보여 줘요. 둘 다 데이터를 반환할 때만 과금돼요.
| 필드 | 의미 | 예시 | 제공 빈도 |
|---|---|---|---|
| shareholdingsobject|null |
인물이 현재 지분을 가진 회사.비어 있는 경우: 알려진 지분이 없음shareholdings |
– | 일부 |
| shareholdings.holdings.currentarray | 현재 지분 목록. | – | 위와 같음 |
| shareholdings.holdings.current[].organizationobject | entity_id, name, status, legal_form, address, registration이 담긴 회사, 기본 데이터와 같은 구조. | – | 위와 같음 |
| shareholdings.holdings.current[].ownership.percentagenumber|null | 자본금 대비 지분율(%), 예: 33.33. |
100 |
위와 같음 |
| shareholdings.holdings.current[].ownership.contributionobject|null | amount와 currency가 담긴 지분의 액면가. | – | 위와 같음 |
| shareholdings.holdings.current[].as_ofstring|null | YYYY-MM-DD 형식의 정보 기준일. |
"2025-01-13" |
위와 같음 |
| shareholdings.summary.total_currentinteger | 현재 지분 수. |
3 |
위와 같음 |
| networkobject|null |
두 단계에 걸쳐 인물과 연결된 회사와 인물. 회사 프로필의 network와 같은 구조.network · Pro부터 · 베타 |
– | 대부분 |
| network.depthinteger | 인물부터 센 네트워크의 단계 수. 인물 자신은 0단계예요. |
2 |
위와 같음 |
| network.nodesarray | 노드: entity_id, 이름, 단계가 담긴 인물(PERSON)과 회사(ORGANIZATION). 인물 자신은 is_root가 true예요. | – | 위와 같음 |
| network.connectionsarray | 두 노드 사이의 연결, 각각 종류(ROLE, OWNERSHIP 또는 GROUP), 레이블, 기간, is_current 포함. | – | 위와 같음 |