@handelsregister/n8n-nodes-handelsregister-ai

This is an n8n community node that allows you to interact with the Handelsregister.ai API to query German business registry data.

Installation

Community Node

1. In n8n, go to Settings > Community Nodes
2. Click Install
3. Enter @handelsregister/n8n-nodes-handelsregister-ai
4. Click Install

Manual Installation

npm install @handelsregister/n8n-nodes-handelsregister-ai

Features

• Fetch Organization: Get comprehensive information about a German company including financial data, related persons, shareholders, UBOs, shareholdings, and publications
• Search Organizations: Search German companies with filters and pagination
• Fetch Document: Download official PDF documents from the German business registry (Shareholders List, AD, CD, Articles of Association)
• Fetch Person: Look up a person profile by name and company context (with AI enrichment)

Setup

1. Get your API key from Handelsregister.ai
2. In n8n, add credentials:
   • Go to Credentials > New
   • Select Handelsregister.ai API
   • Enter your API key
   • Save the credentials

Usage

Fetch Organization

Get comprehensive information about a German company:

• Query: Company name, registration number or search query (e.g., "Konux GmbH aus München")
• Features: Select additional data to include:
  • Financial KPI (1 Credit)
  • Balance Sheet Accounts (3 Credits)
  • Profit and Loss Account (3 Credits)
  • Related Persons (2 Credits)
  • Shareholders (5 Credits)
  • Publications (1 Credit)
  • News (10 Credits)
  • Insolvency Publications (1 Credit)
  • Annual Financial Statements (5 Credits)
  • Website Content (0 Credits - requires AI Mode to be enabled)
  • UBOs (Ultimate Beneficial Owners)
  • Shareholdings (outbound holdings the company has in other companies)
  • Annual Financial Statements (HTML) (HTML variant of the annual reports)
• AI Mode: Enable AI-powered search for better results (enabled by default)
• Realtime Mode: Enable live lookup against the official Handelsregister (+10 credits, disabled by default)

Search Organizations

Search German companies with filters and pagination:

• Query: Search query (minimum 2 characters, e.g., "Konux")
• Additional Fields:
  • Skip: Number of results to skip
  • Limit: Results per page (1-100)
  • Postal Code Filter: Filter by postal code

Fetch Document

Download official PDF documents from the German business registry:

• Company ID: Unique company entity ID from search results
• Document Type:
  • Shareholders List
  • Current Extract (AD)
  • Historical Extract (CD)
  • Articles of Association (Gesellschaftsvertrag / Satzung)

Fetch Person

Look up a person profile by name with company context for disambiguation. The endpoint always uses AI enrichment (15 base credits).

• Person Name: Full name of the person (minimum 2 characters, e.g., "Erika Mustermann")
• Organization: Company context used to disambiguate common names (minimum 2 characters, e.g., "Musterfirma GmbH")
• Features: Optional additional data
  • Shareholdings (+5 credits when data is returned)

Example Workflows

Fetch Organization with Features

{
  "nodes": [
    {
      "parameters": {
        "operation": "fetchOrganization",
        "q": "Konux GmbH aus München",
        "features": ["financial_kpi", "related_persons"],
        "ai_search": true
      },
      "name": "handelsregister.ai",
      "type": "@handelsregister/n8n-nodes-handelsregister-ai.handelsregisterAi",
      "typeVersion": 1,
      "position": [250, 300]
    }
  ]
}

Search Organizations with Filters

{
  "nodes": [
    {
      "parameters": {
        "operation": "searchOrganizations",
        "q": "tech",
        "additionalFields": {
          "limit": 20,
          "postal_code": "80331"
        }
      },
      "name": "Search Organizations",
      "type": "@handelsregister/n8n-nodes-handelsregister-ai.handelsregisterAi",
      "typeVersion": 1,
      "position": [250, 300]
    }
  ]
}

Fetch Document Workflow

{
  "nodes": [
    {
      "parameters": {
        "operation": "fetchDocument",
        "company_id": "{{ $json.entity_id }}",
        "document_type": "shareholders_list"
      },
      "name": "Fetch Document",
      "type": "@handelsregister/n8n-nodes-handelsregister-ai.handelsregisterAi",
      "typeVersion": 1,
      "position": [450, 300]
    }
  ]
}

Fetch Person Workflow

{
  "nodes": [
    {
      "parameters": {
        "operation": "fetchPerson",
        "person_q": "Erika Mustermann",
        "organization_q": "Musterfirma GmbH",
        "personFeatures": ["shareholdings"]
      },
      "name": "Fetch Person",
      "type": "@handelsregister/n8n-nodes-handelsregister-ai.handelsregisterAi",
      "typeVersion": 1,
      "position": [450, 300]
    }
  ]
}

Batch Company Processing

Use this workflow to process multiple companies from a spreadsheet or database:

1. Spreadsheet/Database Node → Read company names
2. handelsregister.ai Node → Use searchOrganizations to find companies
3. Filter Node → Filter results based on criteria
4. handelsregister.ai Node → Use fetchOrganization to get detailed data
5. Output Node → Save results to database or file

Development

# Install dependencies
npm install

# Build the node
npm run build

# Run in development mode
npm run dev

License

MIT

Support

For issues and feature requests, please visit the GitHub repository.