Endpoints

GET

/v1/search-organizations

1 credit • 60/min

Search and filter German companies, with pagination. At least one of q or filters is required.

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	Conditional*	Search term with 2 to 500 characters. You may omit q when filters contains at least one criterion; otherwise q is required.
skip	integer	optional	Number of results to skip (default: 0).
limit	integer	optional	Results per page (default: 10, max: 30).
filters	string (JSON object)	optional	A URL-encoded JSON object. The reference below covers the filters available in the current main search playground and shows their required nesting.
sort	string	optional	Sort field: relevance (default), registration_date, financial_year, revenue, profit, employees, total_assets, equity, liabilities, cash, equity_ratio, share_capital, last_activity, largest_share_ratio, management_size, md_oldest_birth_date, md_youngest_birth_date, fb_entity_id or distance (requires the geo filter). An unknown field is answered with 422.
order	string	optional	Sort direction: asc or desc. Each sort field has a sensible default.
match_context	boolean	optional	match_context=1 adds _match_context to every hit: the entries that satisfied the register-derived filters. Without it the response stays lean.

Filters

All filters are optional. Range filters accept {"gte": min, "lte": max} — either bound may be omitted — and are nested under a financial_filters object, e.g. {"financial_filters":{"pl_revenue":{"gte":1000000}}}.

Example URL

GET /v1/search-organizations?limit=10&filters={"city":"München","industry_code":["62.10.1","62.10.3"],"industry_scheme":"WZ2025","financial_filters":{"pl_revenue":{"gte":1000000}}}

Shown unencoded for readability — in real requests, URL-encode the filters value.

Identity & Registration

registration_date_from date: Earliest registration date (ISO 8601, YYYY-MM-DD).
registration_date_to date: Latest registration date (ISO 8601, YYYY-MM-DD).
legal_form_code string: Exact legal-form code, for example GmbH, AG, e.V. or UG (haftungsbeschränkt). Send one string; arrays are rejected.
industry_code string / array: NACE/WZ industry code. A single code or an array of codes — an array matches companies in any of them, e.g. ["62.10.1","62.10.3"].
industry_scheme string: Classification scheme paired with industry_code. Default: WZ2025.
active boolean: true = active companies only, false = inactive only. Omit for both.
status enum: Exact register status: ACTIVE, INACTIVE, TERMINATED, DISSOLVED or INSOLVENT. Values are case-sensitive. Use status for a specific lifecycle state; active is the simpler boolean alternative.
legal_form_liability_type enum: Liability model: limited, unlimited or mixed.

Location

postal_code string: German 5-digit postal code (PLZ).
city string: City name.
state string: German federal state (e.g. Bayern, Hessen).
location_coordinates object {lat, lon}: Center of the radius search in WGS84 decimal degrees, as {"lat":48.137,"lon":11.576}. Latitude must be between -90 and 90, longitude between -180 and 180. Send this together with location_max_distance_km.
location_max_distance_km number: Search radius in kilometres (1–100). Send this together with location_coordinates.

Court & Register

registration_type string / array: Register type: HRA, HRB, GnR, PR or VR. Single value or array.
registration_authority_name string: Register court (e.g. München).
registration_number string: Register number (e.g. HRB 12345).

Size & Employees

company_size_category enum: Size bucket: micro, small, medium or large.
emp_count range: Employee count range.

Balance Sheet

bs_assets_total EUR range: Total assets / Bilanzsumme, in EUR.
bs_equity_total EUR range: Equity / Eigenkapital, in EUR.
bs_liabilities_total EUR range: Total liabilities / Verbindlichkeiten, in EUR.
bs_cash_and_equivalents EUR range: Cash & cash equivalents, in EUR.
bs_cash_to_liabilities decimal range: Liquidity ratio (cash ÷ liabilities), decimal.
bs_equity_ratio ratio (0–1): Equity ratio (equity ÷ total assets), decimal 0–1.
bs_debt_to_assets ratio (0–1): Debt-to-assets ratio, decimal 0–1.

Profit & Loss

pl_revenue EUR range: Annual revenue / Umsatz, in EUR.
pl_net_income EUR range: Net income / Jahresüberschuss, in EUR.
pl_ebit EUR range: EBIT / operating profit, in EUR.

Register-Derived Filters (Ownership, Management, Insolvency)

ownership_filters conditions: Ownership and succession criteria used by the playground: structure, owner_managed, likely_family_owned, largest_share_ratio (0–1), oldest_owner_birth_date and youngest_owner_birth_date.
executive_filters conditions: Management-age criteria used by the playground: md_oldest_birth_date and md_youngest_birth_date.
lifecycle_filters conditions: Insolvency criteria used by the playground: insolvency_active, insolvency_status and insolvency_opened_date.

Each group is an object inside filters. Boolean fields take true or false. Date and number fields may use gte, lte, gt, lt, eq or exists. Dates accept YYYY, YYYY-MM or YYYY-MM-DD; a partial date covers the entire period. Ownership shares are decimals between 0 and 1, so 0.25 means 25%.

Register-derived filters in detail

