Endpoints

GET

/v1/fetch-person

15-20 Credits • 60/min

Handelsregisterdaten und öffentliche Web-Quellen zu einem Personenprofil zusammenführen. ai_search ist hier immer aktiv — die 15 Credits Grundpreis enthalten die AI-Anreicherung bereits.

Erfordert ein aktives Plus-, Pro- oder Max-Abo. Ohne Abo antwortet der Endpunkt mit 403 und error "subscription_required".

Parameter

Nom	Type	Requis	Description
api_key	string	REQUIS	Votre clé API. Requise si vous n'utilisez pas l'en-tête x-api-key ou le token Bearer
person_q	string	REQUIS	Name der Person (mind. 2 Zeichen, erforderlich).
organization_q	string	REQUIS	Ein Unternehmen als Kontext, um Personen mit gleichem Namen zu unterscheiden (mind. 2 Zeichen, erforderlich).
feature	string[]	optionnel	Optionales Zusatzfeature. Zurzeit unterstützt: shareholdings.

Verfügbare Features

shareholdings +5 credits

Beteiligungen der Person an Unternehmen (Name, Anteil, Rolle, Stichtag). +5 Credits — nur berechnet, wenn Daten geliefert werden.

network Beta Pro / Max

+25 credits

Das Beziehungsnetzwerk der Person: Verbindungen zu Unternehmen und Personen als Graph mit Knoten und Verbindungen. Nur mit einem Pro- oder Max-Abo verfügbar; nur berechnet, wenn mindestens eine Verbindung geliefert wird.

Beispiel-Anfrage

curl -X GET 'https://handelsregister.ai/api/v1/fetch-person?person_q=Max%20Mustermann&organization_q=Beispielwerk%20Analytics%20GmbH&features=shareholdings' \
     -H 'x-api-key: YOUR_API_KEY'

import requests

url = "https://handelsregister.ai/api/v1/fetch-person"
headers = {"x-api-key": "YOUR_API_KEY"}
params = {
    "person_q": "Max Mustermann",
    "organization_q": "Beispielwerk Analytics GmbH",
    "features": ["shareholdings"],
}

response = requests.get(url, headers=headers, params=params)
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', 'Beispielwerk Analytics GmbH');
url.searchParams.append('features', 'shareholdings');

fetch(url, {
  headers: {
    'x-api-key': 'YOUR_API_KEY'
  }
})
  .then(response => response.json())
  .then(data => console.log(data));

Beispiel-Antwort

{
  "entity_id": "f1e2d3c4b5a69788a7b6c5d4e3f2a1b0",
  "name": "Max Mustermann",
  "birth_date": "1985-07-14",
  "name_parts": {
    "given": "Max",
    "family": "Mustermann",
    "maiden": null,
    "canonical_name": "Mustermann, Max",
    "previous_names": null
  },
  "location": {
    "home": {
      "city": "München"
    }
  },
  "bio": "Max Mustermann ist Mitgründer und Geschäftsführer der Beispielwerk Analytics GmbH...",
  "expertise": [
    "Produktentwicklung",
    "Softwareentwicklung",
    "Datenanalyse",
    "KI"
  ],
  "contact": {
    "emails": [
      {
        "address": "[email protected]",
        "type": "organization",
        "label": "Allgemeine Kontakt-E-Mail"
      }
    ],
    "phones": []
  },
  "profiles": {
    "linkedin": "https://linkedin.com/in/max-mustermann",
    "github": "https://github.com/max-mustermann",
    "other": []
  },
  "affiliations": [
    {
      "organization": "Beispielwerk Analytics GmbH",
      "relation": "Geschäftsführer"
    }
  ],
  "handelsregister_roles": [
    {
      "entity_id": "b4a3c2d1e5f697887a6b5c4d3e2f1a0b",
      "name": "Beispielwerk Analytics GmbH",
      "label": "MANAGING_DIRECTOR",
      "role": {
        "en": "Managing Director",
        "de": "Geschäftsführer"
      },
      "start_date": "2019-06-03",
      "end_date": null
    }
  ],
  "shareholdings": {
    "holdings": {
      "current": [
        {
          "organization": {
            "entity_id": "b4a3c2d1e5f697887a6b5c4d3e2f1a0b",
            "name": "Beispielwerk Analytics GmbH",
            "status": "ACTIVE",
            "legal_form": "GmbH",
            "address": {
              "house_number": "12",
              "street": "Beispielstraße",
              "postal_code": "80331",
              "city": "München",
              "county": "München (Stadt)",
              "state": "Bayern",
              "country": "DEU",
              "coordinates": {
                "latitude": 48.13743,
                "longitude": 11.57549
              }
            },
            "registration": {
              "court": "München",
              "register_type": "HRB",
              "register_number": "254891"
            }
          },
          "ownership": {
            "percentage": 25.0,
            "contribution": {
              "amount": 12500,
              "currency": "EUR"
            }
          },
          "as_of": "2025-03-15"
        }
      ]
    },
    "summary": {
      "total_current": 1
    }
  },
  "meta": {
    "request_credit_cost": 20,
    "credits_remaining": 9996743
  }
}

Grundlegende Personendaten

Immer enthalten: entity_id, name, birth_date, name_parts, location, bio, expertise, contact, profiles, handelsregister_roles, affiliations