curl -H 'X-API-KEY: YOUR_API_KEY' \
"https://handelsregister.ai/api/v1/fetch-organization?q=4974f69fe7a081fafbb7a86b0fe603ea&features=financial_kpi&features=balance_sheet_accounts&features=related_persons&features=shareholders&features=ubos&features=shareholdings&features=history&features=annual_financial_statements__html"
# pip install handelsregister
from handelsregister import Handelsregister
client = Handelsregister(api_key="YOUR_API_KEY") # or set HANDELSREGISTER_API_KEY
organization = client.fetch_organization(
q="4974f69fe7a081fafbb7a86b0fe603ea",
features=[
"financial_kpi",
"balance_sheet_accounts",
"related_persons",
"shareholders",
"ubos",
"shareholdings",
"history",
"annual_financial_statements__html",
],
)
print(organization["name"])
// npm install handelsregister
import { Handelsregister } from 'handelsregister';
const client = new Handelsregister('YOUR_API_KEY'); // or set HANDELSREGISTER_API_KEY
const organization = await client.fetchOrganization({
q: '4974f69fe7a081fafbb7a86b0fe603ea',
features: [
'financial_kpi',
'balance_sheet_accounts',
'related_persons',
'shareholders',
'ubos',
'shareholdings',
'history',
'annual_financial_statements__html',
],
});
console.log(organization.name);
// npm install handelsregister
const { Handelsregister } = require('handelsregister');
const client = new Handelsregister(process.env.HANDELSREGISTER_API_KEY);
(async () => {
const organization = await client.fetchOrganization({
q: '4974f69fe7a081fafbb7a86b0fe603ea',
features: [
'financial_kpi',
'balance_sheet_accounts',
'related_persons',
'shareholders',
'ubos',
'shareholdings',
'history',
'annual_financial_statements__html',
],
});
console.log(organization.name);
})();
{
"entity_id": "<32-char hex>",
"name": "<string>",
"status": "<enum: ACTIVE | TERMINATED | DISSOLVED | INSOLVENT>",
"legal_form": "<string>",
"address": {
"house_number": "<string>",
"street": "<string>",
"postal_code": "<string>",
"city": "<string>",
"county": "<string>",
"state": "<string>",
"country": "<ISO country>",
"coordinates": {
"latitude": "<float>",
"longitude": "<float>"
}
},
"registration": {
"court": "<string>",
"register_type": "<string>",
"register_number": "<string>"
},
"registration_date": "<ISO date>",
"purpose": "<string>",
"keywords": [
"<string>"
],
"products_and_services": [],
"contact_data": {
"website": "<URL>",
"phone_number": "<phone>",
"email": null
},
"industry_classification": {
"WZ2008": [],
"WZ2025": [
{
"code": "<string>",
"label": "<string>"
}
]
},
"annual_financial_statements__html": [
{
"document_type": "<string>",
"document_date": "<ISO date>",
"document_title": "<string>",
"language": "<string>",
"year": "<int>",
"document_html": "<string>"
}
],
"profit_and_loss_account": [],
"balance_sheet_accounts": [
{
"year": "<int>",
"balance_sheet_accounts": [
{
"name": {
"de": "<string>",
"en": "<string>",
"in_report": "<string>"
},
"value": "<float>",
"children": [
{
"name": {
"de": "<string>",
"en": "<string>",
"in_report": "<string>"
},
"value": "<float>",
"children": [
{
"name": {
"de": "<string>",
"en": "<string>",
"in_report": "<string>"
},
"value": "<float>",
"children": [
{
"name": {
"de": "<string>",
"in_report": "<string>"
},
"value": "<float>",
"children": []
}
]
}
]
}
]
}
]
}
],
"shareholdings": {
"holdings": {
"current": [
{
"organization": {
"entity_id": "<32-char hex>",
"name": "<string>",
"status": "<enum: ACTIVE | TERMINATED | DISSOLVED | INSOLVENT>",
"legal_form": "<string>",
"address": {
"house_number": "<string>",
"street": "<string>",
"postal_code": "<string>",
"city": "<string>",
"county": "<string>",
"state": "<string>",
"country": "<ISO country>",
"coordinates": {
"latitude": "<float>",
"longitude": "<float>"
}
},
"registration": {
"court": "<string>",
"register_type": "<string>",
"register_number": "<string>"
}
},
"ownership": {
"percentage": "<float>",
"contribution": {
"amount": "<float>",
"currency": "<ISO currency>"
}
},
"as_of": "<string>"
}
]
},
"summary": {
"total_current": "<int>"
}
},
"ubos": {
"beneficial_owners": [],
"unresolved_beneficial_owners": [
{
"reason": "<string>",
"entity_id": null,
"name": "<string>",
"legal_form": null,
"address": {
"country": "<ISO country>"
},
"registration": {
"court": "<string>",
"register_type": "<string>",
"register_number": "<string>"
},
"ownership_percentage": "<float>",
"via": [
{
"depth": "<int>",
"name": "<string>",
"entity_id": "<32-char hex>",
"step_percentage": "<float>"
}
]
}
],
"coverage": {
"resolved_percentage": "<int>",
"unresolved_percentage": "<float>"
}
},
"financial_kpi": [
{
"year": "<int>",
"employees": null,
"active_total": "<float>",
"revenue": null,
"material_expenses": null,
"personnel_expenses": null,
"net_income": "<float>"
}
],
"representation_scheme": {
"current": [
"<string>"
],
"history": [
{
"value": [
"<string>"
],
"effective_from": "<string>",
"effective_to": "<string>"
}
]
},
"related_persons": {
"current": [
{
"entity_id": "<32-char hex>",
"label": "<string>",
"role": {
"en": {
"long": "<string>",
"short": "<string>"
},
"de": {
"long": "<string>",
"short": "<string>"
}
},
"name": "<string>",
"start_date": "<ISO date>",
"end_date": null,
"birth_date": null,
"name_parts": {
"given": "<string>",
"family": "<string>",
"maiden": null,
"canonical_name": "<string>",
"previous_names": null
},
"titles": [
"<string>"
],
"location": {
"home": {
"city": "<string>"
}
},
"organization_representation_scheme": {
"current": [
"<string>"
],
"history": [
{
"value": [
"<string>"
],
"effective_from": "<string>",
"effective_to": "<string>"
}
]
},
"role_representation_scheme": {
"current": [
"<string>"
],
"history": [
{
"value": [
"<string>"
],
"effective_from": "<string>",
"effective_to": null
}
]
}
}
],
"past": [
{
"entity_id": null,
"label": "<string>",
"role": {
"en": {
"long": "<string>",
"short": "<string>"
},
"de": {
"long": "<string>",
"short": "<string>"
}
},
"name": "<string>",
"start_date": "<ISO date>",
"end_date": "<ISO date>",
"birth_date": null,
"name_parts": {
"given": "<string>",
"family": "<string>",
"maiden": null,
"canonical_name": "<string>",
"previous_names": null
},
"location": {
"home": {
"city": null
}
},
"organization_representation_scheme": {
"latest": [
"<string>"
],
"history": [
{
"value": [
"<string>"
],
"effective_from": "<string>",
"effective_to": "<string>"
}
]
},
"role_representation_scheme": {
"latest": [
"<string>"
],
"history": [
{
"value": [
"<string>"
],
"effective_from": "<string>",
"effective_to": "<string>"
}
]
},
"redacted": "<bool>"
}
]
},
"shareholders": {
"total_capital": {
"amount": "<float>",
"currency": "<ISO currency>"
},
"entries": [
{
"shareholder": {
"entity_id": "<32-char hex>",
"entity_name": "<string>",
"address": "<string>",
"country_code": "<ISO country>",
"registration_reference": "<string>"
},
"contribution": {
"amount": "<float>",
"currency": "<ISO currency>"
},
"contribution_ratio": "<float>",
"role": {
"label": "<string>",
"en": {
"long": "<string>",
"short": "<string>"
},
"de": {
"long": "<string>",
"short": "<string>"
}
}
}
],
"history": {
"redacted": "<bool>"
}
},
"capital": {
"current": {
"amount": "<float>",
"currency": "<ISO currency>",
"kind": "<string>"
},
"history": [
{
"value": {
"amount": "<float>",
"currency": "<ISO currency>",
"kind": "<string>"
},
"effective_from": "<string>",
"effective_to": "<string>"
}
]
},
"history": [
{
"entity_type": "<string>",
"name": {
"en": "<string>",
"de": "<string>"
},
"description": {
"short": {
"en": "<string>",
"de": "<string>"
}
},
"start_date": "<ISO date>",
"details": {
"value": "<string>",
"linked_entities": {
"organization": {
"name": "<string>"
}
}
}
}
]
}
Basis-Felder
entity_id
string
Stabile handelsregister.ai-ID (32-stelliger Hex-String).
name
string
Eingetragener Firmenname.
status
enum
ACTIVE, TERMINATED, DISSOLVED oder INSOLVENT.
legal_form
string
Rechtsform (GmbH, AG, KG, …), sofern vorhanden.
address
object
Postanschrift mit street, house_number, postal_code, city, county, state, country und coordinates.
registration
object
Registereintrag mit court, register_type und register_number.
registration_date
date
Datum der Ersteintragung im Handelsregister (ISO).
purpose
string
Unternehmensgegenstand laut Eintragung.
representation_scheme
object
Allgemeine Vertretungsregelung: { current: [...], history: [...] } mit effective_from/effective_to je Fassung.
capital
object
Eingetragenes Kapital: { current, history }. current enthält amount, currency und kind (STAMMKAPITAL, GRUNDKAPITAL, HAFTSUMME, GENEHMIGTES_KAPITAL, BEDINGTES_KAPITAL, VARIABLES_KAPITAL — offene Liste); jeder history-Eintrag hat value, effective_from und effective_to (null = weiterhin gültig). change_amount eines history-Eintrags ist vorzeichenlos und entspricht nicht immer der Differenz zweier aufeinanderfolgender Beträge — Erhöhungen und Herabsetzungen daher aus den Beträgen ableiten. Personengesellschaften und andere Rechtsträger ohne eingetragenes Kapital liefern current: null und eine leere history.
contact_data
object
website, phone_number und email, soweit ermittelbar.
industry_classification
object
Branchencodes nach WZ2008 und WZ2025 mit Labels.
keywords
array<string>
Stichworte, abgeleitet aus dem Unternehmensgegenstand.
products_and_services
array<string>
Produkt- und Dienstleistungsbeschreibungen, soweit ermittelbar.
history
array<object>
Chronologisches Protokoll aller Registeränderungen (Name, Sitz, Kapital, Vertretung, …).
features=financial_kpi
financial_kpi
array<object>
Pro Geschäftsjahr: revenue, employees, active_total (Bilanzsumme), net_income, material_expenses, personnel_expenses.
features=balance_sheet_accounts
balance_sheet_accounts
array<object>
Pro Geschäftsjahr: hierarchische Bilanzpositionen aus dem veröffentlichten Jahresabschluss.
features=profit_and_loss_account
profit_and_loss_account
array<object>
Pro Geschäftsjahr: hierarchische Positionen der Gewinn- und Verlustrechnung.
features=related_persons
related_persons
object
Vertretungsberechtigte Personen: { current: [...], past: [...] } — Geschäftsführer, Vorstände, Prokuristen. Jede Person enthält organization_representation_scheme und role_representation_scheme (aktuelle Regelung + Historie).
features=shareholders
shareholders
object
Gesellschafter: { total_capital, entries: [...], history: { current_as_of, past: [...] } }. Jeder entry enthält shareholder, contribution, contribution_ratio und role; history.past liefert frühere Gesellschafterlisten mit as_of-Datum. total_capital, contribution und contribution_ratio können null sein (z. B. bei Personengesellschaften).
features=ubos
ubos
object
Wirtschaftlich Berechtigte: { beneficial_owners, unresolved_beneficial_owners, coverage } gemäß Transparenzregister.
features=shareholdings
shareholdings
object
Beteiligungen dieses Unternehmens: { holdings: { current: [...] }, summary }. Jede Beteiligung verlinkt eine andere Organisation per entity_id.
features=publications
publications
array<object>
Amtliche Bekanntmachungen aus dem Handelsregister (Datum, Titel, Volltext).
features=annual_financial_statements__html
annual_financial_statements__html
array<object>
Veröffentlichte Jahresabschlüsse mit document_html (gerendertes HTML), document_type, document_title, document_date, language und year.
