🔍 Handelsregister Python SDK

A modern Python client for the Handelsregister.ai API. Structured, reliable, and fast access to the German commercial register (Handelsregister): company master data, financials, management, shareholders, UBOs, person profiles, and official PDF documents.

✨ Features

• 🔎 Company lookup — fetch-organization with configurable feature flags
• 👤 Person profiles — fetch-person (Handelsregister roles + web data)
• 🗂️ Search — query or filters-only search with geo, registry, size, and financial filters
• 📊 Financial data — KPIs, balance sheet, P&L, full annual reports (MD/HTML)
• 👥 Management — current and past related persons with roles
• 🤝 Shareholders, UBOs, shareholdings — who owns the company, who the company owns
• 🔀 Mergers & acquisitions — transactions, succession, enterprise agreements, and control relationships
• ✍️ Representation schemes — current and historical company- and person-role representation rules
• 📰 News, publications, insolvency publications
• 🌐 Website content — structured Markdown, optimized for LLMs
• 📄 Document downloads — Gesellschafterliste, Gesellschaftsvertrag, AD/CD PDFs, and SI XML
• 🔐 Auth — x-api-key header or Bearer token, plus token management
• 📚 Batch enrichment — resilient CSV/JSON/XLSX enrichment with snapshots
• ⚡ Live mode — opt-in realtime lookups against the Handelsregister

📦 Installation

pip install handelsregister

🔑 Authentication

You can authenticate in two ways:

API key (recommended for server-to-server):

export HANDELSREGISTER_API_KEY=your_api_key_here

from handelsregister import Handelsregister

client = Handelsregister(api_key="your_api_key_here")

Bearer token (fine-grained control, expiration):

export HANDELSREGISTER_BEARER_TOKEN=your_token_here

client = Handelsregister(bearer_token="your_token_here")

When both are provided, the bearer token wins.

🚀 Quick Start

Company lookup

from handelsregister import Handelsregister

client = Handelsregister()

result = client.fetch_organization(
    q="KONUX GmbH München",
    features=["related_persons", "financial_kpi", "shareholders"],
    ai_search="on-default",          # optional: enable AI search
    # realtime_mode="handelsregister-default",  # +10 credits for live data
)

print(result["name"], result["registration"]["register_number"])

Object-oriented Company interface

from handelsregister import Company

company = Company(
    "OroraTech GmbH München",
    features=[
        "related_persons",
        "financial_kpi",
        "balance_sheet_accounts",
        "shareholders",
        "ubos",
        "shareholdings",
        "mergers_and_acquisitions",
        "annual_financial_statements",
        "news",
    ],
)

print(company.name, company.is_active)
print(company.formatted_address)

# Management
for person in company.current_related_persons:
    print(person["name"], "-", person["role"]["en"]["long"])

# Shareholders (who owns the company)
for entry in company.shareholders.entries:
    print(entry.display_name, entry.percentage)

# Ultimate beneficial owners
for ubo in company.ubos.resolved:
    print(ubo.name, ubo.percentage)

# Outbound shareholdings (what the company owns)
for holding in company.shareholdings.current:
    print(holding.organization_name, holding.percentage)

# Company- and person-level representation rules
for rule in company.representation_scheme.active:
    print(rule)

for director in company.related_person_entries.current:
    print(director.display_name, director.role_representation_scheme.active)

# M&A transactions
for transaction in company.mergers_and_acquisitions.transactions:
    print(transaction.date, transaction.headline_text("en"))

# News
for article in company.news:
    print(article["publication_date"], article["title"])

Person profiles

The /v1/fetch-person endpoint merges Handelsregister records with public web data. ai_search is always on for this endpoint (the 15-credit base cost includes the AI enrichment). organization_q is required to disambiguate common names.

from handelsregister import Person

person = Person(
    person_q="Max Mustermann",
    organization_q="Beispielwerk Analytics GmbH",
    features=["shareholdings"],  # +5 credits, only if data is returned
)

