Personas y representación

Obtener personas

Pide la función related_persons. La respuesta contiene entonces la clave related_persons con dos listas: current para quienes ocupan su cargo hoy y past para quienes lo han dejado. Cada cargo es una entrada propia. En nuestra solicitud de ejemplo para Hetzner Online GmbH, Ansbach HRB 6089, current contenía tres administradores. Dos de ellos aparecían de nuevo en past con su antigua Prokura (poder general mercantil). Todos los datos personales de las respuestas de ejemplo son datos de muestra.

curl -G "https://handelsregister.ai/api/v1/fetch-organization" \
  -H "x-api-key: TU_CLAVE_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": "TU_CLAVE_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": "TU_CLAVE_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 · Respuesta de ejemplo: Hetzner Online GmbH con la función related_persons, abreviada a nombre y personas

Campo
Campo	Significado	Ejemplo	Disponibilidad
related_personsobject\|null	Todas las personas inscritas de la empresa, divididas en current y past.`related_persons`	–	siempre
related_persons.currentarray	Personas que ocupan su cargo hoy.	–	como arriba
related_persons.pastarray	Personas que lo han dejado, con los mismos campos que current. En las dos reglas de representación, latest sustituye a current: la última versión antes de su salida.Vacío cuando nadie ha salido desde la inscripción	–	casi siempre

Campos de una persona

Cada entrada de current y past tiene los mismos campos. Sin Tiempo real, una persona tiene la misma entity_id en todos los perfiles de empresa y en el perfil de persona. Así la reconoces entre empresas. Las personas de una consulta con Tiempo real tienen IDs propios.

Campo
Campo	Significado	Ejemplo	Disponibilidad
related_persons.current[].entity_idstring\|null	ID de la persona. Sin Tiempo real es el mismo en todos los perfiles de empresa y coincide con la entity_id del perfil de persona.`related_persons`	`"ea3a1670232611a992727ed067216d07"`	siempre
related_persons.current[].labelstring	Cargo como valor fijo. Son posibles otros valores.Valores: `MANAGING_DIRECTOR` administrador (Geschäftsführer), `TEMPORARY_MANAGING_DIRECTOR` administrador de emergencia (Notgeschäftsführer), `BOARD` miembro del consejo de dirección (Vorstand), `BOARD_CHAIR` presidencia del consejo de dirección, `DIRECTOR` director ejecutivo, por ejemplo de una SE, `PROCURA` apoderado con Prokura (Prokurist), `LIQUIDATOR` liquidador, `INSOLVENCY_ADMINISTRATOR` administrador concursal, `REPRESENTATIVE` representante permanente, `FULLY_LIABLE_PARTNER` socio colectivo (persönlich haftender Gesellschafter), `LIMITED_PARTNER` socio comanditario (Kommanditist), `PARTNER` socio, `OWNER` titular (Inhaber), `PROPRIETOR` titular (Inhaber), `TREASURER` tesorero de una asociación, `SECRETARY` secretario de una asociación, `YOUTH_WARDEN` responsable juvenil de una asociación, `WATER_WARDEN` responsable de aguas de una asociación, `OTHER` otro cargo	`"MANAGING_DIRECTOR"`	como arriba
related_persons.current[].roleobject	Nombre del cargo para mostrar, en de y en, cada uno largo (long) y corto (short), por ejemplo Geschäftsführer y GF.	–	como arriba
related_persons.current[].namestring	Nombre completo tal como figura en el registro.	`"Paul Musterwald"`	como arriba
related_persons.current[].name_partsobject	El nombre dividido en sus partes, para ordenar y comparar.	–	como arriba
related_persons.current[].name_parts.givenstring\|null	Nombre de pila, todos si hay varios.	`"Paul"`	como arriba
related_persons.current[].name_parts.familystring\|null	Apellido.	`"Musterwald"`	como arriba
related_persons.current[].name_parts.canonical_namestring\|null	El nombre, normalmente en la forma “Apellido, Nombre”, para ordenar y comparar.	`"Musterwald, Paul"`	como arriba
related_persons.current[].name_parts.maidenstring\|null	Apellido de nacimiento.Vacío cuando no hay ninguno inscrito	`null`	rara vez
related_persons.current[].name_parts.previous_namesarray\|null	Nombres anteriores de la persona como lista.Vacío cuando no hay ninguno inscrito	`null`	como arriba
related_persons.current[].titlesarray	Títulos académicos, por ejemplo Dr. La clave falta si no hay ningún título inscrito.	–	como arriba
related_persons.current[].birth_datestring\|null	Fecha de nacimiento en el formato YYYY-MM-DD, tal como está inscrita.Vacío cuando no hay ninguna fecha inscrita	`"1989-07-18"`	casi siempre
related_persons.current[].locationobject\|null	Lugares de la persona.	–	como arriba
related_persons.current[].location.home.citystring\|null	Lugar de residencia, tal como está inscrito. El registro no contiene ninguna dirección completa.Vacío cuando no hay ningún lugar de residencia inscrito	`"Exempelingen i. Bay."`	como arriba
related_persons.current[].start_datestring\|null	Inicio del cargo en el formato YYYY-MM-DD.Vacío cuando no se conoce el inicio, por ejemplo con Tiempo real	`"2019-01-04"`	como arriba
related_persons.current[].end_datestring\|null	Fin del cargo. Está informado en las personas de past.Vacío cuando el cargo sigue existiendo	`null`	siempre

