Persone e rappresentanza – Documentazione

Recuperare le persone

Richiedi la feature related_persons. La risposta contiene allora la chiave related_persons con due liste: current per tutti coloro che ricoprono il loro ruolo oggi e past per tutti coloro che sono usciti. Ogni ruolo è una voce a sé. Nella nostra richiesta di esempio per Hetzner Online GmbH, Ansbach HRB 6089, current conteneva tre amministratori. Due di loro comparivano di nuovo in past con la loro precedente Prokura. Tutti i dati personali nelle risposte di esempio sono dati di esempio.

curl -G "https://handelsregister.ai/api/v1/fetch-organization" \
  -H "x-api-key: LA_TUA_CHIAVE_API" \
  --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": "LA_TUA_CHIAVE_API"},
    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": "LA_TUA_CHIAVE_API" },
});
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}

200 · Risposta di esempio: Hetzner Online GmbH con la feature related_persons, abbreviata a nome e persone

Campo
Campo	Significato	Esempio	Disponibilità
related_personsobject\|null	Tutte le persone iscritte dell’azienda, suddivise in current e past.`related_persons`	–	sempre
related_persons.currentarray	Persone che ricoprono il loro ruolo oggi.	–	come sopra
related_persons.pastarray	Persone uscite, con gli stessi campi di current. Nelle due regole di rappresentanza latest sostituisce current: l’ultima versione prima dell’uscita.Vuoto se nessuno è uscito dall’iscrizione	–	quasi sempre

Campi di una persona

Ogni voce in current e past ha gli stessi campi. Senza Tempo reale una persona ha lo stesso entity_id in tutti i profili aziendali e nel profilo persona. Così la riconosci tra aziende diverse. Le persone da una query in Tempo reale hanno ID propri.

Campo
Campo	Significato	Esempio	Disponibilità
related_persons.current[].entity_idstring\|null	ID della persona. Senza Tempo reale è lo stesso in tutti i profili aziendali e corrisponde all’entity_id nel profilo persona.`related_persons`	`"ea3a1670232611a992727ed067216d07"`	sempre
related_persons.current[].labelstring	Ruolo come valore fisso. Sono possibili altri valori.Valori: `MANAGING_DIRECTOR` amministratore (Geschäftsführer), `TEMPORARY_MANAGING_DIRECTOR` amministratore d’emergenza (Notgeschäftsführer), `BOARD` membro del consiglio di gestione (Vorstand), `BOARD_CHAIR` presidente del consiglio di gestione, `DIRECTOR` amministratore esecutivo, ad esempio di una SE, `PROCURA` titolare di Prokura (Prokurist), `LIQUIDATOR` liquidatore, `INSOLVENCY_ADMINISTRATOR` curatore fallimentare, `REPRESENTATIVE` rappresentante permanente, `FULLY_LIABLE_PARTNER` socio a responsabilità illimitata (persönlich haftender Gesellschafter), `LIMITED_PARTNER` accomandante (Kommanditist), `PARTNER` socio, `OWNER` titolare (Inhaber), `PROPRIETOR` titolare (Inhaber), `TREASURER` tesoriere di un’associazione, `SECRETARY` segretario di un’associazione, `YOUTH_WARDEN` responsabile giovanile di un’associazione, `WATER_WARDEN` responsabile delle acque di un’associazione, `OTHER` altro ruolo	`"MANAGING_DIRECTOR"`	come sopra
related_persons.current[].roleobject	Nome del ruolo per la visualizzazione, in de ed en, ciascuno lungo (long) e breve (short), ad esempio Geschäftsführer e GF.	–	come sopra
related_persons.current[].namestring	Nome completo come compare nel registro.	`"Paul Musterwald"`	come sopra
related_persons.current[].name_partsobject	Il nome suddiviso nelle sue parti, per ordinare e abbinare.	–	come sopra
related_persons.current[].name_parts.givenstring\|null	Nome di battesimo, tutti se sono più di uno.	`"Paul"`	come sopra
related_persons.current[].name_parts.familystring\|null	Cognome.	`"Musterwald"`	come sopra
related_persons.current[].name_parts.canonical_namestring\|null	Il nome, di solito nella forma “Cognome, Nome”, per ordinare e abbinare.	`"Musterwald, Paul"`	come sopra
related_persons.current[].name_parts.maidenstring\|null	Cognome di nascita.Vuoto se non ne è iscritto alcuno	`null`	raramente
related_persons.current[].name_parts.previous_namesarray\|null	Nomi precedenti della persona come lista.Vuoto se non ne sono iscritti	`null`	come sopra
related_persons.current[].titlesarray	Titoli accademici, ad esempio Dr. La chiave manca se non è iscritto alcun titolo.	–	come sopra
related_persons.current[].birth_datestring\|null	Data di nascita nel formato YYYY-MM-DD, come iscritta.Vuoto se non è iscritta alcuna data	`"1989-07-18"`	quasi sempre
related_persons.current[].locationobject\|null	Luoghi della persona.	–	come sopra
related_persons.current[].location.home.citystring\|null	Luogo di residenza, come iscritto. Il registro non contiene un indirizzo completo.Vuoto se non è iscritto alcun luogo di residenza	`"Exempelingen i. Bay."`	come sopra
related_persons.current[].start_datestring\|null	Inizio del ruolo nel formato YYYY-MM-DD.Vuoto se l’inizio non è noto, ad esempio con Tempo reale	`"2019-01-04"`	come sopra
related_persons.current[].end_datestring\|null	Fine del ruolo. È impostata per le persone in past.Vuoto se il ruolo esiste ancora	`null`	sempre

