Pessoas e representação – Documentação

Obter pessoas

Solicite o recurso related_persons. A resposta então contém a chave related_persons com duas listas: current para todos que exercem sua função hoje e past para todos que saíram. Cada função é uma entrada própria. Na nossa requisição de exemplo para a Hetzner Online GmbH, Ansbach HRB 6089, current continha três diretores. Dois deles apareciam de novo em past com sua antiga Prokura. Todos os dados pessoais nas respostas de exemplo são fictícios.

curl -G "https://handelsregister.ai/api/v1/fetch-organization" \
  -H "x-api-key: SUA_CHAVE_DE_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": "SUA_CHAVE_DE_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": "SUA_CHAVE_DE_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 · Resposta de exemplo: Hetzner Online GmbH com o recurso related_persons, resumida a nome e pessoas

Campo
Campo	Significado	Exemplo	Disponibilidade
related_personsobject\|null	Todas as pessoas registradas da empresa, divididas em current e past.`related_persons`	–	sempre
related_persons.currentarray	Pessoas que exercem sua função hoje.	–	como acima
related_persons.pastarray	Pessoas que saíram, com os mesmos campos de current. Nas duas regras de representação, latest substitui current: a última versão antes da saída.Vazio quando ninguém saiu desde o registro	–	geralmente

Campos de uma pessoa

Toda entrada em current e past tem os mesmos campos. Sem Tempo real, uma pessoa tem o mesmo entity_id em todos os perfis de empresas e no perfil de pessoa. Assim você a reconhece entre empresas. Pessoas de uma consulta em Tempo real têm IDs próprios.

Campo
Campo	Significado	Exemplo	Disponibilidade
related_persons.current[].entity_idstring\|null	ID da pessoa. Sem Tempo real, é o mesmo em todos os perfis de empresas e corresponde ao entity_id no perfil de pessoa.`related_persons`	`"ea3a1670232611a992727ed067216d07"`	sempre
related_persons.current[].labelstring	Função como valor fixo. Outros valores são possíveis.Valores: `MANAGING_DIRECTOR` diretor (Geschäftsführer), `TEMPORARY_MANAGING_DIRECTOR` diretor de emergência (Notgeschäftsführer), `BOARD` membro da diretoria executiva (Vorstand), `BOARD_CHAIR` presidente da diretoria executiva, `DIRECTOR` diretor executivo, por exemplo de uma SE, `PROCURA` titular de Prokura (Prokurist), `LIQUIDATOR` liquidante, `INSOLVENCY_ADMINISTRATOR` administrador judicial da insolvência, `REPRESENTATIVE` representante permanente, `FULLY_LIABLE_PARTNER` sócio de responsabilidade ilimitada (persönlich haftender Gesellschafter), `LIMITED_PARTNER` sócio comanditário (Kommanditist), `PARTNER` sócio, `OWNER` proprietário (Inhaber), `PROPRIETOR` proprietário (Inhaber), `TREASURER` tesoureiro de uma associação, `SECRETARY` secretário de uma associação, `YOUTH_WARDEN` responsável pela juventude de uma associação, `WATER_WARDEN` responsável pelas águas de uma associação, `OTHER` outra função	`"MANAGING_DIRECTOR"`	como acima
related_persons.current[].roleobject	Nome da função para exibição, em de e en, cada um longo (long) e curto (short), por exemplo Geschäftsführer e GF.	–	como acima
related_persons.current[].namestring	Nome completo como consta no registro.	`"Paul Musterwald"`	como acima
related_persons.current[].name_partsobject	O nome dividido em suas partes, para ordenar e comparar.	–	como acima
related_persons.current[].name_parts.givenstring\|null	Prenome, todos se houver vários.	`"Paul"`	como acima
related_persons.current[].name_parts.familystring\|null	Sobrenome.	`"Musterwald"`	como acima
related_persons.current[].name_parts.canonical_namestring\|null	O nome, geralmente na forma “Sobrenome, Prenome”, para ordenar e comparar.	`"Musterwald, Paul"`	como acima
related_persons.current[].name_parts.maidenstring\|null	Nome de nascimento.Vazio quando nenhum está registrado	`null`	raramente
related_persons.current[].name_parts.previous_namesarray\|null	Nomes anteriores da pessoa, como lista.Vazio quando nenhum está registrado	`null`	como acima
related_persons.current[].titlesarray	Títulos acadêmicos, por exemplo Dr. A chave não aparece se nenhum título estiver registrado.	–	como acima
related_persons.current[].birth_datestring\|null	Data de nascimento no formato YYYY-MM-DD, como registrada.Vazio quando nenhuma data está registrada	`"1989-07-18"`	geralmente
related_persons.current[].locationobject\|null	Locais da pessoa.	–	como acima
related_persons.current[].location.home.citystring\|null	Local de residência, como registrado. O registro não contém endereço completo.Vazio quando nenhum local de residência está registrado	`"Exempelingen i. Bay."`	como acima
related_persons.current[].start_datestring\|null	Início da função no formato YYYY-MM-DD.Vazio quando o início não é conhecido, por exemplo com Tempo real	`"2019-01-04"`	como acima
related_persons.current[].end_datestring\|null	Fim da função. Está preenchido para pessoas em past.Vazio quando a função ainda existe	`null`	sempre