Administradores y consejo de dirección

Los administradores (Geschäftsführer) de una GmbH o UG tienen el label MANAGING_DIRECTOR. El consejo de dirección (Vorstand) de una AG, SE o eG lo reconoces por BOARD, su presidencia por BOARD_CHAIR. Cuando una empresa se disuelve, los liquidadores con LIQUIDATOR asumen la representación.

Comprueba siempre los cargos por label. Los textos de role están pensados para mostrarse.

Prokura

La Prokura es el poder general inscrito para representar a la empresa en casi todos los negocios. Los apoderados (Prokuristen) tienen el label PROCURA. Si alguien puede actuar solo o solo junto con otros está en role_representation_scheme, por ejemplo “Gesamtprokura gemeinsam mit einem Vorstandsmitglied” (Prokura conjunta junto con un miembro del consejo de dirección).

Socios colectivos

En una KG, OHG y KGaA, los socios colectivos (persönlich haftende Gesellschafter) representan a la empresa. Tienen el label FULLY_LIABLE_PARTNER. Los socios comanditarios (Kommanditisten) de una KG figuran en el registro con LIMITED_PARTNER, el titular de una e.K. con OWNER, los socios de una PartG o eGbR con PARTNER.

En una GmbH & Co. KG, el socio colectivo suele ser a su vez una GmbH. Sus administradores los encuentras en el perfil de empresa de esa GmbH.

Cargos por forma jurídica

Qué cargos tiene una empresa se deduce de su forma jurídica. La tabla muestra qué labels ves normalmente por forma jurídica. Todos los labels con su significado figuran arriba en label.

Forma jurídica
Forma jurídica	Labels habituales
GmbH, UG	MANAGING_DIRECTOR, PROCURA, en liquidación LIQUIDATOR
AG, SE	BOARD, BOARD_CHAIR, PROCURA
KGaA	FULLY_LIABLE_PARTNER, PROCURA
GmbH & Co. KG	LIMITED_PARTNER, PROCURA
KG, OHG	FULLY_LIABLE_PARTNER, en una KG LIMITED_PARTNER, PROCURA
e.K.	OWNER
eG	BOARD, BOARD_CHAIR, PROCURA
PartG, eGbR	PARTNER
e.V.	BOARD

Poder de representación

Cada persona llega con dos conjuntos de reglas. role_representation_scheme es su propia facultad, por ejemplo “einzelvertretungsberechtigt” (puede representar sola). organization_representation_scheme es la regla general de la empresa, la misma que representation_scheme en los datos básicos. Ambos tienen current e history; en las personas anteriores, latest sustituye a current.

Campo
Campo	Significado	Ejemplo	Disponibilidad
related_persons.current[].role_representation_schemeobject	El poder de representación propio de la persona, por ejemplo “einzelvertretungsberechtigt” (puede representar sola) o una exención del § 181 BGB. current es la versión vigente, history los cambios con value, effective_from y effective_to.`related_persons`	–	casi siempre: GmbH, UG, AG, SE, KGaA, GmbH & Co. KG, KG, OHG, eG, PartG rara vez: e.K.
related_persons.current[].organization_representation_schemeobject	Las reglas generales de representación de la empresa, incluidas con cada persona. Estructuradas como role_representation_scheme.	–	siempre: GmbH, UG, GmbH & Co. KG, KG, OHG, eG, PartG casi siempre: AG, SE, KGaA, e.K.

Personas con Tiempo real

Con realtime_mode=handelsregister-default, las personas inscritas actualmente llegan directamente del Handelsregister (Registro Mercantil), incluso sin la función related_persons. Entonces solo se cobra Tiempo real, no la función. La respuesta contiene solo current.

En esta lista, start_date y end_date están vacíos, los nombres pueden ser más cortos y la entity_id de una persona puede diferir de la que tiene sin Tiempo real. Asigna las personas por nombre y fecha de nacimiento.

Si pides Tiempo real y related_persons juntos, current viene de la consulta en directo y past del perfil de empresa. Entonces se cobra también la función.