Amministratori e consiglio di gestione

Gli amministratori (Geschäftsführer) di una GmbH o UG hanno il label MANAGING_DIRECTOR. Il consiglio di gestione (Vorstand) di una AG, SE o eG lo riconosci da BOARD, il suo presidente da BOARD_CHAIR. Quando un’azienda viene sciolta, la rappresentanza passa ai liquidatori con LIQUIDATOR.

Controlla sempre i ruoli tramite label. I testi in role sono pensati per la visualizzazione.

Prokura

La Prokura è la procura commerciale iscritta che autorizza a rappresentare l’azienda in quasi tutti gli affari. I titolari di Prokura (Prokuristen) hanno il label PROCURA. Se qualcuno può agire da solo o solo insieme ad altri è in role_representation_scheme, ad esempio “Gesamtprokura gemeinsam mit einem Vorstandsmitglied” (Prokura congiunta insieme a un membro del consiglio di gestione).

Soci accomandatari

In una KG, OHG e KGaA i soci a responsabilità illimitata (persönlich haftende Gesellschafter) rappresentano l’azienda. Hanno il label FULLY_LIABLE_PARTNER. Gli accomandanti (Kommanditisten) di una KG sono nel registro con LIMITED_PARTNER, il titolare di una e.K. con OWNER, i soci di una PartG o eGbR con PARTNER.

In una GmbH & Co. KG il socio accomandatario è di solito a sua volta una GmbH. I suoi amministratori li trovi nel profilo aziendale di quella GmbH.

Ruoli per forma giuridica

Quali ruoli ha un’azienda deriva dalla sua forma giuridica. La tabella mostra quali label vedi tipicamente per forma giuridica. Tutti i label con il loro significato sono elencati sopra in label.

Forma giuridica
Forma giuridica	Label tipici
GmbH, UG	MANAGING_DIRECTOR, PROCURA, in liquidazione LIQUIDATOR
AG, SE	BOARD, BOARD_CHAIR, PROCURA
KGaA	FULLY_LIABLE_PARTNER, PROCURA
GmbH & Co. KG	LIMITED_PARTNER, PROCURA
KG, OHG	FULLY_LIABLE_PARTNER, per una KG LIMITED_PARTNER, PROCURA
e.K.	OWNER
eG	BOARD, BOARD_CHAIR, PROCURA
PartG, eGbR	PARTNER
e.V.	BOARD