Diretores e diretoria executiva

Os diretores (Geschäftsführer) de uma GmbH ou UG têm o label MANAGING_DIRECTOR. A diretoria executiva (Vorstand) de uma AG, SE ou eG você reconhece por BOARD, seu presidente por BOARD_CHAIR. Quando uma empresa é dissolvida, liquidantes com LIQUIDATOR assumem a representação.

Sempre verifique funções pelo label. Os textos em role servem para exibição.

Prokura

A Prokura é a procuração registrada para representar a empresa em quase todos os negócios. Titulares de Prokura (Prokuristen) têm o label PROCURA. Se alguém pode agir sozinho ou só em conjunto com outros está em role_representation_scheme, por exemplo “Gesamtprokura gemeinsam mit einem Vorstandsmitglied” (Prokura conjunta com um membro da diretoria).

Sócios com responsabilidade ilimitada

Numa KG, OHG e KGaA, os sócios de responsabilidade ilimitada (persönlich haftende Gesellschafter) representam a empresa. Eles têm o label FULLY_LIABLE_PARTNER. Sócios comanditários (Kommanditisten) de uma KG estão no registro com LIMITED_PARTNER, o proprietário de uma e.K. com OWNER, os sócios de uma PartG ou eGbR com PARTNER.

Numa GmbH & Co. KG, a sócia de responsabilidade ilimitada geralmente é ela própria uma GmbH. Os diretores dela estão no perfil da empresa dessa GmbH.

Funções por forma jurídica

As funções que uma empresa tem decorrem da sua forma jurídica. A tabela mostra quais labels você costuma ver por forma jurídica. Todos os labels com seu significado estão listados acima em label.

Forma jurídica
Forma jurídica	Labels típicos
GmbH, UG	MANAGING_DIRECTOR, PROCURA, em liquidação LIQUIDATOR
AG, SE	BOARD, BOARD_CHAIR, PROCURA
KGaA	FULLY_LIABLE_PARTNER, PROCURA
GmbH & Co. KG	LIMITED_PARTNER, PROCURA
KG, OHG	FULLY_LIABLE_PARTNER, numa KG LIMITED_PARTNER, PROCURA
e.K.	OWNER
eG	BOARD, BOARD_CHAIR, PROCURA
PartG, eGbR	PARTNER
e.V.	BOARD

Poder de representação

Toda pessoa vem com dois conjuntos de regras. role_representation_scheme é o poder dela própria, por exemplo “einzelvertretungsberechtigt” (pode representar sozinha). organization_representation_scheme é a regra geral da empresa, igual a representation_scheme nos dados cadastrais. Ambos têm current e history; para pessoas anteriores, latest substitui current.

Campo
Campo	Significado	Exemplo	Disponibilidade
related_persons.current[].role_representation_schemeobject	O poder de representação da própria pessoa, por exemplo “einzelvertretungsberechtigt” (pode representar sozinha) ou uma dispensa do § 181 BGB. current é a versão em vigor, history as alterações com value, effective_from e effective_to.`related_persons`	–	geralmente: GmbH, UG, AG, SE, KGaA, GmbH & Co. KG, KG, OHG, eG, PartG raramente: e.K.
related_persons.current[].organization_representation_schemeobject	As regras gerais de representação da empresa, incluídas em cada pessoa. Estruturado como role_representation_scheme.	–	sempre: GmbH, UG, GmbH & Co. KG, KG, OHG, eG, PartG geralmente: AG, SE, KGaA, e.K.

Pessoas com Tempo real

Com realtime_mode=handelsregister-default, as pessoas registradas no momento vêm direto do Handelsregister, mesmo sem o recurso related_persons. Nesse caso, só o Tempo real é cobrado, não o recurso. A resposta contém só current.

Nessa lista, start_date e end_date ficam vazios, os nomes podem ser mais curtos e o entity_id de uma pessoa pode diferir do usado sem Tempo real. Associe pessoas por nome e data de nascimento.

Se você solicitar Tempo real e related_persons juntos, current vem da consulta ao vivo e past do perfil da empresa. Então o recurso também é cobrado.

