Node SDK

The API from JavaScript and TypeScript.

The Node SDK provides a client for JavaScript and TypeScript, with type definitions for requests and responses. It retries temporary errors on its own and turns error responses into dedicated error classes.

Install

Install the handelsregister package with npm.

Terminal

npm install handelsregister
export HANDELSREGISTER_API_KEY=YOUR_API_KEY

What
What	Value
Package	`handelsregister`
Current version	0.7.0
Node.js	22.13 or newer
TypeScript	Type definitions included
License	AGPL-3.0
Source code	github.com/Handelsregister-AI/handelsregister-js

The SDK reads your API key from the HANDELSREGISTER_API_KEY environment variable. You can also pass it when you create the client. A bearer token goes through HANDELSREGISTER_BEARER_TOKEN or bearerToken. The key is always sent in the header, never in the URL.

First request

fetchOrganization fetches a company profile and returns the API response as an object. The q parameter takes a name, register court with register number, or an entity_id.

JavaScript

import { Handelsregister } from 'handelsregister';

const client = new Handelsregister({ apiKey: process.env.HANDELSREGISTER_API_KEY });

const company = await client.fetchOrganization({ q: 'Hetzner Online GmbH' });
console.log(company.entity_id, company.name);
console.log(company.registration); // { court: 'Ansbach', register_type: 'HRB', register_number: '6089' }
console.log(company.meta.request_credit_cost);

The response is the same as for fetch-organization. Here is an excerpt:

1{2  "entity_id": "94eb910fef13f94585c48c263fa446d4",3  "name": "Hetzner Online GmbH",4  "status": "ACTIVE",5  "legal_form": "GmbH",6  "registration": {7    "court": "Ansbach",8    "register_type": "HRB",9    "register_number": "6089"10  },11  "meta": {12    "request_credit_cost": 5,13    "credits_remaining": 14514  }15}

200 · Excerpt from our example response for Hetzner Online GmbH, Ansbach HRB 6089, basic data only

You request more data with features, AI Mode with aiSearch: true and Realtime with realtimeMode: true. All features are listed under fetch-organization.

JavaScript

const company = await client.fetchOrganization({
  q: 'Ansbach HRB 6089',
  features: ['financial_kpi', 'related_persons'],
});

For one hour, the client answers identical requests from its cache, without new credits. Requests with Realtime always go to the API. Set cacheEnabled: false to turn the cache off.

Handle errors

Every error response from the API becomes an error with its own class. All of them inherit from HandelsregisterError and carry statusCode, the response in response and the costs in meta.

Exception
Exception	Status	Meaning
AuthenticationError	401	Missing or invalid API key.
InsufficientCreditsError	402	Your balance is not enough for this request.
SubscriptionRequiredError	403	The request needs a higher plan. `requiredPlans` names the plans that fit.
NotFoundError	404	No matching company or person found.
RequestTimeoutError	408	The register did not answer in time. Nothing was charged.
RequestValidationError	400, 422	A parameter has an invalid value.
RateLimitError	429	Too many requests per minute.
ServerError	5xx	The data source is unavailable or overloaded right now. Retry later.

JavaScript

import {
  Handelsregister,
  HandelsregisterError,
  InsufficientCreditsError,
  NotFoundError,
  RequestTimeoutError,
} from 'handelsregister';

const client = new Handelsregister({ timeout: 120000 });

try {
  const company = await client.fetchOrganization({
    q: 'Hetzner Online GmbH',
    realtimeMode: true,
  });
} catch (error) {
  if (error instanceof NotFoundError) {
    console.log('No matching company found');
  } else if (error instanceof InsufficientCreditsError) {
    console.log('Not enough credits:', error.meta);
  } else if (error instanceof RequestTimeoutError) {
    console.log('The register is not answering right now, try again later');
  } else if (error instanceof HandelsregisterError) {
    console.log('Error:', error.statusCode, error.message);
  } else {
    throw error;
  }
}

On network errors, status 429 and server errors, the SDK retries on its own, with up to three attempts in total. If the API sends a wait time in Retry-After, it respects it.

By default, the client waits 90 seconds for a response. For Realtime, person profiles and documents, we recommend at least 120 seconds, that is timeout: 120000.

Command line

The package comes with the handelsregister program. It fetches company profiles, person profiles and documents, searches companies and enriches files.

Terminal

# Company profile without AI Mode, with Financial KPIs only
npx handelsregister fetch "Hetzner Online GmbH" --no-ai-search --feature financial_kpi

# Save the shareholder list as a PDF
npx handelsregister document "Hetzner Online GmbH" --type shareholders_list --output hetzner.pdf

Without further options, handelsregister fetch turns on AI Mode. A request then costs 25 credits instead of 5, even without features. With --no-ai-search, you request without AI Mode.

handelsregister document first looks up the company through a company profile without AI Mode. So 5 credits are added to the 15 credits of the document.

Reference

The full reference with all methods is in the repository’s README. The SDK covers the whole API:

Company profiles with all features, also as a Company class
Person profiles, also as a Person class
Search & Export with filters, sorting and automatic paging
Documents as files
Signals, Monitoring and webhook endpoints, with webhook signature verification
Account, balance, usage and API keys
Enrichment of whole CSV, JSON and Excel files

The SDK is licensed under AGPL-3.0. You find the source code on GitHub and the package on npm.

fetch-organization All parameters, features and fields of the company profile. Python SDK The same API from Python.