Campo
Campo	Significado	Ejemplo	Disponibilidad
related_persons.current[].name_parts.aliasesarray	Grafías del nombre de la consulta en directo, en la forma “Apellido, Nombre”. Solo con Tiempo real.`related_persons`	–	siempre

Perfil de persona

El perfil de persona (fetch-person) describe a una sola persona: sus cargos en todas las empresas con las que está conectada y lo que dicen de ella las fuentes web públicas. Encuentras a la persona por su nombre y una empresa en la que ocupa u ocupó un cargo.

El perfil de persona viene con cualquier suscripción de créditos desde Plus. Una solicitud suele tardar de diez a treinta segundos, porque investigamos en la web. Configura el timeout de tu cliente en al menos 120 segundos.

curl -G "https://handelsregister.ai/api/v1/fetch-person" \
  -H "x-api-key: TU_CLAVE_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": "TU_CLAVE_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": "TU_CLAVE_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 · Respuesta de ejemplo: perfil de persona de Max Felix Mustermann (datos de muestra) en Hetzner Online GmbH, abreviado

La persona

El nombre, la fecha de nacimiento y el lugar de residencia proceden del registro. La entity_id es la misma que en related_persons de los perfiles de empresa sin Tiempo real.

Campo
Campo	Significado	Ejemplo	Disponibilidad
entity_idstring	ID de la persona. El mismo ID aparece en related_persons de los perfiles de empresa sin Tiempo real.Perfil de persona	`"08ed5f967956831ca6588930fd2693ed"`	siempre
namestring	Nombre completo tal como figura en el registro.	`"Max Felix Mustermann"`	como arriba
birth_datestring\|null	Fecha de nacimiento en el formato YYYY-MM-DD, tal como está inscrita.Vacío cuando no hay ninguna fecha inscrita	`"1976-01-15"`	casi siempre
name_partsobject	El nombre dividido en sus partes, estructurado como en related_persons.	–	siempre
name_parts.givenstring\|null	Nombre de pila, todos si hay varios.	`"Max Felix"`	como arriba
name_parts.familystring\|null	Apellido.	`"Mustermann"`	como arriba
name_parts.canonical_namestring\|null	El nombre, normalmente en la forma “Apellido, Nombre”, para ordenar y comparar.	`"Mustermann, Max Felix"`	como arriba
name_parts.maidenstring\|null	Apellido de nacimiento.Vacío cuando no hay ninguno inscrito	`null`	rara vez
name_parts.previous_namesarray\|null	Nombres anteriores de la persona como lista.Vacío cuando no hay ninguno inscrito	`null`	como arriba
locationobject	Lugares de la persona.	–	casi siempre
location.home.citystring\|null	Lugar de residencia, tal como está inscrito.Vacío cuando no hay ningún lugar de residencia inscrito	`"Musterheim"`	como arriba

Cargos y conexiones

handelsregister_roles enumera cada cargo inscrito de la persona con la empresa y su periodo. Usa la entity_id de una empresa para obtener su perfil de empresa. affiliations resume brevemente las conexiones, del registro y de la web.

Campo
Campo	Significado	Ejemplo	Disponibilidad
handelsregister_rolesarray	Los cargos inscritos de la persona con empresa y periodo, actuales y anteriores.Perfil de persona	–	siempre
handelsregister_roles[].entity_idstring	entity_id de la empresa, para un perfil de empresa en el parámetro q.	`"0b3435f83ce8591300625100815d4583"`	como arriba
handelsregister_roles[].namestring	Nombre de la empresa.	`"Hetzner Online GmbH"`	como arriba
handelsregister_roles[].labelstring	Cargo como valor fijo, los mismos valores que label en related_persons, por ejemplo MANAGING_DIRECTOR, BOARD, PROCURA o LIMITED_PARTNER.	`"BOARD"`	como arriba
handelsregister_roles[].roleobject	Nombre del cargo para mostrar, como texto en de y en.	–	como arriba
handelsregister_roles[].start_datestring\|null	Inicio del cargo en el formato YYYY-MM-DD.Vacío cuando no se conoce el inicio	`"2002-10-15"`	casi siempre
handelsregister_roles[].end_datestring\|null	Fin del cargo.Vacío cuando el cargo sigue existiendo	`"2015-07-28"`	siempre
affiliationsarray	Las empresas con las que está conectada la persona, cada una con el tipo de conexión. Resumidas de fuentes registrales y web.	–	como arriba
affiliations[].organizationstring	Nombre de la empresa.	`"ENSoXX Holding AG"`	como arriba
affiliations[].relationstring	Tipo de conexión como texto en alemán, por ejemplo Geschäftsführer (administrador), Prokura o Kommanditist (socio comanditario).	`"Vorstandsmitglied"`	como arriba