Campo
Campo	Significado	Exemplo	Disponibilidade
related_persons.current[].name_parts.aliasesarray	Grafias do nome vindas da consulta ao vivo, na forma “Sobrenome, Prenome”. Só com Tempo real.`related_persons`	–	sempre

Perfil de pessoa

O perfil de pessoa (fetch-person) descreve uma única pessoa: seus cargos em todas as empresas com as quais está ligada e o que fontes públicas da web dizem sobre ela. Você encontra a pessoa pelo nome e por uma empresa em que ela tem ou teve um cargo.

O perfil de pessoa está incluído em toda assinatura de créditos a partir do Plus. Uma requisição costuma levar de dez a trinta segundos, porque pesquisamos na web. Configure o timeout do seu cliente para pelo menos 120 segundos.

curl -G "https://handelsregister.ai/api/v1/fetch-person" \
  -H "x-api-key: SUA_CHAVE_DE_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": "SUA_CHAVE_DE_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": "SUA_CHAVE_DE_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 · Resposta de exemplo: perfil de pessoa de Max Felix Mustermann (dados fictícios) na Hetzner Online GmbH, resumido

A pessoa

Nome, data de nascimento e local de residência vêm do registro. O entity_id é o mesmo que em related_persons dos perfis de empresas sem Tempo real.

Campo
Campo	Significado	Exemplo	Disponibilidade
entity_idstring	ID da pessoa. O mesmo ID aparece em related_persons dos perfis de empresas sem Tempo real.Perfil de pessoa	`"08ed5f967956831ca6588930fd2693ed"`	sempre
namestring	Nome completo como consta no registro.	`"Max Felix Mustermann"`	como acima
birth_datestring\|null	Data de nascimento no formato YYYY-MM-DD, como registrada.Vazio quando nenhuma data está registrada	`"1976-01-15"`	geralmente
name_partsobject	O nome dividido em suas partes, estruturado como em related_persons.	–	sempre
name_parts.givenstring\|null	Prenome, todos se houver vários.	`"Max Felix"`	como acima
name_parts.familystring\|null	Sobrenome.	`"Mustermann"`	como acima
name_parts.canonical_namestring\|null	O nome, geralmente na forma “Sobrenome, Prenome”, para ordenar e comparar.	`"Mustermann, Max Felix"`	como acima
name_parts.maidenstring\|null	Nome de nascimento.Vazio quando nenhum está registrado	`null`	raramente
name_parts.previous_namesarray\|null	Nomes anteriores da pessoa, como lista.Vazio quando nenhum está registrado	`null`	como acima
locationobject	Locais da pessoa.	–	geralmente
location.home.citystring\|null	Local de residência, como registrado.Vazio quando nenhum local de residência está registrado	`"Musterheim"`	como acima

Cargos e ligações

handelsregister_roles lista cada cargo registrado da pessoa com a empresa e o período. Use o entity_id de uma empresa para obter o perfil dela. affiliations resume as ligações brevemente, a partir do registro e da web.

Campo
Campo	Significado	Exemplo	Disponibilidade
handelsregister_rolesarray	Os cargos registrados da pessoa com empresa e período, atuais e anteriores.Perfil de pessoa	–	sempre
handelsregister_roles[].entity_idstring	entity_id da empresa, para um perfil de empresa no parâmetro q.	`"0b3435f83ce8591300625100815d4583"`	como acima
handelsregister_roles[].namestring	Nome da empresa.	`"Hetzner Online GmbH"`	como acima
handelsregister_roles[].labelstring	Cargo como valor fixo, os mesmos valores de label em related_persons, por exemplo MANAGING_DIRECTOR, BOARD, PROCURA ou LIMITED_PARTNER.	`"BOARD"`	como acima
handelsregister_roles[].roleobject	Nome do cargo para exibição, como texto em de e en.	–	como acima
handelsregister_roles[].start_datestring\|null	Início do cargo no formato YYYY-MM-DD.Vazio quando o início não é conhecido	`"2002-10-15"`	geralmente
handelsregister_roles[].end_datestring\|null	Fim do cargo.Vazio quando o cargo ainda existe	`"2015-07-28"`	sempre
affiliationsarray	As empresas com as quais a pessoa está ligada, cada uma com o tipo de ligação. Resumido a partir do registro e de fontes da web.	–	como acima
affiliations[].organizationstring	Nome da empresa.	`"ENSoXX Holding AG"`	como acima
affiliations[].relationstring	Tipo de ligação como texto em alemão, por exemplo Geschäftsführer (diretor), Prokura ou Kommanditist (sócio comanditário).	`"Vorstandsmitglied"`	como acima