Potere di rappresentanza

Ogni persona arriva con due insiemi di regole. role_representation_scheme è il suo potere personale, ad esempio “einzelvertretungsberechtigt” (può rappresentare da solo). organization_representation_scheme è la regola generale dell’azienda, uguale a representation_scheme nei dati anagrafici. Entrambi hanno current e history; per le persone passate latest sostituisce current.

Campo
Campo	Significato	Esempio	Disponibilità
related_persons.current[].role_representation_schemeobject	Il potere di rappresentanza personale, ad esempio “einzelvertretungsberechtigt” (può rappresentare da solo) o un’esenzione dal § 181 BGB. current è la versione in vigore, history le modifiche con value, effective_from ed effective_to.`related_persons`	–	quasi sempre: GmbH, UG, AG, SE, KGaA, GmbH & Co. KG, KG, OHG, eG, PartG raramente: e.K.
related_persons.current[].organization_representation_schemeobject	Le regole generali di rappresentanza dell’azienda, incluse con ogni persona. Strutturate come role_representation_scheme.	–	sempre: GmbH, UG, GmbH & Co. KG, KG, OHG, eG, PartG quasi sempre: AG, SE, KGaA, e.K.

Persone con Tempo reale

Con realtime_mode=handelsregister-default le persone attualmente iscritte arrivano direttamente dall’Handelsregister, anche senza la feature related_persons. In quel caso viene addebitato solo Tempo reale, non la feature. La risposta contiene solo current.

In questa lista start_date ed end_date sono vuoti, i nomi possono essere più corti e l’entity_id di una persona può differire da quello senza Tempo reale. Abbina le persone per nome e data di nascita.

Se richiedi Tempo reale e related_persons insieme, current viene dalla query in diretta e past dal profilo aziendale. Allora viene addebitata anche la feature.

Campo
Campo	Significato	Esempio	Disponibilità
related_persons.current[].name_parts.aliasesarray	Grafie del nome dalla query in diretta, nella forma “Cognome, Nome”. Solo con Tempo reale.`related_persons`	–	sempre

Profilo persona

Il profilo persona (fetch-person) descrive una singola persona: i suoi ruoli in tutte le aziende a cui è collegata e ciò che dicono di lei le fonti web pubbliche. Trovi la persona tramite il suo nome e un’azienda in cui ricopre o ha ricoperto un ruolo.

Il profilo persona è incluso in ogni abbonamento a crediti da Plus. Una richiesta dura spesso da dieci a trenta secondi, perché facciamo ricerche sul web. Imposta il timeout del tuo client ad almeno 120 secondi.

curl -G "https://handelsregister.ai/api/v1/fetch-person" \
  -H "x-api-key: LA_TUA_CHIAVE_API" \
  --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": "LA_TUA_CHIAVE_API"},
    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": "LA_TUA_CHIAVE_API" },
});
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}

200 · Risposta di esempio: profilo persona di Max Felix Mustermann (dati di esempio) presso Hetzner Online GmbH, abbreviato

La persona

Nome, data di nascita e luogo di residenza vengono dal registro. L’entity_id è lo stesso di related_persons nei profili aziendali senza Tempo reale.