print(person.canonical_name, "-", person.home_city)
print(person.bio)

for role in person.handelsregister_roles:
    print(role["name"], role["label"], role.get("start_date"), role.get("end_date"))

for holding in person.shareholdings.current:
    print(holding.organization_name, holding.percentage, holding.as_of)

Search

from handelsregister import Handelsregister, RangeFilter, SearchFilters

client = Handelsregister()

page = client.search_organizations(
    limit=10,
    skip=0,
    filters=SearchFilters(
        city="München",
        legal_form_code=["GmbH", "AG"],
        active=True,
        pl_revenue=RangeFilter(gte=1_000_000, lte=5_000_000),
    ),
    ai_mode="on-default",  # optional; makes the search cost 5 credits
)

print(page["total"])
for item in page["results"]:
    print(item["name"], item["registration"]["register_number"])

q may be omitted when at least one filter is supplied. filters may also be an ordinary dictionary. Supported keys cover registration dates, legal forms, WZ/NACE industries, active status, postal code/city/state, radius search, register court/type/number, company size, employee ranges, seven balance-sheet ranges, and revenue/net-income/EBIT ranges. Range dictionaries use {"gte": minimum, "lte": maximum}; either bound may be omitted. The SDK automatically translates these documented flat financial keys to the live API's nested financial_filters wire format.

📄 Document Downloads

from handelsregister import Handelsregister, Company

client = Handelsregister()

# Get the company's entity_id
result = client.fetch_organization(q="KONUX GmbH München")
entity_id = result["entity_id"]

# Download documents directly from the client
client.fetch_document(
    company_id=entity_id,
    document_type="shareholders_list",       # Gesellschafterliste
    output_file="konux_shareholders.pdf",
)

client.fetch_document(
    company_id=entity_id,
    document_type="articles_of_association", # Gesellschaftsvertrag / Satzung
    output_file="konux_articles.pdf",
)

client.fetch_document(
    company_id=entity_id,
    document_type="AD",                      # Aktueller Ausdruck
    output_file="konux_current.pdf",
)

pdf_bytes = client.fetch_document(
    company_id=entity_id,
    document_type="CD",                      # Chronologischer Ausdruck
)

xml_bytes = client.fetch_document(
    company_id=entity_id,
    document_type="SI",                      # Structured information (XML)
    output_file="konux_structured.xml",
)

# Or via the Company helper
company = Company("OroraTech GmbH München")
company.fetch_document(
    document_type="shareholders_list",
    output_file="ororatech_shareholders.pdf",
)

Available document types

🔐 Bearer Token Management

If you prefer managing bearer tokens over sharing an API key:

client = Handelsregister(api_key="your_api_key_here")

# Create a new token
created = client.create_token(
    token_name="My Application",
    abilities=["*"],
    expires_at="2026-01-01 00:00:00",
)
print(created)

# List / revoke
tokens = client.list_tokens()
client.revoke_token(token_id=42)
client.revoke_all_tokens()

📊 Data Enrichment

Enrich a CSV/JSON/XLSX file of companies with Handelsregister data. Intermediate snapshots let you resume long-running jobs.

from handelsregister import Handelsregister

client = Handelsregister()

client.enrich(
    file_path="companies.csv",
    input_type="csv",
    query_properties={
        "name": "company_name",   # map 'company_name' column to query
        "location": "city",       # map 'city' column to query
    },
    snapshot_dir="snapshots",
    params={
        "features": ["related_persons", "financial_kpi", "ubos"],
        "ai_search": "on-default",
    },
    output_format="csv",
)

There is also a DataFrame convenience:

import pandas as pd
from handelsregister import Handelsregister

client = Handelsregister()
df = pd.read_csv("companies.csv")
enriched = client.enrich_dataframe(
    df,
    query_properties={"name": "company_name", "location": "city"},
    params={"features": ["financial_kpi"]},
)

🖥️ Command Line Interface

Installing the package exposes the handelsregister CLI. If the optional rich dependency is installed, commands render colorful tables.