Pesquisa na web

Reunimos a minibiografia, as áreas de especialidade, os canais de contato e as fontes a partir de fontes públicas da web. Quanto disso existe depende de quão visível a pessoa é na web.

Campo
Campo	Significado	Exemplo	Disponibilidade
biostring\|null	Minibiografia da pessoa em uma ou duas frases, em alemão.Vazio quando a web tem pouca informação sobre a pessoa (então null)Perfil de pessoa	`"Max Felix Mustermann ist Geschäftsführer der Hetzner Onl…"`	geralmente
expertisearray	Áreas de especialidade e temas da pessoa, como lista.Vazio quando a web tem pouca informação sobre a pessoa	–	como acima
contactobject	Canais de contato divulgados publicamente, com emails e phones.	–	sempre
contact.emailsarray	Endereços de e-mail, como lista.Vazio quando nenhum endereço foi encontrado	–	raramente
contact.emails[].addressstring	O endereço de e-mail.	`"[email protected]"`	como acima
contact.emails[].typestring	Tipo de endereço. organization significa: um endereço da empresa, não um particular.	`"organization"`	como acima
contact.emails[].labelstring	Para que serve o endereço, como texto curto.	`"Allgemeine Unternehmenskontakt-E-Mail"`	como acima
contact.phonesarray	Números de telefone, como lista.Vazio quando nenhum número foi encontrado	–	como acima
contact.phones[].numberstring	O número, geralmente em formato internacional.	`"+49374574447100"`	como acima
contact.phones[].typestring	Tipo de número. organization significa: um número da empresa.	`"organization"`	como acima
contact.phones[].entitystring	A empresa a que o número pertence.	`"Hetzner Online GmbH"`	como acima
contact.phones[].labelstring	Para que serve o número, por exemplo central ou fax.	`"Öffentliche Unternehmens-Telefonnummer"`	como acima
profilesobject	Páginas da web sobre a pessoa, com linkedin e other.	–	sempre
profiles.linkedinstring\|null	Endereço do perfil no LinkedIn.Vazio quando nenhum foi encontrado	`null`	raramente
profiles.otherarray	Outras páginas sobre a pessoa, por exemplo artigos de imprensa ou páginas de equipe, como lista de endereços.Vazio quando nenhuma foi encontrada	–	geralmente

Uma IA reúne essas informações a partir de fontes públicas. Usamos a tecnologia mais recente para isso e investimos muito em qualidade; ainda assim, erros pontuais são possíveis.

Participações e rede

Dois recursos ampliam o perfil de pessoa: shareholdings mostra as empresas em que a pessoa tem participação. network mostra as empresas e pessoas com as quais ela está ligada, em dois níveis. Ambos só são cobrados se retornarem dados.

Campo
Campo	Significado	Exemplo	Disponibilidade
shareholdingsobject\|null	Empresas em que a pessoa tem participação hoje.Vazio quando nenhuma participação é conhecida`shareholdings`	–	em parte
shareholdings.holdings.currentarray	As participações atuais, como lista.	–	como acima
shareholdings.holdings.current[].organizationobject	A empresa com entity_id, name, status, legal_form, address e registration, estruturada como nos dados cadastrais.	–	como acima
shareholdings.holdings.current[].ownership.percentagenumber\|null	Participação no capital em percentual, por exemplo 33.33.	`100`	como acima
shareholdings.holdings.current[].ownership.contributionobject\|null	Valor nominal da participação com amount e currency.	–	como acima
shareholdings.holdings.current[].as_ofstring\|null	Data da informação no formato YYYY-MM-DD.	`"2025-01-13"`	como acima
shareholdings.summary.total_currentinteger	Número de participações atuais.	`3`	como acima
networkobject\|null	Empresas e pessoas com as quais a pessoa está ligada, em dois níveis. Estruturado como network no perfil da empresa.`network` · a partir de Pro · Beta	–	geralmente
network.depthinteger	Quantos níveis a rede abrange, contados a partir da pessoa. A própria pessoa é o nível 0.	`2`	como acima
network.nodesarray	Os nós: pessoas (PERSON) e empresas (ORGANIZATION) com entity_id, name e seu nível. A própria pessoa tem is_root true.	–	como acima
network.connectionsarray	As ligações entre dois nós, cada uma com kind (ROLE, OWNERSHIP ou GROUP), label, período e is_current.	–	como acima

Próximos passos

fetch-organization O endpoint com o recurso related_persons e Tempo real. fetch-person Obter o perfil de pessoa: parâmetros, custos e erros. Encontrar diretores e sócios Passo a passo da empresa até suas pessoas. Sócios e participações Quem é dono de uma empresa e em que ela tem participação.