Campo
Campo	Significato	Esempio	Disponibilità
entity_idstring	ID della persona. Lo stesso ID compare in related_persons dei profili aziendali senza Tempo reale.Profilo persona	`"08ed5f967956831ca6588930fd2693ed"`	sempre
namestring	Nome completo come compare nel registro.	`"Max Felix Mustermann"`	come sopra
birth_datestring\|null	Data di nascita nel formato YYYY-MM-DD, come iscritta.Vuoto se non è iscritta alcuna data	`"1976-01-15"`	quasi sempre
name_partsobject	Il nome suddiviso nelle sue parti, strutturato come in related_persons.	–	sempre
name_parts.givenstring\|null	Nome di battesimo, tutti se sono più di uno.	`"Max Felix"`	come sopra
name_parts.familystring\|null	Cognome.	`"Mustermann"`	come sopra
name_parts.canonical_namestring\|null	Il nome, di solito nella forma “Cognome, Nome”, per ordinare e abbinare.	`"Mustermann, Max Felix"`	come sopra
name_parts.maidenstring\|null	Cognome di nascita.Vuoto se non ne è iscritto alcuno	`null`	raramente
name_parts.previous_namesarray\|null	Nomi precedenti della persona come lista.Vuoto se non ne sono iscritti	`null`	come sopra
locationobject	Luoghi della persona.	–	quasi sempre
location.home.citystring\|null	Luogo di residenza, come iscritto.Vuoto se non è iscritto alcun luogo di residenza	`"Musterheim"`	come sopra

Ruoli e collegamenti

handelsregister_roles elenca ogni ruolo iscritto della persona con l’azienda e il periodo. Usa l’entity_id di un’azienda per recuperarne il profilo aziendale. affiliations riassume brevemente i collegamenti, da registro e web.

Campo
Campo	Significato	Esempio	Disponibilità
handelsregister_rolesarray	I ruoli iscritti della persona con azienda e periodo, attuali e passati.Profilo persona	–	sempre
handelsregister_roles[].entity_idstring	entity_id dell’azienda, per un profilo aziendale nel parametro q.	`"0b3435f83ce8591300625100815d4583"`	come sopra
handelsregister_roles[].namestring	Nome dell’azienda.	`"Hetzner Online GmbH"`	come sopra
handelsregister_roles[].labelstring	Ruolo come valore fisso, gli stessi valori di label in related_persons, ad esempio MANAGING_DIRECTOR, BOARD, PROCURA o LIMITED_PARTNER.	`"BOARD"`	come sopra
handelsregister_roles[].roleobject	Nome del ruolo per la visualizzazione, come testo in de ed en.	–	come sopra
handelsregister_roles[].start_datestring\|null	Inizio del ruolo nel formato YYYY-MM-DD.Vuoto se l’inizio non è noto	`"2002-10-15"`	quasi sempre
handelsregister_roles[].end_datestring\|null	Fine del ruolo.Vuoto se il ruolo esiste ancora	`"2015-07-28"`	sempre
affiliationsarray	Le aziende a cui la persona è collegata, ciascuna con il tipo di collegamento. Riassunte da registro e fonti web.	–	come sopra
affiliations[].organizationstring	Nome dell’azienda.	`"ENSoXX Holding AG"`	come sopra
affiliations[].relationstring	Tipo di collegamento come testo tedesco, ad esempio Geschäftsführer (amministratore), Prokura o Kommanditist (accomandante).	`"Vorstandsmitglied"`	come sopra

Ricerca sul web

Raccogliamo la breve biografia, le aree di competenza, i canali di contatto e le fonti da fonti web pubbliche. Quanto ne esiste dipende da quanto la persona è visibile sul web.

