# Handelsregister.de \[$8💰] German Company Registry (`memo23/handelsregister-scraper`) Actor

Scrape the official German company register (handelsregister.de) — register number, court, status, legal form, registered address, officers with roles & birth dates, representation rules, and name history. Precise lookups or keyword search with filters. JSON or CSV out.

- **URL**: https://apify.com/memo23/handelsregister-scraper.md
- **Developed by:** [Muhamed Didovic](https://apify.com/memo23) (community)
- **Categories:** Lead generation, AI, Agents
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $8.00 / 1,000 company records

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.

Learn more: https://docs.apify.com/platform/actors/running/actors-in-store#pay-per-event

## What's an Apify Actor?

Actors are a software tools running on the Apify platform, for all kinds of web data extraction and automation use cases.
In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours,
and optionally produces a well-defined JSON output, datasets with results, or files in key-value store.
In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server.
Actors are written with capital "A".

## How to integrate an Actor?

If asked about integration, you help developers integrate Actors into their projects.
You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready.
The best way to integrate Actors is as follows.

In JavaScript/TypeScript projects, use official [JavaScript/TypeScript client](https://docs.apify.com/api/client/js/docs.md):

```bash
npm install apify-client
```

In Python projects, use official [Python client library](https://docs.apify.com/api/client/python/docs.md):

```bash
pip install apify-client
```

In shell scripts, use [Apify CLI](https://docs.apify.com/cli/docs.md):

````bash
# MacOS / Linux
curl -fsSL https://apify.com/install-cli.sh | bash
# Windows
irm https://apify.com/install-cli.ps1 | iex
```bash

In AI frameworks, you might use the [Apify MCP server](https://docs.apify.com/integrations/mcp.md).

If your project is in a different language, use the [REST API](https://docs.apify.com/api/v2.md).

For usage examples, see the [API](#api) section below.

For more details, see Apify documentation as [Markdown index](https://docs.apify.com/llms.txt) and [Markdown full-text](https://docs.apify.com/llms-full.txt).


# README

## Handelsregister Scraper — German Company Registry (handelsregister.de)

Search the **official German company register** and get clean, structured company records — register number, court, legal form, registered address, **officers with roles and birth dates**, representation rules, and the full name history. One row per company, straight from the primary source German authorities maintain.

#### How it works

![How the Handelsregister Scraper works](https://raw.githubusercontent.com/muhamed-didovic/muhamed-didovic.github.io/main/assets/how-it-works-handelsregister.png)

#### ✨ Why use this scraper?

- **Primary-source data** — reads the official Registerportal of the German federal states, not a third-party aggregator with stale copies.
- **Structured officers** — every record can include Geschäftsführer, Prokuristen, Vorstände and liquidators with role, full name, birth date, and city, parsed from the official XJustiz "SI" document.
- **All six registers** — HRA, HRB, GnR, PR, VR, and GsR, including deleted (gelöscht) entries for due-diligence work.
- **Register history included** — former company names and former seats, numbered in order, for tracing renames and relocations.
- **Precise or broad** — look up one exact register number at one court, or fan out multiple keyword queries with legal-form, city, postal-code, and federal-state filters in a single run.
- **KYC/KYB-ready shape** — one JSON row per company with a stable `registerId` (court + type + number), the natural key German compliance workflows expect.

#### 🎯 Use cases

| Who | What they do with it |
|---|---|
| **KYC / compliance teams** | Verify counterparties against the official register: status, officers, representation rules |
| **B2B lead-gen & sales ops** | Build German company lists by city, legal form, or industry keyword — with decision-maker names |
| **Credit & risk analysts** | Track register status and officer changes for portfolios of German counterparties |
| **Law firms & insolvency practitioners** | Pull register facts and name history without clicking through the portal case by case |
| **Data & investigative journalists** | Trace networks of officers and renamed entities across register courts |
| **M&A / market researchers** | Map subsidiaries and legal-entity structures of German groups |

#### 📥 Supported inputs

| Input | Example | What it does |
|---|---|---|
| `searchQueries` | `["Siemens", "Bäckerei München"]` | One portal search per entry (each capped at 100 results by the portal) |
| `keywordMatch` | `all` / `any` / `exact` | How the words inside one query combine |
| `registerType` + `registerNumber` + `registerCourt` | `HRB` + `230633` + `München` | Precise single-company lookup |
| `legalForm` | `Gesellschaft mit beschränkter Haftung` | Filter by legal form |
| `postalCode` / `city` / `states` | `80331` / `Hamburg` / `["Bayern"]` | Geographic narrowing |
| `includeDeleted` | `true` | Also return deleted register entries |

**Not supported:** document downloads other than the structured SI record (AD/CD/HD PDF printouts and the DK document list are not fetched), and bulk full-register dumps — the portal caps every search at 100 results, so coverage comes from running several narrower queries.

#### 🔄 How it works

1. **Opens a session** on the official Registerportal (handelsregister.de) and walks its stateful search flow.
2. **Submits your advanced search** — keywords plus any register-type, court, legal-form, and location filters.
3. **Parses the result table**: company name, register court, HRA/HRB/GnR/PR/VR/GsR number, seat, state, status, and name history.
4. **Downloads the official SI document** (structured XJustiz XML) per company and extracts address, officers, and representation rules — toggle with `fetchStructuredData`.
5. **Pushes one deduplicated row per company** across all your queries, ready as JSON, CSV, or Excel.

#### ⚙️ Input parameters

| Field | Type | Default | Description |
|---|---|---|---|
| `searchQueries` | array | `["Siemens"]` | Company-name keywords; one portal search per entry |
| `keywordMatch` | string | `all` | `all` words, `any` word, or `exact` company name |
| `registerType` | string | *(all)* | HRA, HRB, GnR, PR, VR, or GsR |
| `registerNumber` | string | — | Exact register number |
| `registerCourt` | string | — | Amtsgericht name, e.g. `München`, `Charlottenburg (Berlin)` |
| `legalForm` | string | — | Legal-form label, e.g. `Aktiengesellschaft` |
| `postalCode` / `city` / `street` | string | — | Seat address filters |
| `states` | array | — | Federal states, e.g. `["Bayern", "Hessen"]` |
| `includeDeleted` | boolean | `false` | Include deleted (gelöscht) entries |
| `fetchStructuredData` | boolean | `true` | Download + parse the SI record (address, officers, representation) |
| `includeRawXml` | boolean | `false` | Attach the raw XJustiz XML to each row |
| `maxItems` | integer | `1000` | Hard cap on company rows |
| `maxConcurrency` | integer | `3` | Parallel portal sessions (one per query) |
| `proxy` | object | Apify auto | Datacenter proxies are sufficient — no anti-bot wall |

#### 📊 Output overview

Each dataset row describes **one register entry**: the search-table facts (name, court, register number, status, history) plus — when `fetchStructuredData` is on — the parsed official SI record (registered address, officers with roles and birth dates, representation rules, legal form). Fields the register doesn't expose for an entity stay `null`.

#### 📦 Output sample

```json
{
    "type": "company-registration",
    "companyName": "AREVA GmbH",
    "registerId": "Amtsgericht Fürth HRB 7817",
    "registerCourt": "Amtsgericht Fürth",
    "registerType": "HRB",
    "registerNumber": "7817",
    "state": "Bayern",
    "seat": "Erlangen",
    "status": "active",
    "statusRaw": "aktuell",
    "history": [
        { "position": 1, "name": "Siemens Nuclear Power GmbH", "seat": "Erlangen" },
        { "position": 2, "name": "Framatome ANP GmbH", "seat": "Erlangen" },
        { "position": 3, "name": "AREVA NP GmbH", "seat": "Erlangen" }
    ],
    "availableDocuments": ["AD", "CD", "HD", "UT", "VÖ", "SI"],
    "legalName": "AREVA GmbH",
    "legalForm": "Gesellschaft mit beschränkter Haftung (GmbH)",
    "address": {
        "street": "Paul-Gossen-Str.100",
        "houseNumber": null,
        "postalCode": "91052",
        "city": "Erlangen",
        "country": "Deutschland"
    },
    "representationRules": "Ist nur ein Geschäftsführer bestellt, so vertritt er die Gesellschaft allein. Sind mehrere Geschäftsführer bestellt, so wird die Gesellschaft durch zwei Geschäftsführer oder durch einen Geschäftsführer gemeinsam mit einem Prokuristen vertreten.",
    "officers": [
        { "role": "Geschäftsführer(in)", "firstName": "Ulrich", "lastName": "Klapp", "fullName": "Ulrich Klapp", "birthDate": "1974-04-09", "city": "Erlangen", "organisationName": null },
        { "role": "Prokurist(in)", "firstName": "René", "lastName": "Schümer", "fullName": "René Schümer", "birthDate": "1967-05-29", "city": "Erlangen", "organisationName": null }
    ],
    "registerCourtOfficial": "Amtsgericht Fürth",
    "searchQuery": "Siemens",
    "scrapedAt": "2026-07-16T21:30:12.000Z"
}
````

#### 🗂 Key output fields

| Group | Fields | Notes |
|---|---|---|
| **Identity** | `companyName`, `legalName`, `registerId`, `registerType`, `registerNumber`, `registerCourt` | `registerId` is the stable natural key |
| **Status & location** | `status`, `statusRaw`, `seat`, `state`, `address.{street, houseNumber, postalCode, city, country}` | `status` is normalized to `active` / `deleted` |
| **People** | `officers[].{role, fullName, firstName, lastName, birthDate, city, organisationName}` | `organisationName` set when the officer is a company (e.g. general partner GmbH) |
| **Governance** | `representationRules`, `legalForm` | Parsed from the official SI record |
| **History** | `history[].{position, name, seat}` | Former names and seats in chronological order |
| **Meta** | `availableDocuments`, `searchQuery`, `scrapedAt`, `siXml` (opt-in) | `availableDocuments` lists what the portal offers per entry |

#### ❓ FAQ

**Why do I get at most 100 results per query?**
That's a hard cap of the official portal itself, not the scraper. Split a broad name into narrower queries — add a `registerType`, a `city`, a `legalForm`, or per-state runs — and the actor deduplicates rows across queries automatically.

**Where do the officer names come from?**
From the official SI ("Strukturierte Registerinhalte") document — the same structured XJustiz XML the justice administration publishes per register entry. It's fetched per company when `fetchStructuredData` is on (default).

**Does it cover all of Germany?**
Yes. The Registerportal is the common portal of all federal states, so all ~150 register courts (Amtsgerichte) are searchable, and results span HRA, HRB, GnR, PR, VR, and GsR.

**Can I get the AD/HD PDF printouts too?**
Not in this actor — it fetches the structured SI record, which contains the current register facts in machine-readable form. If you need the certified PDF printouts, open the entry on the portal directly.

**Is the data current?**
Every run queries the live portal, so you see exactly what the register shows at that moment — including entries deleted or renamed yesterday.

**Do I need residential proxies?**
No. The portal is a public government service without an anti-bot wall; default Apify datacenter proxies (or none) work. The actor paces its requests to stay polite.

#### 💬 Support

Found an issue or missing a field? Open an issue on the actor's **Issues** tab in Apify Console — I usually respond within 24 hours.

#### 🛠 Additional services

Need a custom pipeline on top of this data (officer-change monitoring, matching against your CRM, bulk enrichment with websites/emails), or a scraper for another registry? Reach out via the Issues tab.

#### 🔎 Explore more scrapers

More actors from the same portfolio: [Trustpilot](https://apify.com/memo23/trustpilot-scraper-ppe), [Clutch.co](https://apify.com/memo23/apify-clutch-cheerio), [G2](https://apify.com/memo23/g2-scraper), [Idealista](https://apify.com/memo23/idealista-scraper), [Crunchbase](https://apify.com/memo23/crunchbase-scraper) — see the full list on the [memo23 profile](https://apify.com/memo23).

***

### ⚠️ Disclaimer

This Actor is an independent tool and is not affiliated with, endorsed by, or sponsored by the German justice administration, the Registerportal der Länder (handelsregister.de), or any German federal state. All trademarks mentioned are the property of their respective owners.

The scraper accesses only publicly available register information — no authenticated endpoints or paid documents. Register data contains personal data (officer names and birth dates); users are responsible for ensuring their use complies with the portal's terms of use, applicable data-protection law (GDPR — in particular Art. 6(1) lawful-basis requirements for processing officer data), and any contractual obligations of their own organisation.

***

### SEO Keywords

handelsregister scraper, handelsregister api, german company registry scraper, scrape handelsregister.de, german business register api, HRB lookup api, german company data extraction, registerportal scraper, german company officers data, geschäftsführer data api, german kyc data, kyb germany api, german company register export, amtsgericht register search, german trade register scraper, unternehmensregister alternative, north data alternative, german b2b leads, company register germany json, xjustiz parser

# Actor input Schema

## `searchQueries` (type: `array`):

Company-name keywords, one search per entry, e.g. `Siemens` or `Bäckerei München`. The portal caps each search at 100 results, so split broad terms into narrower queries (by city, register type, or legal form).

## `keywordMatch` (type: `string`):

How the words inside one query combine: `all` — every word must appear; `any` — at least one word; `exact` — exact company name.

## `registerType` (type: `string`):

Restrict to one register: HRA (partnerships/sole traders), HRB (GmbH/AG), GnR (cooperatives), PR (professional partnerships), VR (associations), GsR (civil-law partnerships). Empty = all.

## `registerNumber` (type: `string`):

Exact register number, e.g. `230633`. Combine with register type and court for a precise lookup.

## `registerCourt` (type: `string`):

Amtsgericht that keeps the record, by name as on the portal — e.g. `München`, `Charlottenburg (Berlin)`, `Duisburg`.

## `legalForm` (type: `string`):

Filter by legal form label, e.g. `Gesellschaft mit beschränkter Haftung`, `Aktiengesellschaft`, `eingetragener Verein`.

## `postalCode` (type: `string`):

Filter by the company seat's postal code, e.g. `80331`.

## `city` (type: `string`):

Filter by the company seat's city, e.g. `Hamburg`.

## `states` (type: `array`):

Restrict results to specific Bundesländer. Allowed values: Baden-Württemberg, Bayern, Berlin, Brandenburg, Bremen, Hamburg, Hessen, Mecklenburg-Vorpommern, Niedersachsen, Nordrhein-Westfalen, Rheinland-Pfalz, Saarland, Sachsen, Sachsen-Anhalt, Schleswig-Holstein, Thüringen.

## `includeDeleted` (type: `boolean`):

Also return companies whose register entry has been deleted (gelöscht). Useful for due-diligence and history research.

## `fetchStructuredData` (type: `boolean`):

Download and parse the official SI document (structured XJustiz XML) for every company: registered street address, officers with roles and birth dates, representation rules, legal form. One extra request per company.

## `includeRawXml` (type: `boolean`):

Attach the raw SI XML string to each row (large — increases dataset size significantly). For users who need fields beyond the parsed set.

## `maxItems` (type: `integer`):

Hard cap on company records pushed to the dataset across all queries.

## `maxConcurrency` (type: `integer`):

How many portal sessions run in parallel (one per search query). Keep low — the portal is a government service and drops connections when hammered.

## `proxy` (type: `object`):

handelsregister.de is a public government portal with no anti-bot wall — datacenter proxies are sufficient.

## Actor input object example

```json
{
  "searchQueries": [
    "Siemens"
  ],
  "keywordMatch": "all",
  "registerType": "",
  "includeDeleted": false,
  "fetchStructuredData": true,
  "includeRawXml": false,
  "maxItems": 1000,
  "maxConcurrency": 3,
  "proxy": {
    "useApifyProxy": true
  }
}
```

# API

You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup.

## JavaScript example

```javascript
import { ApifyClient } from 'apify-client';

// Initialize the ApifyClient with your Apify API token
// Replace the '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {
    "searchQueries": [
        "Siemens"
    ],
    "proxy": {
        "useApifyProxy": true
    }
};

// Run the Actor and wait for it to finish
const run = await client.actor("memo23/handelsregister-scraper").call(input);

// Fetch and print Actor results from the run's dataset (if any)
console.log('Results from dataset');
console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`);
const { items } = await client.dataset(run.defaultDatasetId).listItems();
items.forEach((item) => {
    console.dir(item);
});

// 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs

```

## Python example

```python
from apify_client import ApifyClient

# Initialize the ApifyClient with your Apify API token
# Replace '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = {
    "searchQueries": ["Siemens"],
    "proxy": { "useApifyProxy": True },
}

# Run the Actor and wait for it to finish
run = client.actor("memo23/handelsregister-scraper").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print("💾 Check your data here: https://console.apify.com/storage/datasets/" + run["defaultDatasetId"])
for item in client.dataset(run["defaultDatasetId"]).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

```

## CLI example

```bash
echo '{
  "searchQueries": [
    "Siemens"
  ],
  "proxy": {
    "useApifyProxy": true
  }
}' |
apify call memo23/handelsregister-scraper --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "command": "npx",
            "args": [
                "mcp-remote",
                "https://mcp.apify.com/?tools=memo23/handelsregister-scraper",
                "--header",
                "Authorization: Bearer <YOUR_API_TOKEN>"
            ]
        }
    }
}

