curl -H 'X-API-KEY: YOUR_API_KEY' \
"https://handelsregister.ai/api/v1/fetch-organization?q=454f5d3bef7f8f7dcfa3a4f962fcc6d7&features=financial_kpi&features=balance_sheet_accounts&features=related_persons&features=shareholders&features=ubos&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="454f5d3bef7f8f7dcfa3a4f962fcc6d7",
features=[
"financial_kpi",
"balance_sheet_accounts",
"related_persons",
"shareholders",
"ubos",
"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: '454f5d3bef7f8f7dcfa3a4f962fcc6d7',
features: [
'financial_kpi',
'balance_sheet_accounts',
'related_persons',
'shareholders',
'ubos',
'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: '454f5d3bef7f8f7dcfa3a4f962fcc6d7',
features: [
'financial_kpi',
'balance_sheet_accounts',
'related_persons',
'shareholders',
'ubos',
'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": [],
"products_and_services": [],
"contact_data": {
"website": null,
"phone_number": null,
"email": null
},
"industry_classification": {
"WZ2008": [],
"WZ2025": [
{
"code": "<string>",
"label": "<string>"
}
]
},
"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>"
}
},
"ubos": {
"beneficial_owners": [
{
"person": {
"entity_id": null,
"name": "<string>",
"birth_date": null,
"name_parts": {
"given": "<string>",
"family": "<string>"
},
"location": null,
"redacted": "<bool>"
},
"ownership_percentage": "<float>",
"paths": [
{
"percentage": "<float>",
"via": []
}
],
"redacted": "<bool>"
}
],
"unresolved_beneficial_owners": [
{
"reason": "<string>",
"entity_id": "<32-char hex>",
"name": "<string>",
"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>",
"via": []
}
],
"coverage": {
"resolved_percentage": "<float>",
"unresolved_percentage": "<float>"
}
},
"shareholdings": null,
"financial_kpi": [
{
"year": "<int>",
"employees": "<int>",
"active_total": "<float>",
"revenue": null,
"material_expenses": null,
"personnel_expenses": null,
"net_income": "<float>"
}
],
"annual_financial_statements__html": [
{
"document_type": "<string>",
"document_date": "<ISO date>",
"document_title": "<string>",
"language": "<string>",
"year": "<int>",
"document_html": "<string>"
}
],
"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": []
}
]
}
]
}
]
}
],
"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
},
"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": []
},
"profit_and_loss_account": [],
"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": {
"@type": "<string>",
"resolution_body": "<string>"
},
"linked_entities": {
"organization": {
"name": "<string>"
}
}
}
}
]
}
Base fields
entity_id
string
Stable handelsregister.ai identifier (32-char hex string).
name
string
Registered legal name of the entity.
status
enum
ACTIVE, TERMINATED, DISSOLVED or INSOLVENT.
legal_form
string
Legal form (GmbH, AG, KG, …) when available.
address
object
Postal address with street, house_number, postal_code, city, county, state, country and coordinates.
registration
object
Register record with court, register_type and register_number.
registration_date
date
Initial entry into the commercial register (ISO date).
purpose
string
Stated business purpose (Unternehmensgegenstand).
representation_scheme
object
General representation scheme: { current: [...], history: [...] } with effective_from/effective_to per version.
capital
object
Registered capital: { current, history }. current carries amount, currency and kind (STAMMKAPITAL, GRUNDKAPITAL, HAFTSUMME, GENEHMIGTES_KAPITAL, BEDINGTES_KAPITAL, VARIABLES_KAPITAL — open enum); each history entry has value, effective_from and effective_to (null = still in force). change_amount on a history entry is unsigned and does not always equal the difference between two consecutive amounts, so derive increases and decreases from the amounts. Partnerships and other entities without registered capital return current: null and an empty history.
contact_data
object
website, phone_number and email when available.
industry_classification
object
Industry codes per WZ2008 and WZ2025 with labels.
keywords
array<string>
Keywords derived from the business purpose.
products_and_services
array<string>
Product and service descriptions when available.
history
array<object>
Chronological log of all register changes (name, seat, capital, representation, …).
features=financial_kpi
financial_kpi
array<object>
Per fiscal year: revenue, employees, active_total (balance-sheet total), net_income, material_expenses, personnel_expenses.
features=balance_sheet_accounts
balance_sheet_accounts
array<object>
Per fiscal year: hierarchical balance-sheet line items from the published annual statement.
features=profit_and_loss_account
profit_and_loss_account
array<object>
Per fiscal year: hierarchical profit-and-loss line items.
features=related_persons
related_persons
object
Authorized representatives: { current: [...], past: [...] } — managing directors, board members, signatories. Each person carries organization_representation_scheme and role_representation_scheme (current scheme + history).
features=shareholders
shareholders
object
Shareholders: { total_capital, entries: [...], history: { current_as_of, past: [...] } }. Each entry carries shareholder, contribution, contribution_ratio and role; history.past delivers previous shareholder lists with an as_of date. total_capital, contribution and contribution_ratio may be null (e.g. for partnerships).
features=ubos
ubos
object
Ultimate beneficial owners: { beneficial_owners, unresolved_beneficial_owners, coverage } as recorded in the transparency register.
features=shareholdings
shareholdings
object
Stakes this entity holds in others: { holdings: { current: [...] }, summary }. Each holding links another organization by entity_id.
features=publications
publications
array<object>
Official commercial-register publications (date, title, full text).
features=annual_financial_statements__html
annual_financial_statements__html
array<object>
Published annual statements with document_html (rendered HTML), document_type, document_title, document_date, language and year.
