curl -H 'X-API-KEY: YOUR_API_KEY' \
"https://handelsregister.ai/api/v1/fetch-organization?q=17c9e4b000e5dff6fb5f0a44bdcd7eb9&features=financial_kpi&features=balance_sheet_accounts&features=profit_and_loss_account&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="17c9e4b000e5dff6fb5f0a44bdcd7eb9",
features=[
"financial_kpi",
"balance_sheet_accounts",
"profit_and_loss_account",
"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: '17c9e4b000e5dff6fb5f0a44bdcd7eb9',
features: [
'financial_kpi',
'balance_sheet_accounts',
'profit_and_loss_account',
'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: '17c9e4b000e5dff6fb5f0a44bdcd7eb9',
features: [
'financial_kpi',
'balance_sheet_accounts',
'profit_and_loss_account',
'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": [],
"products_and_services": [],
"contact_data": {
"website": "<URL>",
"phone_number": "<phone>",
"email": null
},
"industry_classification": {
"WZ2008": [],
"WZ2025": [
{
"code": "<string>",
"label": "<string>"
}
]
},
"ubos": {
"beneficial_owners": [],
"unresolved_beneficial_owners": [
{
"reason": "<string>",
"entity_id": null,
"name": "<string>",
"legal_form": null,
"address": {
"country": "<ISO country>"
},
"registration": [],
"ownership_percentage": "<float>",
"via": [
{
"depth": "<int>",
"name": "<string>",
"entity_id": "<32-char hex>",
"step_percentage": "<float>"
}
]
}
],
"coverage": {
"resolved_percentage": "<int>",
"unresolved_percentage": "<float>"
}
},
"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>"
}
}
}
]
},
"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": []
}
]
}
]
}
]
}
],
"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>"
}
}
}
],
"past": [
{
"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": "<ISO date>",
"birth_date": null,
"name_parts": {
"given": "<string>",
"family": "<string>",
"maiden": null,
"canonical_name": "<string>",
"previous_names": null
},
"location": {
"home": {
"city": "<string>"
}
}
}
]
},
"shareholdings": {
"holdings": {
"current": [
{
"organization": {
"entity_id": "<32-char hex>",
"name": "<string>",
"status": "<enum: ACTIVE | TERMINATED | DISSOLVED | INSOLVENT>",
"legal_form": "<string>",
"address": {
"house_number": null,
"street": null,
"postal_code": "<string>",
"city": "<string>",
"county": "<string>",
"state": "<string>",
"country": "<ISO country>",
"coordinates": null
},
"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>"
}
},
"profit_and_loss_account": [
{
"year": "<int>",
"profit_and_loss_accounts": [
{
"name": {
"de": "<string>",
"en": "<string>",
"in_report": "<string>"
},
"value": "<float>",
"children": []
}
]
}
],
"financial_kpi": [
{
"active_total": "<float>",
"net_income": "<float>",
"revenue": null,
"material_expenses": null,
"personnel_expenses": null,
"employees": "<int>",
"year": "<int>"
}
],
"annual_financial_statements__html": [
{
"document_type": "<string>",
"document_date": "<ISO date>",
"document_title": "<string>",
"language": "<string>",
"year": "<int>",
"document_html": "<string>"
}
],
"history": [
{
"entity_type": "<string>",
"name": {
"de": "<string>",
"en": "<string>"
},
"description": {
"short": {
"de": "<string>",
"en": "<string>"
}
},
"start_date": "<ISO date>",
"details": {
"value": {
"role": {
"name": "<string>",
"original_name_source": "<string>",
"representation_scheme": [
"<string>"
]
}
},
"linked_entities": {
"person": {
"name": {
"given": "<string>",
"family": "<string>"
}
},
"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.
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.
