Basic concepts

The parameter q of fetch-organization takes three kinds of input. The examples on this page are requests for Hetzner Online GmbH, Ansbach HRB 6089:

The register number alone is not enough, because each register court assigns its own numbers. The order, on the other hand, is free: in the example, HRB 6089 Ansbach finds the same company.

If the API finds no company, it responds with 404 and charges nothing. For fuzzy input, there is AI Mode (ai_search=on-default): it also finds the company from parts of the name and researches it on the web. It costs 20 extra credits, even if it finds no company. To get several candidates at once, use Search & Export.

Every company profile contains the basic data, including name, legal form, status, register entry, address, purpose, industry, capital and representation rules. You request everything else as a feature, for example related_persons for the managing directors or financial_kpi for the Financial KPIs.

You pass several features with a repeated feature or as a list: features=related_persons,financial_kpi. Each feature appears in the response under its own key. Only publications is called history there.

The API ignores unknown names without an error message, so check the spelling. Features that your plan does not include are left out and not charged.

All features with their prices are listed in fetch-organization, every field in the Data catalog.

Data requests cost credits. For a company profile, these rules apply:

• The base price of 5 credits applies when the API returns a company.
• A feature costs credits only when it returns data in the response. An empty feature is free, including insolvency_publications without entries.
• Realtime and AI Mode are not features but surcharges with their own rules:
  • Realtime costs 10 extra credits as soon as the live fetch succeeds. This also applies when it shows nothing new.
  • AI Mode costs 20 extra credits, even if it finds no company. The surcharge is waived only when the API aborts the request with 408 because it takes too long.
• All other errors cost nothing.

The rule for each individual feature is in Billing, the prices in fetch-organization.

An example: the basic data with related_persons and financial_kpi costs 5 + 2 + 1 = 8 credits if both features return data.

Before each request, the API checks whether your balance covers the highest possible price. If it does not, the API responds with 402 and charges nothing. What was actually charged is in meta.request_credit_cost, your balance afterwards in meta.credits_remaining.

You get credits as start credits, every month with a credit subscription, or once as top-up credits. Without a credit subscription, start credits and top-up credits are valid for 30 days; with an active subscription, they do not expire. Everything else is in Billing.

By default, the company profile comes from our database. How current a piece of information is depends on its source.

We keep basic data, people and register notices up to date in our database from the register. This is fast and enough for most purposes.

With Realtime (realtime_mode=handelsregister-default), the API fetches the Aktueller Abdruck (AD, current printout) live from the Handelsregister (commercial register) at the moment of your request and returns it as JSON. You also get the currently registered people in related_persons.current, without paying for the feature.

Whether the live fetch worked is shown in _realtime_mode.status. We charge the 10 credits for Realtime only on success.

If the live fetch fails, the API returns the stored data from our database. You can tell by _realtime_mode.status, which is then not success. Realtime is then not charged, as meta.request_credit_cost also shows.

Realtime is worth it when today’s state matters. For example, you check new business partners before signing, or see who may represent the company right now.

We look for newly published annual financial statements every day. Companies, however, have up to twelve months after the end of the financial year to publish them (§ 325 HGB), and many use the full deadline. Some companies deliberately miss the legal deadline and publish even later.

The latest statement therefore often covers the year before last. More in Freshness.

The insolvency courts usually publish their notices on the day of the decision or shortly after. You get them through the feature insolvency_publications, each with court, case number and date.

The feature news returns news about the company from the web, with title, source, date and link. How current it is depends on when the company was last reported on. For small companies, there are often only a few matching reports.

Many details change over time. The API therefore returns the current state and the history side by side:

• current is the state as of today.
• history lists every registered state with effective_from and effective_to. If effective_to is null, the state is still valid today.
• People are in related_persons.current and related_persons.past, each with start_date and end_date.

Every detail with a history comes from the registers and publications, for example from the Chronologischer Abdruck (CD, chronological printout) of the Handelsregister or from all published annual financial statements.

This is how it looks in our example for the representation rules of Hetzner Online GmbH. In the example response, they name the management board until July 28, 2015, and the managing directors since then:

Most dates come in the format YYYY-MM-DD. How far back the history goes is described in Age and history.

Not every company has a value for every field. The API shows this in two ways:

• null: there is no value for this field.
• []: the list has no entries, for example no insolvency notices.

A requested feature without data comes as null or [] and costs nothing.

In your code, treat a missing key, null and [] the same, because some empty objects come as []. Also read fields by their names, because the order of the keys is not fixed.

If a value is missing, the company usually does not have to publish it at all. What the law requires depending on legal form and size is described in Data availability. We deliberately withhold some details; they then carry redacted: true.

The API grows additively. New data and features arrive as new fields. We never remove existing fields, we do not rename them, and we change neither their type nor their meaning. This keeps every version backward compatible.

Changes that would break existing code only come in a new API version, for example under /v2. The current version runs under /v1.

So let your client ignore unknown fields and treat unknown values as a general case. New fields and features are listed in the Changelog.

You can use Company profile, Documents, Search & Export and Signals with every account, even without a credit subscription. A credit subscription brings new credits every month and unlocks more data:

The API leaves out features outside your plan without an error and does not charge them. It rejects person profiles and search filters outside your plan with 403, also at no cost. For Signals, this applies to topics you request explicitly; without that, you simply get all topics of your plan.

You find the prices and credits of the plans on the pricing page.