# Company lookup (defaults: all standard features + AI search)
$ handelsregister fetch "KONUX GmbH München"

# Raw JSON
$ handelsregister fetch json "KONUX GmbH München"

# Opt-in to realtime mode for live register data
$ handelsregister fetch "KONUX GmbH München" --realtime-mode handelsregister-default

# Person profile
$ handelsregister person \
    --person "Max Mustermann" \
    --organization "Beispielwerk Analytics GmbH" \
    --feature shareholdings

# Search
$ handelsregister search "tech" --postal-code 80992 --limit 20

# Filters-only search (JSON or repeated key=value)
$ handelsregister search \
    --filters '{"city":"München","pl_revenue":{"gte":1000000}}' \
    --ai-mode on-default

# Enrich a file
$ handelsregister enrich companies.csv --input csv \
    --query-properties name=company_name location=city \
    --snapshot-dir snapshots \
    --feature related_persons --feature financial_kpi \
    --output-format csv

# Download documents
$ handelsregister document "KONUX GmbH München" \
    --type shareholders_list --output konux_shareholders.pdf

$ handelsregister document "KONUX GmbH München" \
    --type articles_of_association --output konux_articles.pdf

$ handelsregister document "KONUX GmbH München" \
    --type SI --output konux_structured.xml

📋 Available Features (fetch-organization)

realtime_mode="handelsregister-default" forces a live Handelsregister lookup (+10 credits), independent of the feature flags above. It cannot be combined with related_persons or publications.

The base response includes representation_scheme. Entries in related_persons may include both organization_representation_scheme and role_representation_scheme. Historical person records can expose their last applicable rules as latest; the SDK normalizes current and latest through the .active property.

🔍 Company properties

# Basic
company.name
company.entity_id
company.status
company.is_active
company.purpose
company.representation_scheme          # RepresentationScheme

# Registration
company.registration_number
company.registration_court
company.registration_type
company.registration_date

# Contact & address
company.address
company.formatted_address
company.coordinates
company.website
company.phone_number
company.email

# Financial
company.financial_kpi
company.financial_years
company.balance_sheet_accounts
company.profit_and_loss_account
company.annual_financial_statements
company.annual_financial_statements_html
company.get_financial_kpi_for_year(2023)
company.get_balance_sheet_for_year(2023)
company.get_profit_and_loss_for_year(2023)
company.get_annual_financial_statement_for_year(2023)  # Markdown
company.get_annual_financial_statement_for_year(2023, html=True)

# People & ownership
company.current_related_persons
company.past_related_persons
company.get_related_persons_by_role("MANAGING_DIRECTOR")
company.related_person_entries         # typed persons + representation schemes
company.shareholders           # ShareholderInfo
company.ubos                   # UBOInfo
company.shareholdings          # ShareholdingsInfo
company.mergers_and_acquisitions  # MergersAndAcquisitions

# News & publications
company.publications
company.insolvency_publications
company.news
company.website_content

👤 Person properties

person.entity_id
person.name
person.canonical_name
person.given_name
person.family_name
person.maiden_name
person.previous_names
person.birth_date
person.home_city
person.home_location
person.bio
person.expertise
person.emails
person.phones
person.linkedin
person.github
person.other_profiles

person.handelsregister_roles
person.current_handelsregister_roles
person.get_handelsregister_roles_by_label("MANAGING_DIRECTOR")
person.affiliations

person.shareholdings           # PersonShareholdings (requires feature flag)

Error handling

All API exceptions inherit from HandelsregisterError. Documented HTTP responses are mapped to RequestValidationError (HTTP 400/422), AuthenticationError, InsufficientCreditsError, ForbiddenError / SubscriptionRequiredError, NotFoundError, RateLimitError, and RequestTimeoutError / ServerError. API exceptions preserve status_code, the raw JSON payload, and billing metadata through .meta.

Only network failures, HTTP 408/429, and server errors are retried. When supplied, the API's Retry-After header controls the delay.

📜 License

MIT — see LICENSE.