# German Handelsregister Company Lookup (HRB/HRA) (`metsuryu/handelsregister-company-lookup`) Actor

Lookup German companies on handelsregister.de by keyword or HRB/HRA number. Returns court, seat, status, docs & name history. Pay per company.

- **URL**: https://apify.com/metsuryu/handelsregister-company-lookup.md
- **Developed by:** [Mario Cannistrà](https://apify.com/metsuryu) (community)
- **Categories:** Business, Lead generation
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $6.00 / 1,000 dataset item (company)s

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/actors/running/actors-in-store.md#pay-per-event

## What's an Apify Actor?

An Actor is a serverless cloud program that runs on the Apify platform. It has two run modes.
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.

Apify vocabulary and the platform model are defined once, in the agent quickstart at https://apify.com/agents.md.

## 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.

Do not guess an integration path. Every one of them is in the agent quickstart at https://apify.com/agents.md: the Apify MCP server, Agent Skills with the Apify CLI, the JavaScript and Python clients, the REST API, and the account-free path for an agent with no human to sign in. It also carries the rule on stating cost before the first paid run.

For examples already wired to this Actor's own input schema, see the [API](#api) section below.

Each client library has reference documentation the quickstart does not restate: [JavaScript/TypeScript](https://docs.apify.com/api/client/js/docs.md) (`npm install apify-client`) and [Python](https://docs.apify.com/api/client/python/docs.md) (`pip install apify-client`).

# README

## German Handelsregister Company Lookup (handelsregister.de)

Search the official **German company register** ([handelsregister.de](https://www.handelsregister.de)) by keyword or **HRB / HRA / GnR / PR / VR / GsR** number. Get clean JSON: company name, register court, seat, federal state, status, available document codes, and name history.

Store: [metsuryu/handelsregister-company-lookup](https://apify.com/metsuryu/handelsregister-company-lookup)

### What it does

Walks the public Registerportal advanced-search flow (stateful JSF session), submits your keyword or register filters, and parses the result table. **One dataset item per company.**

### Why use this Actor

- **Official portal** — primary source German federal states maintain
- **Cheap PPE** — pay per company row; undercuts richer SI competitors when you only need search-table facts
- **No CAPTCHA wall** in normal operation (DC proxies OK)
- **Ready-made tasks** — demo lookups you can clone and edit

### Common use cases (ready-made tasks)

| Use case | Task | What you get |
| --- | --- | --- |
| **Demo: Gasag group companies** | [gasag-company-lookup](https://apify.com/metsuryu/handelsregister-company-lookup/task/gasag-company-lookup) | Sample Berlin energy-group hits from keyword `Gasag` |
| **Siemens keyword search** (max 50) | [siemens-hrb-keyword-search](https://apify.com/metsuryu/handelsregister-company-lookup/task/siemens-hrb-keyword-search) | Broader keyword scan capped for cost control |

Typical buyers: KYC / AML enrichment, lead gen on German GmbH/AG entities, M\&A screening, and CRM backfill of register court + HRB number.

### Honest limits (read before buying)

- **Portal cap:** each search returns at most **100** hits — split broad names into narrower queries (city, register type, state).
- **Rate limits:** the justice portal paces / IP-blocks aggressive clients (order of ~60 retrievals/hour class). This Actor adds request delays; use **datacenter proxies** on Apify.
- **No CAPTCHA wall** in normal operation (unlike Cloudflare-gated Italian registries). If a CAPTCHA appears, the run fails loudly.
- **v0.1 fields:** search-table facts + history. Structured SI/XJustiz officers & street address are **not** fetched yet (`officers` / `address` / `legalForm` stay `null`). Competitor Actors that parse SI charge more for a reason. *(v0.2 SI enrichment skipped for now — see sprint notes: feasible without CAPTCHA but not low-risk JSF/doc-tree work.)*

### Input highlights

| Field | Purpose |
| --- | --- |
| `searchQueries` | Keywords; one portal search each |
| `keywordMatch` | `all` / `any` / `exact` |
| `registerType` + `registerNumber` + `registerCourt` | Precise lookup |
| `city` / `postalCode` / `states` | Geographic narrowing |
| `includeDeleted` | Include gelöscht entries |
| `maxItems` | Hard cap (PPE control) |
| `proxy` | Apify Proxy (DC OK) |

### Example input

```json
{
  "searchQueries": ["Gasag"],
  "keywordMatch": "all",
  "maxItems": 10,
  "proxy": { "useApifyProxy": true }
}
```

### Output fields

`companyName`, `registerId`, `registerCourt`, `registerType`, `registerNumber`, `state`, `seat`, `status`, `statusRaw`, `history[]`, `availableDocuments[]`, `searchQuery`, `scrapedAt`.

### Pricing

Pay-per-event: near-zero `apify-actor-start` + primary charge per company dataset item. See the pricing panel.

### Legal / GDPR

Public register data. Officer PII appears only if/when SI parsing is enabled in a later version — users remain responsible for lawful basis under GDPR and the portal terms (no bulk dump / resale of the full register).

# Actor input Schema

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

Company-name keywords, one portal search per entry (portal caps each search at 100 results). Example: Siemens, Gasag, Bäckerei München.

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

all = contain every word; any = at least one word; exact = exact company name.

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

Optional: HRA, HRB, GnR, PR, VR, or GsR. Empty = all.

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

Exact register number for a precise lookup (combine with register type / court).

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

Amtsgericht name filter, e.g. München or Berlin (Charlottenburg). Best-effort text filter.

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

Optional legal-form filter (portal label or abbreviation, e.g. GmbH).

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

Seat postal code filter, e.g. 80331.

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

Seat city filter, e.g. Hamburg.

## `street` (type: `string`):

Optional street filter.

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

Restrict to Bundesländer. Exact portal labels: 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 gelöscht (deleted) register entries.

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

Hard cap on dataset rows across all queries (controls PPE cost). Portal also caps each search at 100.

## `requestDelayMs` (type: `integer`):

Polite pacing. Portal rate-limits aggressive clients; 600–1500 ms recommended.

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

Datacenter proxies are usually enough (no CAPTCHA wall). Enable Apify Proxy on the platform.

## Actor input object example

```json
{
  "searchQueries": [
    "Gasag"
  ],
  "keywordMatch": "all",
  "registerType": "",
  "registerNumber": "",
  "registerCourt": "",
  "legalForm": "",
  "postalCode": "",
  "city": "",
  "street": "",
  "states": [],
  "includeDeleted": false,
  "maxItems": 100,
  "requestDelayMs": 800,
  "proxy": {
    "useApifyProxy": true
  }
}
```

# Actor output Schema

## `companies` (type: `string`):

Normalized Handelsregister company rows in the default dataset.

# 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 = {};

// Run the Actor and wait for it to finish
const run = await client.actor("metsuryu/handelsregister-company-lookup").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 = {}

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

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

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

```

## CLI example

```bash
echo '{}' |
apify call metsuryu/handelsregister-company-lookup --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,metsuryu/handelsregister-company-lookup"
        }
    }
}
```

The hosted server signs you in with OAuth on first connect, so no API token belongs in this config. Clients without OAuth support can send an `Authorization: Bearer <APIFY_API_TOKEN>` header instead, using a token from API & Integrations in Apify Console (https://console.apify.com/settings/integrations).

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/TK3qfuIfwXrx8eQVs/builds/rhWOgwnvdE0WUlJGR/openapi.json