Endpoints

GET

/v1/fetch-person

15-20 credits • 60/min

Merge commercial-register data and public web sources into a single person profile. ai_search is always on here — the 15-credit base price already includes AI enrichment.

Requires an active Plus, Pro, or Max subscription. Without one, the endpoint returns 403 with error "subscription_required".

Parameters

Name	Type	Required	Description
api_key	string	REQUIRED	Your API key. Only required if you use neither the x-api-key header nor a Bearer token.
person_q	string	REQUIRED	The person's name (min. 2 chars, required).
organization_q	string	REQUIRED	A company used as context to tell apart people with the same name (min. 2 chars, required).
feature	string[]	optional	Optional extra feature. Currently supported: shareholdings.

Available Features

shareholdings +5 credits

The person's holdings in companies (name, share, role, as-of date). +5 credits — only charged when data is returned.

network Beta Pro / Max

+25 credits

The relationship network of the person: connections to companies and people as a graph of nodes and connections. Requires a Pro or Max plan; only charged when at least one connection is returned.

Example Request

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));

Example Response

{
  "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
  }
}

Core Person Data

Always included: entity_id, name, birth_date, name_parts, location, bio, expertise, contact, profiles, handelsregister_roles, affiliations