fetch-organization
Endpoints
GET

/v1/fetch-organization

5–110 credits • 60/min

Fetch the full profile of a German company: core registry data plus optional features like financials, management, shareholders, or news.

Parameters

Name Type Required Description
api_key string Conditional* Your API key. Only required if you use neither the x-api-key header nor a Bearer token.
q string REQUIRED Company name, registration number, search query, or an entity_id from /v1/search-organizations. The entity_id is the most reliable way to reach a specific company — company names are not unique.
feature string optional Extra data feature to include. Repeatable (feature=a&feature=b), or pass features= comma-separated (features=a,b). All features are listed in the table below.
ai_search string optional Enables AI mode (+20 credits). The only accepted value: on-default — omit the parameter to leave it off.
realtime_mode string optional Enables realtime mode for live data straight from the commercial register (+10 credits). The only accepted value: handelsregister-default — omit the parameter to leave it off.

Available Features

financial_kpi 1 credit
balance_sheet_accounts 3 credits
profit_and_loss_account 3 credits
related_persons 2 credits
publications 1 credit
news 10 credits
insolvency_publications 5 credits
annual_financial_statements 5 credits
annual_financial_statements__html 5 credits
shareholders Beta
5 credits
ubos Beta
10 credits
shareholdings Beta
5 credits
mergers_and_acquisitions Beta
20 credits
network Beta Pro / Max
25 Credits
website_content AI
0 credits
How billing works
  • Every request has a base price of 5 credits; each requested feature adds its price from the table below.
  • Features are only charged when they actually return data. A feature that comes back empty — say, insolvency publications for a company that never had proceedings — costs nothing. The request_credit_cost field in the meta object always shows what was really charged.
  • AI mode (ai_search=on-default) adds 20 credits. The surcharge also applies when the request itself fails — the AI processing runs regardless.
  • Realtime mode (realtime_mode=handelsregister-default) adds 10 credits, charged only when the live register fetch succeeds. It cannot be combined with the related_persons and publications features.

Example Request

curl -X GET 'https://handelsregister.ai/api/v1/fetch-organization?q=BMW%20AG&feature=financial_kpi&feature=related_persons&feature=publications&feature=website_content&ai_search=on-default' \
     -H 'x-api-key: YOUR_API_KEY'

Example Response

{
  "entity_id": "add84642a957b08a3f252c69c9d063de",
  "name": "Polyden-Folienfabrik GmbH",
  "status": "TERMINATED",
  "legal_form": "GmbH",
  "purpose": "Herstellung von Folien...",
  "registration_date": "1978-02-23T00:00:00",
  "address": {
    "house_number": "38",
    "street": "Ansbacher Straße",
    "postal_code": "91560",
    "city": "Heilsbronn",
    "coordinates": {
      "latitude": 49.33438,
      "longitude": 10.78262
    }
  },
  "registration": {
    "court": "Ansbach",
    "register_type": "HRB",
    "register_number": "405"
  },
  "contact_data": {
    "website": "https://www.polyden.de",
    "phone_number": "+49 9872 808 0"
  },
  "representation_scheme": {
    "current": ["Ist nur ein Geschäftsführer bestellt, so vertritt er die Gesellschaft allein. ..."],
    "history": [
      {
        "value": ["Ist nur ein Geschäftsführer bestellt, ..."],
        "effective_from": "1995-11-10",
        "effective_to": null
      }
    ]
  },
  "capital": {
    "current": {"amount": 3297000.0, "currency": "EUR", "kind": "GRUNDKAPITAL"},
    "history": [
      {
        "value": {"amount": 3132000.0, "currency": "EUR", "kind": "GRUNDKAPITAL"},
        "effective_from": "2017-01-17",
        "effective_to": "2021-06-01"
      },
      {
        "value": {
          "amount": 3297000.0,
          "currency": "EUR",
          "kind": "GRUNDKAPITAL",
          "change_amount": {"amount": 165000.0, "currency": "EUR"}
        },
        "effective_from": "2021-06-01",
        "effective_to": null
      }
    ]
  },
  "financial_kpi": [
    {
      "year": 2022,
      "revenue": 41855558.25,
      "net_income": -19668989.99,
      "employees": 208
    }
  ],
  "related_persons": {
    "current": [
      {
        "name": "Knut Neumann",
        "role": {
          "en": {"long": "Managing Director"},
          "de": {"long": "Geschäftsführer"}
        },
        "start_date": "2019-06-03",
        "role_representation_scheme": {
          "current": ["einzelvertretungsberechtigt; mit der Befugnis, ..."],
          "history": ["..."]
        },
        "organization_representation_scheme": {"...": "..."}
      }
    ]
  },
  "publications": [...],
  "news": [
    {
      "title": "Company News Title",
      "source": "News Source",
      "publication_date": "2023-08-08"
    }
  ],
  "meta": {
    "request_credit_cost": 29,
    "credits_remaining": 73841334
  }
}