These are the ownership, management and insolvency criteria available in the current main search playground, including its AI query and quick-start options. Each group is a condition object inside filters and combines with every other filter.

These groups require an active Pro or Max subscription. Without one the API answers HTTP 403 with error: subscription_required — meta.blocked_filters names the groups involved, meta.required_plans the plans that would allow them. A blocked filter is never dropped silently, because that would quietly make it a different search.

`ownership_filters` Ownership structure

One condition object

structure enum: How the group of owners is composed. Values: sole_person Single person · partners Several partners · sole_company Single company · family Family · fragmented Fragmented · corporate_group Corporate group
owner_managed boolean: At least one owner is also registered in management.
likely_family_owned boolean: Several owners share a family name — an indication of family ownership, not an official finding.
largest_share_ratio range: Largest single share, decimal between 0 and 1.
oldest_owner_birth_date date: Date of birth of the oldest owner.
youngest_owner_birth_date date: Date of birth of the youngest owner.

Match context: _match_context.ownership

`executive_filters` Management metrics

One condition object

md_oldest_birth_date date: Date of birth of the oldest active managing director.
md_youngest_birth_date date: Date of birth of the youngest active managing director.

Match context: _match_context.executive

`lifecycle_filters` Lifecycle & insolvency

One condition object

insolvency_active boolean: true = proceedings currently running. The field only exists where any proceeding was recorded — so {"exists": false} finds companies with no insolvency proceeding at all.
insolvency_status enum: State of the most recent proceeding. Values: opened Opened · provisional Provisional · discontinued Discontinued · concluded Concluded · rejected_no_assets Rejected for lack of assets · plan_monitoring Plan monitoring · opening_rescinded Opening rescinded
insolvency_opened_date date: Date the proceeding was opened.

Match context: _match_context.lifecycle

Each field takes a scalar, a list (any of them), or an operator object with gte, lte, gt, lt, eq or exists. Dates accept YYYY, YYYY-MM or YYYY-MM-DD; a partial date covers its whole period. Shares travel as a decimal between 0 and 1 — 0.25 means 25%.

With match_context=1 every hit reports under _match_context which entries satisfied the filter — each group under its own key.

Example: family-run, owner-managed companies whose oldest owner was born in 1959 or earlier

GET /v1/search-organizations?limit=10&match_context=1&filters={"state":"Bayern","ownership_filters":{"owner_managed":true,"likely_family_owned":true,"oldest_owner_birth_date":{"lte":"1959"}}}

Shown unencoded for readability — in real requests, URL-encode the filters value.

Excerpt from the response

{
  "name": "Muster Beteiligungs-GmbH",
  "_match_context": {
    "ownership": {
      "owner_managed": true,
      "likely_family_owned": true,
      "oldest_owner_birth_date": "1948-04-29"
    }
  }
}

Names and identifiers are replaced in this example.

Example Request

curl 'https://handelsregister.ai/api/v1/search-organizations?api_key=your_api_key_here&q=tech&limit=10&filters=%7B%22postal_code%22%3A%2280992%22%7D'

import requests
import json

url = "https://handelsregister.ai/api/v1/search-organizations"
params = {
    "api_key": "your_api_key_here",
    "q": "tech",
    "limit": 10,
    "filters": json.dumps({"postal_code": "80992"})
}

response = requests.get(url, params=params)
data = response.json()

const url = new URL('https://handelsregister.ai/api/v1/search-organizations');
url.searchParams.append('api_key', 'your_api_key_here');
url.searchParams.append('q', 'tech');
url.searchParams.append('limit', '10');
url.searchParams.append('filters', JSON.stringify({"postal_code": "80992"}));

fetch(url)
  .then(response => response.json())
  .then(data => console.log(data));

Example Response

{
  "results": [
    {
      "entity_id": "65063129c1bf565e4244b943a188bbda",
      "name": "m50 GmbH",
      "registration": {
        "court": "München",
        "register_type": "HRB",
        "register_number": "189767"
      },
      "address": {
        "house_number": "20",
        "street": "Gubestraße",
        "postal_code": "80992",
        "city": "München",
        "county": "München (Stadt)",
        "state": "Bayern",
        "country": "DEU",
        "coordinates": {
          "latitude": 48.18005,
          "longitude": 11.51116
        }
      },
      "registration_date": "2011-01-04T00:00:00",
      "purpose": "Film- und Fernsehproduktion..."
    }
  ],
  "total": 988,
  "meta": {
    "request_credit_cost": 1,
    "credits_remaining": "73841333"
  }
}

/v1/search-organizations

Parameters

Filters

Identity & Registration

Location

Court & Register

Size & Employees

Balance Sheet

Profit & Loss

Register-Derived Filters (Ownership, Management, Insolvency)

Register-derived filters in detail

ownership_filters Ownership structure

executive_filters Management metrics

lifecycle_filters Lifecycle & insolvency

Excerpt from the response

Example Request

Example Response

Cookie Settings

Customize Cookie Settings

`ownership_filters` Ownership structure

`executive_filters` Management metrics

`lifecycle_filters` Lifecycle & insolvency