Investigación web

Recopilamos la breve biografía, las áreas de especialidad, las vías de contacto y las fuentes de fuentes web públicas. Cuánto hay depende de lo visible que sea la persona en la web.

Campo
Campo	Significado	Ejemplo	Disponibilidad
biostring\|null	Breve biografía de la persona en una o dos frases, en alemán.Vacío cuando la web tiene muy poco sobre la persona (entonces null)Perfil de persona	`"Max Felix Mustermann ist Geschäftsführer der Hetzner Onl…"`	casi siempre
expertisearray	Áreas de especialidad y temas de la persona como lista.Vacío cuando la web tiene muy poco sobre la persona	–	como arriba
contactobject	Vías de contacto publicadas, con emails y phones.	–	siempre
contact.emailsarray	Direcciones de email como lista.Vacío cuando no se encontró ninguna dirección	–	rara vez
contact.emails[].addressstring	La dirección de email.	`"[email protected]"`	como arriba
contact.emails[].typestring	Tipo de dirección. organization significa: una dirección de la empresa, no privada.	`"organization"`	como arriba
contact.emails[].labelstring	Para qué es la dirección, como texto breve.	`"Allgemeine Unternehmenskontakt-E-Mail"`	como arriba
contact.phonesarray	Números de teléfono como lista.Vacío cuando no se encontró ningún número	–	como arriba
contact.phones[].numberstring	El número, normalmente en formato internacional.	`"+49374574447100"`	como arriba
contact.phones[].typestring	Tipo de número. organization significa: un número de la empresa.	`"organization"`	como arriba
contact.phones[].entitystring	La empresa a la que pertenece el número.	`"Hetzner Online GmbH"`	como arriba
contact.phones[].labelstring	Para qué es el número, por ejemplo centralita o fax.	`"Öffentliche Unternehmens-Telefonnummer"`	como arriba
profilesobject	Páginas web sobre la persona, con linkedin y other.	–	siempre
profiles.linkedinstring\|null	Dirección del perfil de LinkedIn.Vacío cuando no se encontró ninguno	`null`	rara vez
profiles.otherarray	Otras páginas sobre la persona, por ejemplo artículos de prensa o páginas de equipo, como lista de direcciones.Vacío cuando no se encontró ninguna	–	casi siempre

Una IA compila esta información a partir de fuentes públicas. Para ello usamos la tecnología más actual e invertimos mucho en calidad; aun así, pueden darse errores puntuales.

Participaciones y red

Dos funciones amplían el perfil de persona: shareholdings muestra las empresas en las que la persona tiene participaciones. network muestra las empresas y personas con las que está conectada, en dos niveles. Ambas solo se cobran si devuelven datos.

Campo
Campo	Significado	Ejemplo	Disponibilidad
shareholdingsobject\|null	Empresas en las que la persona tiene participaciones hoy.Vacío cuando no se conoce ninguna participación`shareholdings`	–	a veces
shareholdings.holdings.currentarray	Las participaciones actuales como lista.	–	como arriba
shareholdings.holdings.current[].organizationobject	La empresa con entity_id, name, status, legal_form, address y registration, estructurada como en los datos básicos.	–	como arriba
shareholdings.holdings.current[].ownership.percentagenumber\|null	Participación en el capital en porcentaje, por ejemplo 33.33.	`100`	como arriba
shareholdings.holdings.current[].ownership.contributionobject\|null	Importe nominal de la participación con amount y currency.	–	como arriba
shareholdings.holdings.current[].as_ofstring\|null	Fecha de la información en el formato YYYY-MM-DD.	`"2025-01-13"`	como arriba
shareholdings.summary.total_currentinteger	Número de participaciones actuales.	`3`	como arriba
networkobject\|null	Empresas y personas con las que está conectada la persona, en dos niveles. Estructurado como network en el perfil de empresa.`network` · desde Pro · Beta	–	casi siempre
network.depthinteger	Cuántos niveles abarca la red, contados desde la persona. La propia persona es el nivel 0.	`2`	como arriba
network.nodesarray	Los nodos: personas (PERSON) y empresas (ORGANIZATION) con entity_id, nombre y su nivel. La propia persona tiene is_root true.	–	como arriba
network.connectionsarray	Las conexiones entre dos nodos, cada una con kind (ROLE, OWNERSHIP o GROUP), label, periodo e is_current.	–	como arriba

fetch-organization El endpoint con la función related_persons y Tiempo real. fetch-person Obtener el perfil de persona: parámetros, costes y errores. Encontrar administradores y socios Paso a paso de la empresa a sus personas. Socios y participaciones Quién es propietario de una empresa y en qué participa ella.