Response Structure Details

Core Company Data

Always included: entity_id, name, status, legal_form, address, registration, contact_data, purpose, keywords, products_and_services, representation_scheme, capital

capital — registered capital and its history

Registered capital as { current, history }. current is a money object with amount, currency and kind (STAMMKAPITAL, GRUNDKAPITAL, HAFTSUMME, GENEHMIGTES_KAPITAL, BEDINGTES_KAPITAL, VARIABLES_KAPITAL — treat the list as open). history holds every recorded version with effective_from and effective_to (null = still in force). A history entry may carry change_amount, which is the amount stated in the register entry: it is unsigned and does not always equal the difference between two consecutive amounts, so derive increases and decreases by comparing the amounts themselves. Entities without registered capital, such as partnerships, return {"current": null, "history": []}. Included in the 5-credit base price — no feature parameter required.

financial_kpi

Yearly financial metrics as an array (revenue, net income, employees, and more) spanning multiple years.

balance_sheet_accounts

Balance sheet positions as a hierarchy: assets and liabilities broken down, one entry per fiscal year.

profit_and_loss_account

Detailed P&L per fiscal year, breaking down revenue, expenses, and profit.

related_persons

Current and former directors and officers with names, roles, tenures, and powers of representation — organization_representation_scheme and role_representation_scheme, each with history.

publications

Official register publications, announcements, and structured company events. Note: returned under the response key "history".

news

News articles as an array with title, source, publication date, and URL.

insolvency_publications

Insolvency court publications with dates, case numbers, and event details.

annual_financial_statements

Complete annual financial statements as Markdown, including metadata.

annual_financial_statements__html

Complete annual financial statements as HTML, including metadata.

shareholders Beta

Shareholder list with ownership percentages and roles, including historical lists (history). Charged only when the current list contains at least one entry.

ubos Beta

Ultimate beneficial owners (UBOs) with ownership percentages — resolved and unresolved owners plus coverage metrics.

shareholdings Beta

This company's holdings in other entities with share, contribution, and as-of date.

mergers_and_acquisitions Beta

M&A transactions (mergers, splits, enterprise agreements) with counterparties, roles, register references, control relationships, and a summary.

network Beta Pro / Max

The relationship network of a company: connections to related companies and persons as a graph. Requires a Pro or Max plan; no credits are charged when no network data is returned.

website_content

The company's website as structured Markdown, optimized for LLMs (AI mode only, 0 credits).

financial_kpi: fields by plan

Which yearly figures the response contains depends on your plan: every plan receives the base figures. On Pro and Max, the response additionally includes extended balance-sheet and income-statement figures — at the unchanged price of 1 credit.

Included in every plan

year employees active_total net_income revenue material_expenses personnel_expenses

Additional fields Pro / Max

Company profile

company_size_by_employees company_size_by_assets company_size_by_revenue revenue_per_employee net_income_per_employee

Income statement

other_operating_income material_expenses_goods material_expenses_services wages_salaries social_expenses pension_costs depreciation_amortization depreciation_amortization_operating write_downs_financial_assets_and_securities other_operating_expenses selling_expenses admin_expenses sga opex_core gross_profit ebitda ebit ebt income_taxes other_taxes income_after_taxes interest_income interest_expense finance_income finance_income_from_affiliates

Balance sheet