```

## OpenAPI specification

```json
{
    "openapi": "3.0.1",
    "info": {
        "title": "Handelsregister.de [$8💰] German Company Registry",
        "description": "Scrape the official German company register (handelsregister.de) — register number, court, status, legal form, registered address, officers with roles & birth dates, representation rules, and name history. Precise lookups or keyword search with filters. JSON or CSV out.",
        "version": "0.0",
        "x-build-id": "vmgPS34ZauGUrxSTo"
    },
    "servers": [
        {
            "url": "https://api.apify.com/v2"
        }
    ],
    "paths": {
        "/acts/memo23~handelsregister-scraper/run-sync-get-dataset-items": {
            "post": {
                "operationId": "run-sync-get-dataset-items-memo23-handelsregister-scraper",
                "x-openai-isConsequential": false,
                "summary": "Executes an Actor, waits for its completion, and returns Actor's dataset items in response.",
                "tags": [
                    "Run Actor"
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/inputSchema"
                            }
                        }
                    }
                },
                "parameters": [
                    {
                        "name": "token",
                        "in": "query",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Enter your Apify token here"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK"
                    }
                }
            }
        },
        "/acts/memo23~handelsregister-scraper/runs": {
            "post": {
                "operationId": "runs-sync-memo23-handelsregister-scraper",
                "x-openai-isConsequential": false,
                "summary": "Executes an Actor and returns information about the initiated run in response.",
                "tags": [
                    "Run Actor"
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/inputSchema"
                            }
                        }
                    }
                },
                "parameters": [
                    {
                        "name": "token",
                        "in": "query",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Enter your Apify token here"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/runsResponseSchema"
                                }
                            }
                        }
                    }
                }
            }
        },
        "/acts/memo23~handelsregister-scraper/run-sync": {
            "post": {
                "operationId": "run-sync-memo23-handelsregister-scraper",
                "x-openai-isConsequential": false,
                "summary": "Executes an Actor, waits for completion, and returns the OUTPUT from Key-value store in response.",
                "tags": [
                    "Run Actor"
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/inputSchema"
                            }
                        }
                    }
                },
                "parameters": [
                    {
                        "name": "token",
                        "in": "query",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Enter your Apify token here"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK"
                    }
                }
            }
        }
    },
    "components": {
        "schemas": {
            "inputSchema": {
                "type": "object",
                "properties": {
                    "searchQueries": {
                        "title": "Company name keywords (one search per line)",
                        "type": "array",
                        "description": "Company-name keywords, one search per entry, e.g. `Siemens` or `Bäckerei München`. The portal caps each search at 100 results, so split broad terms into narrower queries (by city, register type, or legal form).",
                        "items": {
                            "type": "string"
                        }
                    },
                    "keywordMatch": {
                        "title": "Keyword matching",
                        "enum": [
                            "all",
                            "any",
                            "exact"
                        ],
                        "type": "string",
                        "description": "How the words inside one query combine: `all` — every word must appear; `any` — at least one word; `exact` — exact company name.",
                        "default": "all"
                    },
                    "registerType": {
                        "title": "Register type",
                        "enum": [
                            "",
                            "HRA",
                            "HRB",
                            "GnR",
                            "PR",
                            "VR",
                            "GsR"
                        ],
                        "type": "string",
                        "description": "Restrict to one register: HRA (partnerships/sole traders), HRB (GmbH/AG), GnR (cooperatives), PR (professional partnerships), VR (associations), GsR (civil-law partnerships). Empty = all.",
                        "default": ""
                    },
                    "registerNumber": {
                        "title": "Register number",
                        "type": "string",
                        "description": "Exact register number, e.g. `230633`. Combine with register type and court for a precise lookup."
                    },
                    "registerCourt": {
                        "title": "Register court",
                        "type": "string",
                        "description": "Amtsgericht that keeps the record, by name as on the portal — e.g. `München`, `Charlottenburg (Berlin)`, `Duisburg`."
                    },
                    "legalForm": {
                        "title": "Legal form",
                        "type": "string",
                        "description": "Filter by legal form label, e.g. `Gesellschaft mit beschränkter Haftung`, `Aktiengesellschaft`, `eingetragener Verein`."
                    },
                    "postalCode": {
                        "title": "Postal code",
                        "type": "string",
                        "description": "Filter by the company seat's postal code, e.g. `80331`."
                    },
                    "city": {
                        "title": "City",
                        "type": "string",
                        "description": "Filter by the company seat's city, e.g. `Hamburg`."
                    },
                    "states": {
                        "title": "Federal states",
                        "type": "array",
                        "description": "Restrict results to specific Bundesländer. Allowed values: Baden-Württemberg, Bayern, Berlin, Brandenburg, Bremen, Hamburg, Hessen, Mecklenburg-Vorpommern, Niedersachsen, Nordrhein-Westfalen, Rheinland-Pfalz, Saarland, Sachsen, Sachsen-Anhalt, Schleswig-Holstein, Thüringen.",
                        "items": {
                            "type": "string"
                        }
                    },
                    "includeDeleted": {
                        "title": "Include deleted entries",
                        "type": "boolean",
                        "description": "Also return companies whose register entry has been deleted (gelöscht). Useful for due-diligence and history research.",
                        "default": false
                    },
                    "fetchStructuredData": {
                        "title": "Fetch structured register data (address, officers, representation)",
                        "type": "boolean",
                        "description": "Download and parse the official SI document (structured XJustiz XML) for every company: registered street address, officers with roles and birth dates, representation rules, legal form. One extra request per company.",
                        "default": true
                    },
                    "includeRawXml": {
                        "title": "Include raw XJustiz XML",
                        "type": "boolean",
                        "description": "Attach the raw SI XML string to each row (large — increases dataset size significantly). For users who need fields beyond the parsed set.",
                        "default": false
                    },
                    "maxItems": {
                        "title": "Maximum companies to scrape",
                        "minimum": 1,
                        "type": "integer",
                        "description": "Hard cap on company records pushed to the dataset across all queries.",
                        "default": 1000
                    },
                    "maxConcurrency": {
                        "title": "Max concurrent searches",
                        "minimum": 1,
                        "maximum": 10,
                        "type": "integer",
                        "description": "How many portal sessions run in parallel (one per search query). Keep low — the portal is a government service and drops connections when hammered.",
                        "default": 3
                    },
                    "proxy": {
                        "title": "Proxy configuration",
                        "type": "object",
                        "description": "handelsregister.de is a public government portal with no anti-bot wall — datacenter proxies are sufficient.",
                        "default": {
                            "useApifyProxy": true
                        }
                    }
                }
            },
            "runsResponseSchema": {
                "type": "object",
                "properties": {
                    "data": {
                        "type": "object",
                        "properties": {
                            "id": {
                                "type": "string"
                            },
                            "actId": {
                                "type": "string"
                            },
                            "userId": {
                                "type": "string"
                            },
                            "startedAt": {
                                "type": "string",
                                "format": "date-time",
                                "example": "2025-01-08T00:00:00.000Z"
                            },
                            "finishedAt": {
                                "type": "string",
                                "format": "date-time",
                                "example": "2025-01-08T00:00:00.000Z"
                            },
                            "status": {
                                "type": "string",
                                "example": "READY"
                            },
                            "meta": {
                                "type": "object",
                                "properties": {
                                    "origin": {
                                        "type": "string",
                                        "example": "API"
                                    },
                                    "userAgent": {
                                        "type": "string"
                                    }
                                }
                            },
                            "stats": {
                                "type": "object",
                                "properties": {
                                    "inputBodyLen": {
                                        "type": "integer",
                                        "example": 2000
                                    },
                                    "rebootCount": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "restartCount": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "resurrectCount": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "computeUnits": {
                                        "type": "integer",
                                        "example": 0
                                    }
                                }
                            },
                            "options": {
                                "type": "object",
                                "properties": {
                                    "build": {
                                        "type": "string",
                                        "example": "latest"
                                    },
                                    "timeoutSecs": {
                                        "type": "integer",
                                        "example": 300
                                    },
                                    "memoryMbytes": {
                                        "type": "integer",
                                        "example": 1024
                                    },
                                    "diskMbytes": {
                                        "type": "integer",
                                        "example": 2048
                                    }
                                }
                            },
                            "buildId": {
                                "type": "string"
                            },
                            "defaultKeyValueStoreId": {
                                "type": "string"
                            },
                            "defaultDatasetId": {
                                "type": "string"
                            },
                            "defaultRequestQueueId": {
                                "type": "string"
                            },
                            "buildNumber": {
                                "type": "string",
                                "example": "1.0.0"
                            },
                            "containerUrl": {
                                "type": "string"
                            },
                            "usage": {
                                "type": "object",
                                "properties": {
                                    "ACTOR_COMPUTE_UNITS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATASET_READS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATASET_WRITES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "KEY_VALUE_STORE_READS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "KEY_VALUE_STORE_WRITES": {
                                        "type": "integer",
                                        "example": 1
                                    },
                                    "KEY_VALUE_STORE_LISTS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "REQUEST_QUEUE_READS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "REQUEST_QUEUE_WRITES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATA_TRANSFER_INTERNAL_GBYTES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATA_TRANSFER_EXTERNAL_GBYTES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "PROXY_RESIDENTIAL_TRANSFER_GBYTES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "PROXY_SERPS": {
                                        "type": "integer",
                                        "example": 0
                                    }
                                }
                            },
                            "usageTotalUsd": {
                                "type": "number",
                                "example": 0.00005
                            },
                            "usageUsd": {
                                "type": "object",
                                "properties": {
                                    "ACTOR_COMPUTE_UNITS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATASET_READS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATASET_WRITES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "KEY_VALUE_STORE_READS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "KEY_VALUE_STORE_WRITES": {
                                        "type": "number",
                                        "example": 0.00005
                                    },
                                    "KEY_VALUE_STORE_LISTS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "REQUEST_QUEUE_READS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "REQUEST_QUEUE_WRITES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATA_TRANSFER_INTERNAL_GBYTES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATA_TRANSFER_EXTERNAL_GBYTES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "PROXY_RESIDENTIAL_TRANSFER_GBYTES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "PROXY_SERPS": {
                                        "type": "integer",
                                        "example": 0
                                    }
                                }
                            }
                        }
                    }
                }
            }
        }
    }
}
```