Campo
Campo	Significato	Esempio	Disponibilità
biostring\|null	Breve biografia della persona in una o due frasi, in tedesco.Vuoto se sul web c’è troppo poco sulla persona (allora null)Profilo persona	`"Max Felix Mustermann ist Geschäftsführer der Hetzner Onl…"`	quasi sempre
expertisearray	Aree di competenza e temi della persona come lista.Vuoto se sul web c’è troppo poco sulla persona	–	come sopra
contactobject	Canali di contatto indicati pubblicamente, con emails e phones.	–	sempre
contact.emailsarray	Indirizzi email come lista.Vuoto se non è stato trovato alcun indirizzo	–	raramente
contact.emails[].addressstring	L’indirizzo email.	`"[email protected]"`	come sopra
contact.emails[].typestring	Tipo di indirizzo. organization significa: un indirizzo dell’azienda, non privato.	`"organization"`	come sopra
contact.emails[].labelstring	A cosa serve l’indirizzo, come breve testo.	`"Allgemeine Unternehmenskontakt-E-Mail"`	come sopra
contact.phonesarray	Numeri di telefono come lista.Vuoto se non è stato trovato alcun numero	–	come sopra
contact.phones[].numberstring	Il numero, di solito in formato internazionale.	`"+49374574447100"`	come sopra
contact.phones[].typestring	Tipo di numero. organization significa: un numero dell’azienda.	`"organization"`	come sopra
contact.phones[].entitystring	L’azienda a cui appartiene il numero.	`"Hetzner Online GmbH"`	come sopra
contact.phones[].labelstring	A cosa serve il numero, ad esempio centralino o fax.	`"Öffentliche Unternehmens-Telefonnummer"`	come sopra
profilesobject	Pagine web sulla persona, con linkedin e other.	–	sempre
profiles.linkedinstring\|null	Indirizzo del profilo LinkedIn.Vuoto se non ne è stato trovato alcuno	`null`	raramente
profiles.otherarray	Altre pagine sulla persona, ad esempio articoli di stampa o pagine del team, come lista di indirizzi.Vuoto se non ne sono state trovate	–	quasi sempre

Un’AI compone queste informazioni da fonti pubbliche. Usiamo la tecnologia più recente e investiamo molto nella qualità; singoli errori restano comunque possibili.

Partecipazioni e rete

Due feature ampliano il profilo persona: shareholdings mostra le aziende in cui la persona detiene partecipazioni. network mostra le aziende e le persone a cui è collegata, su due livelli. Entrambe vengono addebitate solo se restituiscono dati.

Campo
Campo	Significato	Esempio	Disponibilità
shareholdingsobject\|null	Aziende in cui la persona detiene partecipazioni oggi.Vuoto se non è nota alcuna partecipazione`shareholdings`	–	in parte
shareholdings.holdings.currentarray	Le partecipazioni attuali come lista.	–	come sopra
shareholdings.holdings.current[].organizationobject	L’azienda con entity_id, name, status, legal_form, address e registration, strutturata come nei dati anagrafici.	–	come sopra
shareholdings.holdings.current[].ownership.percentagenumber\|null	Quota del capitale in percentuale, ad esempio 33.33.	`100`	come sopra
shareholdings.holdings.current[].ownership.contributionobject\|null	Valore nominale della partecipazione con amount e currency.	–	come sopra
shareholdings.holdings.current[].as_ofstring\|null	Data dell’informazione nel formato YYYY-MM-DD.	`"2025-01-13"`	come sopra
shareholdings.summary.total_currentinteger	Numero di partecipazioni attuali.	`3`	come sopra
networkobject\|null	Aziende e persone a cui la persona è collegata, su due livelli. Strutturata come network nel profilo aziendale.`network` · da Pro · Beta	–	quasi sempre
network.depthinteger	Quanti livelli copre la rete, contati dalla persona. La persona stessa è il livello 0.	`2`	come sopra
network.nodesarray	I nodi: persone (PERSON) e aziende (ORGANIZATION) con entity_id, name e il loro livello. La persona stessa ha is_root true.	–	come sopra
network.connectionsarray	I collegamenti tra due nodi, ciascuno con tipo (ROLE, OWNERSHIP o GROUP), label, periodo e is_current.	–	come sopra

Avanti

fetch-organization L’endpoint con la feature related_persons e Tempo reale. fetch-person Recuperare il profilo persona: parametri, costi ed errori. Trovare amministratori e soci Passo dopo passo dall’azienda alle sue persone. Soci e partecipazioni Chi possiede un’azienda e in cosa detiene partecipazioni.