assets_total fixed_assets_total current_assets_total inventory_total receivables_total trade_receivables intragroup_receivables securities_current_total cash_and_equivalents ppe_total land_and_buildings intangible_assets goodwill long_term_financial_assets prepaid_expenses equity_total capital_reserves revenue_reserves profit_loss_carried_forward tangible_equity liabilities_total provisions_total pension_provisions other_provisions trade_payables intragroup_payables liabilities_to_affiliated_companies other_liabilities deferred_income bank_debt bonds

Working capital & debt

operating_working_capital net_working_capital_strict net_working_capital_approx interest_bearing_debt_strict interest_bearing_debt_broad net_debt_narrow net_debt_broad

Ratios

equity_ratio tangible_equity_ratio debt_to_equity debt_to_assets cash_to_assets cash_to_liabilities receivables_to_assets inventory_to_assets ppe_to_assets intangible_to_assets goodwill_to_assets intangible_to_equity gross_margin ebitda_margin ebit_margin net_margin material_intensity personnel_intensity sga_ratio opex_ratio interest_coverage effective_tax_rate capitalized_own_work_ratio inventory_change_ratio finance_to_ebt_ratio

Source

source_statement_date source_statement_type

Feature Response Examples

Shortened excerpts from real responses, showing the JSON shape each feature adds (arrays truncated with "..."):

