GET handelsregister.ai /api/v1/fetch-organization
? q = 7a37dfaf536c4ef5a7ffbf5894de45b0
& features = financial_kpi
& features = balance_sheet_accounts
& features = profit_and_loss_account
& features = related_persons
& features = shareholders
& features = ubos
& features = history
& features = annual_financial_statements__html
curl -H 'X-API-KEY: YOUR_API_KEY' \
"https://handelsregister.ai/api/v1/fetch-organization?q=7a37dfaf536c4ef5a7ffbf5894de45b0&features=financial_kpi&features=balance_sheet_accounts&features=profit_and_loss_account&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="7a37dfaf536c4ef5a7ffbf5894de45b0",
features=[
"financial_kpi",
"balance_sheet_accounts",
"profit_and_loss_account",
"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: '7a37dfaf536c4ef5a7ffbf5894de45b0',
features: [
'financial_kpi',
'balance_sheet_accounts',
'profit_and_loss_account',
'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: '7a37dfaf536c4ef5a7ffbf5894de45b0',
features: [
'financial_kpi',
'balance_sheet_accounts',
'profit_and_loss_account',
'related_persons',
'shareholders',
'ubos',
'history',
'annual_financial_statements__html',
],
});
console.log(organization.name);
})();
JSON preview
{
"entity_id": "7a37dfaf536c4ef5a7ffbf5894de45b0",
"name": "BIM.live UG (haftungsbeschränkt)",
"status": "ACTIVE",
"legal_form": "UG (haftungsbeschränkt)",
"registration_date": "2019-09-13T00:00:00+00:00",
"purpose": "Entwicklung, Wartung, Unterstützung, Betrieb, Beratung und Vertrieb von Computersoftware.",
"address": {
"street": "Am Schlosssee",
"house_number": "4/1",
"postal_code": "88682",
"city": "Salem",
"country": "IND"
},
"registration": {
"register_type": "HRB",
"register_number": "726312",
"court": "Freiburg"
}
}
"representation_scheme" : { … } Unlock the full JSON response
Register to retrieve the full JSON response in the playground. A monthly plan lets you expand every JSON field directly here.
"capital" : { … } Unlock the full JSON response
Register to retrieve the full JSON response in the playground. A monthly plan lets you expand every JSON field directly here.
"contact_data" : { … } Unlock the full JSON response
Register to retrieve the full JSON response in the playground. A monthly plan lets you expand every JSON field directly here.
"industry_classification" : { … } Unlock the full JSON response
Register to retrieve the full JSON response in the playground. A monthly plan lets you expand every JSON field directly here.
"keywords" : [ … ] Unlock the full JSON response
Register to retrieve the full JSON response in the playground. A monthly plan lets you expand every JSON field directly here.
"products_and_services" : [ … ] Unlock the full JSON response
Register to retrieve the full JSON response in the playground. A monthly plan lets you expand every JSON field directly here.
"history" : [ … ] Unlock the full JSON response
Register to retrieve the full JSON response in the playground. A monthly plan lets you expand every JSON field directly here.
"financial_kpi" : [ … ] Unlock the full JSON response
Register to retrieve the full JSON response in the playground. A monthly plan lets you expand every JSON field directly here.
"related_persons" : { … } Unlock the full JSON response
Register to retrieve the full JSON response in the playground. A monthly plan lets you expand every JSON field directly here.
"shareholders" : { … } Unlock the full JSON response
Register to retrieve the full JSON response in the playground. A monthly plan lets you expand every JSON field directly here.
"ubos" : { … } Unlock the full JSON response
Register to retrieve the full JSON response in the playground. A monthly plan lets you expand every JSON field directly here.
"balance_sheet_accounts" : [ … ] Unlock the full JSON response
Register to retrieve the full JSON response in the playground. A monthly plan lets you expand every JSON field directly here.
"profit_and_loss_account" : [ … ] Unlock the full JSON response
Register to retrieve the full JSON response in the playground. A monthly plan lets you expand every JSON field directly here.
"annual_financial_statements__html" : [ … ] Unlock the full JSON response
Register to retrieve the full JSON response in the playground. A monthly plan lets you expand every JSON field directly here.
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. Every year names the source of its figures in _provenance: statement_type (Jahresabschluss = annual accounts, Bilanz = balance sheet only, Konzernabschluss = consolidated accounts; null for market data), period_start and period_end of the fiscal year, plus exempt_subsidiary and parent_organization ({ entity_id, name }). With exempt_subsidiary: true the company published the consolidated accounts of parent_organization instead of accounts of its own, so that year's figures cover the whole group.
features=balance_sheet_accounts
balance_sheet_accounts
array<object>
Per fiscal year: hierarchical balance-sheet line items from the published statement, with _provenance naming the source of the figures (fields as in financial_kpi). For energy utilities, Max accounts also receive activity_statements through the API: the balance sheets of the activity statements (section 6b EnWG), one per regulated activity such as electricity or gas distribution; together they do not add up to the company's balance sheet.
features=profit_and_loss_account
profit_and_loss_account
array<object>
Per fiscal year: hierarchical profit-and-loss line items, with _provenance naming the source of the figures (fields as in financial_kpi). For energy utilities, Max accounts also receive activity_statements through the API: the profit and loss accounts of the activity statements (section 6b EnWG), one per regulated activity.
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.