financial_kpi 
"financial_kpi": [
  {
    "year": 2021,
    "revenue": 111239000000,
    "net_income": 12382000000,
    "active_total": 229527000000,
    "material_expenses": null,
    "personnel_expenses": null
  },
  "..."
]
network 
"network": {
  "depth": 2,
  "nodes": [
    { "node_id": "9dffc318...", "entity_id": "9dffc318...", "type": "ORGANIZATION",
      "name": "Beispielwerk Analytics GmbH", "depth": 0, "is_root": true },
    { "node_id": "c92a5b9a...", "entity_id": "c92a5b9a...", "type": "PERSON",
      "name": "Nina Weidmann", "depth": 1, "is_root": false },
    "..."
  ],
  "connections": [
    { "source": { "node_id": "c92a5b9a...", "type": "PERSON", "name": "Nina Weidmann" },
      "target": { "node_id": "9dffc318...", "type": "ORGANIZATION", "name": "Beispielwerk Analytics GmbH" },
      "connection_type": "ROLE", "label": "MANAGING_DIRECTOR",
      "role": { "en": { "long": "Managing Director", "short": "MD" },
                "de": { "long": "Geschaeftsfuehrer", "short": "GF" } },
      "start_date": "2020-06-01", "end_date": null, "is_current": true, "depth": 1 },
    "..."
  ]
}
balance_sheet_accounts 
"balance_sheet_accounts": [
  {
    "year": 2024,
    "balance_sheet_accounts": [
      {
        "name": {"de": "Aktivseite", "en": "Assets", "in_report": "Aktiva"},
        "value": 267732000000,
        "children": [
          {
            "name": {"de": "Aktuelle Anlagen", "en": "Current Assets", "in_report": "..."},
            "value": 96387000000,
            "children": ["..."]
          },
          "..."
        ]
      },
      "..."
    ]
  },
  "..."
]
profit_and_loss_account 
"profit_and_loss_account": [
  {
    "year": 2024,
    "profit_and_loss_accounts": [
      {
        "name": {"de": "Umsatzerlöse", "en": "Revenue", "in_report": "Umsatzerlöse"},
        "value": 142380000000,
        "children": []
      },
      "..."
    ]
  },
  "..."
]
related_persons 
"related_persons": {
  "current": [
    {
      "entity_id": "80fd27f39a5c075f88d99f3e126442e0",
      "name": "Milan Dr. Nedeljkovic",
      "label": "BOARD_CHAIR",
      "role": {
        "en": {"long": "Board Chair", "short": "Board"},
        "de": {"long": "Vorsitzender des Vorstands", "short": "Vorstand"}
      },
      "start_date": "2026-05-15",
      "end_date": null,
      "birth_date": "1969-03-11",
      "name_parts": {"given": "Milan", "family": "Nedeljkovic", "canonical_name": "Dr. Nedeljkovic, Milan"},
      "titles": ["Dr."],
      "location": {"home": {"city": "Leipzig"}},
      "organization_representation_scheme": {
        "current": ["Ist nur ein Vorstandsmitglied bestellt, so vertritt es die Gesellschaft allein. ..."],
        "history": [
          {"value": ["..."], "effective_from": "2004-02-03", "effective_to": "2009-08-25"},
          "..."
        ]
      },
      "role_representation_scheme": {
        "current": ["einzelvertretungsberechtigt; mit der Befugnis, im Namen der Gesellschaft mit sich als Vertreter eines Dritten Rechtsgeschäfte abzuschließen."],
        "history": [
          {"value": ["..."], "effective_from": "2021-08-04", "effective_to": null}
        ]
      }
    },
    "..."
  ],
  "past": ["... (past roles carry the scheme under \"latest\" instead of \"current\")"]
}
publications → response key "history" 
"history": [
  {
    "entity_type": "EVENT",
    "name": {"en": "Change of legal form", "de": "Änderung der Rechtsform"},
    "description": {
      "short": {"en": "The company changed its legal form", "de": "Die Rechtsform wurde geändert"}
    },
    "start_date": "2018-09-28T00:00:00",
    "details": {
      "value": "Gesellschaft mit beschränkter Haftung",
      "linked_entities": {"organization": {"name": "OroraTech GmbH"}}
    }
  },
  "..."
]
insolvency_publications 
"insolvency_publications": [
  {
    "publication_date": "2026-05-05T00:00:00+00:00",
    "insolvency_id": "10 IN 56/26",
    "court_city": "Wiesbaden",
    "entity_name": "Teltec AG",
    "seat": "Mainz-Kastel",
    "register": "Wiesbaden, HRB 27296",
    "publication_label": "Eröffnung",
    "event_notice": "Am 05.05.2026 wurde eine Insolvenzbekanntmachung (Eröffnung) ..."
  },
  "..."
]
news 
"news": [
  {
    "id": "c204cffdcef222e543ae5c16",
    "title": "PTA-CMS: Bayerische Motoren Werke Aktiengesellschaft: ...",
    "source": "TradingView",
    "publication_date": "2026-07-20",
    "url": "https://de.tradingview.com/news/..."
  },
  "..."
]
annual_financial_statements 
"annual_financial_statements": [
  {
    "document_type": "Jahresabschluss",
    "document_date": "2026-04-16",
    "document_title": "Jahresabschluss zum Geschäftsjahr vom 01.01.2025 bis zum 31.12.2025",
    "language": "Deutsch",
    "year": 2025,
    "document_md": "| Bayerische Motoren Werke Aktiengesellschaft ... (full report as Markdown)"
  },
  "..."
]
shareholders 
"shareholders": {
  "total_capital": {"amount": 125193, "currency": "EUR"},
  "entries": [
    {
      "shareholder": {
        "entity_id": "960bf144c3eda5c99e3caab086644da1",
        "first_name": "Ingo",
        "last_name": "Baumann",
        "birth_date": "1971-02-27",
        "address": "Köln-Neustadt/Nord"
      },
      "contribution": {"amount": 566, "currency": "EUR"},
      "contribution_ratio": 0.00452,
      "role": {
        "label": "SHAREHOLDER",
        "en": {"long": "Shareholder", "short": "Shareholder"},
        "de": {"long": "Gesellschafter", "short": "Gesellschafter"}
      }
    },
    "..."
  ],
  "history": {
    "current_as_of": "2025-07-04",
    "past": [
      {
        "as_of": "2025-06-16",
        "data": {
          "total_capital": {"amount": 125193, "currency": "EUR"},
          "shareholders": ["... (same entry shape as \"entries\")"]
        }
      },
      "..."
    ]
  }
}
ubos 
"ubos": {
  "beneficial_owners": [
    {
      "person": {
        "entity_id": "99e133f16ed20bbe874dfb08f87f2e54",
        "name": "Thomas Grübler",
        "birth_date": "1991-09-20",
        "name_parts": {"given": "Thomas", "family": "Grübler", "canonical_name": "Grübler, Thomas"},
        "location": {"home": {"city": "München", "state": "Bayern", "country": "DEU"}}
      },
      "ownership_percentage": 6.3,
      "paths": [
        {
          "percentage": 6.3,
          "via": [{"depth": 1, "name": "Gruebler Ventures UG (haftungsbeschränkt)", "entity_id": "...", "step_percentage": 6.3}]
        }
      ]
    },
    "..."
  ],
  "unresolved_beneficial_owners": [
    {
      "reason": "no_further_shareholder_data",
      "entity_id": "0aedd216ca3a22f0204667d552fe0c82",
      "name": "ConActivity KG",
      "legal_form": "KG",
      "ownership_percentage": 10.53,
      "registration": {"court": "Frankfurt am Main", "register_type": "HRA", "register_number": "30787"},
      "via": []
    },
    "..."
  ]
}
shareholdings 
"shareholdings": {
  "holdings": {
    "current": [
      {
        "organization": {
          "entity_id": "c3b23cd03d57d302b938b74ce7fbc5e3",
          "name": "BMW M GmbH Gesellschaft für individuelle Automobile",
          "status": "ACTIVE",
          "legal_form": "GmbH",
          "address": {"city": "München", "state": "Bayern", "country": "DEU", "...": "..."},
          "registration": {"court": "München", "register_type": "HRB", "register_number": "44621"}
        },
        "ownership": {
          "percentage": 100,
          "contribution": {"amount": 50000, "currency": "DEM"}
        },
        "as_of": "2020-12-21"
      },
      "..."
    ]
  },
  "summary": {"total_current": 15}
}
mergers_and_acquisitions 
"mergers_and_acquisitions": {
  "transactions": [
    {
      "id": "9254b90f65271482a0cd4babd80814b6",
      "headline": {
        "en": "Result transfer agreement with Avemio AG concluded",
        "de": "Ergebnisabführungsvertrag mit Avemio AG geschlossen"
      },
      "type": {
        "category": "ENTERPRISE_AGREEMENT",
        "event_type": "GROUP.ENTERPRISE_AGREEMENT",
        "name": {"en": "Enterprise agreement", "de": "Unternehmensvertrag"}
      },
      "kind": {
        "label": "RESULT_TRANSFER",
        "name": {"en": "Result transfer agreement", "de": "Ergebnisabführungsvertrag"}
      },
      "role": {
        "label": "CONTROLLED",
        "en": {"long": "Controlled company", "short": "Controlled"},
        "de": {"long": "Beherrschtes Unternehmen", "short": "Beherrscht"}
      },
      "phase": "REGISTERED",
      "date": "2023-10-11",
      "dates": {"registered_at": "2023-10-11", "agreement_date": null, "resolution_date": null},
      "counterparties": [
        {
          "entity_id": "176ad1d2790f8150ac03f6644e52f02c",
          "name": "Avemio AG",
          "seat": "Düsseldorf",
          "registration": {"court": "Amtsgericht Düsseldorf", "register_type": "HRB", "register_number": "82980"},
          "role": {"label": "CONTROLLING", "en": {"short": "Controlling"}, "de": {"short": "Herrschend"}}
        }
      ],
      "description": "Ergebnisabführungsvertrag mit der Avemio AG abgeschlossen.",
      "register_entries": [{"registered_at": "2023-10-11", "description": "..."}]
    },
    "..."
  ],
  "succession": null,
  "control": {
    "controlled_by": [
      {
        "counterparty": {"entity_id": "...", "name": "Avemio AG", "role": {"label": "CONTROLLING", "...": "..."}},
        "via": {"label": "RESULT_TRANSFER", "name": {"en": "Result transfer agreement", "de": "Ergebnisabführungsvertrag"}},
        "loss_absorption_obligation": true,
        "since": "2023-10-11",
        "transaction_ids": ["9254b90f65271482a0cd4babd80814b6"]
      }
    ],
    "controls": [],
    "former": []
  },
  "summary": {
    "total_transactions": 7,
    "by_category": {
      "ENTERPRISE_AGREEMENT": {"count": 5, "name": {"en": "Enterprise agreement", "de": "Unternehmensvertrag"}},
      "MERGER": {"count": 1, "name": {"en": "Merger", "de": "Verschmelzung"}}
    },
    "first_date": "2013-09-03",
    "last_date": "2024-08-14"
  }
}
website_content 
"website_content": "# Company Name\n\nStructured Markdown extracted from the company website ..."