API documentation

Introduction

German insolvency courts publish every step of a proceeding on the official portal insolvenzbekanntmachungen.de: protective measures, the opening, dismissals for lack of assets, distribution lists, discharge of residual debt. The portal is built for looking up single cases, not for processing data. It has no interface, no export and deletes announcements after statutory periods.

The API closes that gap. We collect every new announcement on the day of publication, normalise court, federal state, register number and filing type, link it to a company profile and make it available as JSON or CSV. Credit insurers, collection agencies, law firms, trade credit teams and data journalists use it to feed their own systems with it.

All requests go to https://germanyinsolvencies.com/api/v1. The API speaks HTTPS only, accepts JSON and answers with JSON. There is no mandatory SDK: any language that can send an HTTP request is enough. The examples on this page use curl, Python and Node.

Access

There is deliberately no self-service sign-up. We enable keys by hand because insolvency data includes personal data and we want to know what an integration is for. In practice that is one short message and one business day.

Use the contact form or write to [email protected] and mention four things:

• What you want to build, in two or three sentences.
• Which filing types and regions you need.
• Roughly how many requests or checked companies per month.
• Whether you can receive webhooks or would rather poll.

You then receive a personal key that works immediately on all endpoints your contract covers. An account may hold several active keys, so a key can be rotated without downtime.

Authentication

Every request carries the key in the X-API-Key header. Alternatively the API accepts the same key as a bearer token in the Authorization header, which is handy for tools that only know that header.

X-API-Key: YOUR_API_KEY

# equivalent
Authorization: Bearer YOUR_API_KEY

Without a key the API answers 401 missing_api_key. An unknown or disabled key returns 403 invalid_api_key, and an expired subscription returns 403 subscription_expired. The reason is always in the error field of the response.

Treat the key like a password: use it only on the server side, never in frontend code, never in a public repository. If a key leaks, tell us and we revoke it at once and issue a new one.

Quickstart

The most common request is also the simplest: all openings, protective measures and dismissals of one day. One call, no pagination, the answer comes within a second.

curl -H "X-API-Key: $INSOLVENCY_API_KEY" \
  "https://germanyinsolvencies.com/api/v1/filings?date=2026-09-28&types=eroeffnung,sicherung,abweisung"

Without a date the API returns the previous day. That makes a daily job trivial: a cron entry shortly after 6 am fetches yesterday's filings and writes them into your system. Courts publish on working days, so on Sundays and public holidays the result is usually empty or very short.

For a historical backfill you walk through the period in windows of at most 31 days:

import os, datetime, requests

API = "https://germanyinsolvencies.com/api/v1"
HEAD = {"X-API-Key": os.environ["INSOLVENCY_API_KEY"]}

# Backfill a quarter in 31-day windows, then keep running daily.
start, end = datetime.date(2026, 7, 1), datetime.date(2026, 9, 28)
day = start
while day <= end:
    stop = min(day + datetime.timedelta(days=30), end)
    r = requests.get(API + "/filings", headers=HEAD, params={
        "date_from": day.isoformat(),
        "date_to": stop.isoformat(),
        "types": "eroeffnung,abweisung",
    }, timeout=60)
    r.raise_for_status()
    for f in r.json()["filings"]:
        print(f["date"], f["aktenzeichen"], f["name"])
    day = stop + datetime.timedelta(days=1)

Endpoints at a glance

Paths are relative to https://germanyinsolvencies.com/api. The full address of the first endpoint is therefore https://germanyinsolvencies.com/api/v1/filings.

Retrieve filings

GET /v1/filings is the core of the API. It returns every announcement published in the requested period, sorted by date of publication and, within a day, in the order of publication.

The response contains the effective period, the requested type codes, the number of hits and the array of announcements. A period is always returned in one piece, there is no pagination on this endpoint. Even busy days stay well below a megabyte.

{
  "date_from": "2026-09-28",
  "date_to": "2026-09-28",
  "types": ["0", "1", "2"],
  "count": 142,
  "filings": [
    {
      "id": "fil_8Kq2Zp4RwT",
      "date": "2026-09-28",
      "type": "Eröffnungen",
      "type_code": "2",
      "name": "Musterbau GmbH",
      "sitz": "Berlin",
      "court": "Charlottenburg (Berlin)",
      "aktenzeichen": "36a IN 4711/26",
      "bundesland": "Berlin",
      "register": "HRB 123456 B",
      "company_id": "cmp_3n8Kd2ZpQv",
      "text": "Amtsgericht Charlottenburg (Berlin), Aktenzeichen: 36a IN 4711/26 ..."
    }
  ]
}

The same request in Node, filtered to Bavaria:

const url = new URL("https://germanyinsolvencies.com/api/v1/filings");
url.searchParams.set("types", "eroeffnung");
url.searchParams.set("bundesland", "Bayern");

const res = await fetch(url, {
  headers: { "X-API-Key": process.env.INSOLVENCY_API_KEY },
});
if (!res.ok) throw new Error((await res.json()).error);

const { count, filings } = await res.json();
console.log(count, "openings in Bavaria yesterday");

A single announcement with full text is returned by GET /v1/filings/{id}. The ID stays stable, so you can store it and use it later to check whether an announcement has already been processed.

curl -H "X-API-Key: $INSOLVENCY_API_KEY" \
  https://germanyinsolvencies.com/api/v1/filings/fil_8Kq2Zp4RwT

Filing types

Insolvency courts sort their announcements into nine subjects. The API accepts both the numeric code and a readable alias in the types parameter. Plurals and spellings with umlauts are also accepted (eroeffnungen, eröffnung).

The official name of the type is returned in German in the type field, exactly as the court publishes it. For machine processing use type_code, which never changes. An unknown value in types returns 400 bad_type together with the list of allowed codes.

The filing object

All text fields are UTF-8. Names and texts are passed on exactly as the court wrote them, including typing errors. Normalised values are only found in the fields that are explicitly normalised: type_code, bundesland and company_id.

The combination of court and case number identifies a proceeding. A proceeding typically produces several announcements over months or years: protective measures, opening, decisions, distribution list, termination. If you want to follow a proceeding, group by court plus aktenzeichen.

CSV export

With format=csv the API returns the same data as a CSV file instead of JSON: one line per announcement, header row, comma as separator, UTF-8. The file comes with Content-Disposition: attachment and a file name containing the period.

curl -H "X-API-Key: $INSOLVENCY_API_KEY" \
  -o filings.csv \
  "https://germanyinsolvencies.com/api/v1/filings?date_from=2026-09-01&date_to=2026-09-28&format=csv"

date,type,type_code,name,sitz,court,aktenzeichen,bundesland,register,text
2026-09-28,Eröffnungen,2,Musterbau GmbH,Berlin,Charlottenburg (Berlin),36a IN 4711/26,Berlin,HRB 123456 B,"Amtsgericht Charlottenburg ..."
2026-09-28,Sicherungsmaßnahmen,0,Beispiel Logistik UG (haftungsbeschränkt),Hamburg,Hamburg,67c IN 812/26,Hamburg,HRB 98765,"Amtsgericht Hamburg ..."

The full text in the text column contains line breaks and is therefore enclosed in quotes. Excel opens the file correctly via "Data, from text/CSV" with UTF-8 encoding; a plain double-click can mangle umlauts depending on the system settings.

Companies

Announcements are about proceedings, but most use cases are about companies. That is why each announcement is matched to a company profile where possible, using the register number, the name and the registered seat. GET /v1/companies searches these profiles.

curl -G -H "X-API-Key: $INSOLVENCY_API_KEY" \
  https://germanyinsolvencies.com/api/v1/companies \
  --data-urlencode "q=Musterbau" \
  --data-urlencode "bundesland=Berlin" \
  -d limit=20

Search parameters are q (name, at least three characters), register, city, bundesland, status and industry. Lists are returned in pages of at most 100 entries with a cursor:

{
  "object": "list",
  "data": [ { "id": "cmp_3n8Kd2ZpQv", "object": "company", "...": "..." } ],
  "has_more": true,
  "next_cursor": "eyJpZCI6ImNtcF8zbjhLZDJacFF2In0"
}

As long as has_more is true, pass next_cursor as the cursor parameter of the next request. A cursor stays valid for 24 hours.

The company object

{
  "id": "cmp_3n8Kd2ZpQv",
  "object": "company",
  "name": "Musterbau GmbH",
  "legal_form": "GmbH",
  "register": "HRB 123456 B",
  "register_court": "Charlottenburg (Berlin)",
  "city": "Berlin",
  "bundesland": "Berlin",
  "industry": "Hochbau",
  "status": "opened",
  "first_filing": "2026-08-14",
  "last_filing": "2026-09-28",
  "filings_count": 3,
  "website": "https://musterbau.example",
  "url": "https://germanyinsolvencies.com/company/musterbau-gmbh-berlin/"
}

Status values

The status is derived from the most recent relevant announcement of the proceeding. It is a practical summary, not a legal assessment: in case of doubt the full text of the announcement applies.

GET /v1/companies/{id}/filings returns all announcements of a company, oldest first. This gives you the full history of a proceeding without searching by case number yourself.

Balance sheet figures

For corporations the annual accounts filed with the company register are often available. GET /v1/companies/{id}/financials returns the key figures of the last fiscal years, newest first. Amounts are in whole euros.

{
  "company_id": "cmp_3n8Kd2ZpQv",
  "currency": "EUR",
  "statements": [
    {
      "fiscal_year_to": "2024-12-31",
      "bilanzsumme": 4820000,
      "eigenkapital": -310000,
      "verbindlichkeiten": 5130000,
      "jahresueberschuss": -1240000,
      "source": "Unternehmensregister"
    },
    {
      "fiscal_year_to": "2023-12-31",
      "bilanzsumme": 5410000,
      "eigenkapital": 930000,
      "verbindlichkeiten": 4480000,
      "jahresueberschuss": 85000,
      "source": "Unternehmensregister"
    }
  ]
}

Small companies only have to publish an abridged balance sheet. Fields that are not included in the filing are null and never estimated. The annual net income is often missing for that reason.

Typical use: in a credit decision, the development of equity over the last two or three fiscal years tells you more than the insolvency announcement alone. Negative equity combined with a protective measure is a clear picture.

Counterparty check

POST /v1/check checks a whole list of customers or suppliers in one call. You send your own reference and whatever you know about the company: name, city, register number. The API returns a match and the proceeding status for each entry.

curl https://germanyinsolvencies.com/api/v1/check \
  -H "X-API-Key: $INSOLVENCY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "since": "2025-01-01",
    "items": [
      { "ref": "D-10023", "name": "Musterbau GmbH", "city": "Berlin" },
      { "ref": "D-10024", "register": "HRB 98765", "register_court": "Hamburg" },
      { "ref": "D-10025", "name": "Nordlicht Handels GmbH" }
    ]
  }' 

{
  "checked": 3,
  "hits": 1,
  "results": [
    {
      "ref": "D-10023",
      "match": "exact",
      "company_id": "cmp_3n8Kd2ZpQv",
      "status": "opened",
      "last_filing": { "id": "fil_8Kq2Zp4RwT", "date": "2026-09-28", "type_code": "2" }
    },
    { "ref": "D-10024", "match": "none" },
    { "ref": "D-10025", "match": "ambiguous", "candidates": 2 }
  ]
}

A call accepts up to 500 entries. since limits the search to announcements from that date, default is three years back. For larger portfolios we recommend the watchlist: check once, then only receive changes.

Watchlist

The watchlist turns a one-off check into continuous monitoring. You add companies, and as soon as a new announcement appears for one of them you receive a watchlist.match event by webhook. Entries can be identified by company_id, by register number and court, or by name and city.

curl https://germanyinsolvencies.com/api/v1/watchlist \
  -H "X-API-Key: $INSOLVENCY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "register": "HRB 123456 B", "register_court": "Charlottenburg (Berlin)", "ref": "D-10023" }' 

{
  "id": "wl_Q7m2Lx9Pd",
  "object": "watchlist_entry",
  "ref": "D-10023",
  "company_id": "cmp_3n8Kd2ZpQv",
  "name": "Musterbau GmbH",
  "created_at": "2026-09-29T08:12:44Z",
  "last_match": null
}

Companies that have never been insolvent can also be watched. The entry then waits until the first announcement appears, which is exactly the point. Your own reference in ref comes back in every event, so you can assign a hit to your customer number without an extra lookup.

GET /v1/watchlist lists all entries with the date of the last hit, DELETE /v1/watchlist/{id} removes one. The same watchlist is visible in your Germany Insolvencies dashboard, changes are synchronised both ways.

Webhooks

Instead of polling you can have events pushed. Register an HTTPS endpoint and choose the events, optionally with the same filters as for /v1/filings.

curl https://germanyinsolvencies.com/api/v1/webhooks \
  -H "X-API-Key: $INSOLVENCY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/hooks/insolvency",
    "events": ["watchlist.match", "filing.published"],
    "filter": { "types": ["eroeffnung", "sicherung"], "bundesland": ["Bayern", "Hessen"] }
  }' 

{
  "id": "evt_5Tg8Nw2Ka",
  "type": "watchlist.match",
  "created_at": "2026-09-29T06:05:11Z",
  "data": {
    "watchlist_entry": { "id": "wl_Q7m2Lx9Pd", "ref": "D-10023" },
    "filing": {
      "id": "fil_8Kq2Zp4RwT",
      "date": "2026-09-28",
      "type": "Eröffnungen",
      "type_code": "2",
      "name": "Musterbau GmbH",
      "court": "Charlottenburg (Berlin)",
      "aktenzeichen": "36a IN 4711/26"
    }
  }
}

Every call is signed. The X-Webhook-Signature header contains a timestamp and an HMAC-SHA256 over timestamp and raw body, calculated with the secret you receive when registering.

X-Webhook-Signature: t=1790661911,v1=7f2c1d9a4b6e8035c1f7a29d4e5b0c8371a6d2f94e8b3c07a15d9e2f6b4c8a01

import hashlib, hmac, os, time
from flask import Flask, request, abort

app = Flask(__name__)
SECRET = os.environ["INSOLVENCY_WEBHOOK_SECRET"].encode()

@app.post("/hooks/insolvency")
def hook():
    header = request.headers.get("X-Webhook-Signature", "")
    parts = dict(p.split("=", 1) for p in header.split(",") if "=" in p)
    signed = parts.get("t", "") + "." + request.get_data(as_text=True)
    expected = hmac.new(SECRET, signed.encode(), hashlib.sha256).hexdigest()
    if not hmac.compare_digest(expected, parts.get("v1", "")):
        abort(400)
    if abs(time.time() - int(parts["t"])) > 300:
        abort(400)  # replay protection

    event = request.get_json()
    if event["type"] == "watchlist.match":
        ref = event["data"]["watchlist_entry"]["ref"]
        print("Customer", ref, "has a new insolvency filing")
    return "", 204

Answer with a 2xx status within ten seconds. If that fails, we retry with increasing intervals over 24 hours, eight times in total. Events can arrive twice, so use the id of the event to discard duplicates.

Statistics

GET /v1/stats returns counts instead of individual announcements. This is the endpoint for dashboards, reports and journalistic evaluations, because it does not require downloading and counting thousands of records.

curl -G -H "X-API-Key: $INSOLVENCY_API_KEY" \
  https://germanyinsolvencies.com/api/v1/stats \
  -d date_from=2026-07-01 -d date_to=2026-09-28 \
  -d group_by=month,bundesland -d types=eroeffnung

{
  "date_from": "2026-07-01",
  "date_to": "2026-09-28",
  "group_by": ["month", "bundesland"],
  "rows": [
    { "month": "2026-07", "bundesland": "Bayern",  "count": 318 },
    { "month": "2026-07", "bundesland": "Berlin",  "count": 204 },
    { "month": "2026-08", "bundesland": "Bayern",  "count": 297 }
  ],
  "total": 8412
}

group_by accepts day, week, month, bundesland, court, type and legal_form, up to two at once. The same filters as for /v1/filings apply. Unlike filings, the period here may cover up to 24 months.

Reference data

Two small endpoints return the valid values for filters. They change rarely and may be cached for a day.

[
  { "code": "0", "alias": "sicherung",   "name": "Sicherungsmaßnahmen" },
  { "code": "1", "alias": "abweisung",   "name": "Abweisungen mangels Masse" },
  { "code": "2", "alias": "eroeffnung",  "name": "Eröffnungen" }
]

GET /v1/courts returns all insolvency courts with the exact spelling expected by the court filter and the federal state. GET /v1/account shows your contract scope, the active limits and the consumption in the current month.

Errors

Errors come back as JSON with a matching HTTP status. The error field is machine-readable and stable, message explains the problem for humans and may change.

{
  "error": "range_too_large",
  "message": "Maximum range is 31 days per request."
}

{
  "error": "bad_type",
  "message": "Unknown type 'eroffnung'.",
  "allowed": ["0", "1", "2", "3", "4", "5", "6", "7", "8"]
}

Limits

Every response carries the current state of the rate limit in its headers. If you exceed it you receive 429 rate_limited and a Retry-After header in seconds.

X-RateLimit-Limit: 120
X-RateLimit-Remaining: 117
X-RateLimit-Reset: 1790661960
Retry-After: 12

Versioning

The major version is part of the path (/v1/). Within a major version we only make additive changes: new endpoints, new optional parameters, new fields in responses. Your client should therefore ignore unknown fields instead of failing on them.

Changes that could break existing integrations only happen in a new major version. The previous version then keeps running for at least twelve months, and we inform every key holder by email beforehand. The version date of the response is in the X-API-Version header.

X-API-Version: 2026-09-01

Data sources and timeliness

The only source for announcements is the official joint portal of the federal states, insolvenzbekanntmachungen.de, on which all German insolvency courts publish under section 9 of the Insolvency Code. We do not add announcements from other sources and do not change their content.

Courts publish on working days, mostly overnight and in the morning. New announcements are usually available in the API before 7 am on the following morning. Company profiles and register numbers are enriched from the company register; balance sheet figures come from the annual accounts published there.

Matching announcements to companies is automated. With a register number it is reliable; without one (sole traders, very common names) mistakes are possible. That is why company_id can be null, and that is why the counterparty check distinguishes between exact and probable.

Data protection and permitted use

Insolvency announcements are public, but they contain personal data, especially in consumer proceedings. Their use is subject to the GDPR and to the deletion periods of the Insolvency Announcement Ordinance. We therefore delete announcements from the API at the latest when the official portal has to delete them, and GET /v1/filings/{id} then returns 404 not_found.

Please mirror that deletion in your own systems. A regular comparison via the IDs you have stored is enough: whatever the API no longer knows should no longer be in your database either.

Permitted uses are the assessment of business risks, receivables management, legal advice, research and journalism. Not permitted: publishing announcements about private individuals, reselling the raw data and decisions about natural persons that are based solely on this data. If you process personal data on our behalf, a data processing agreement is available.

Support

Questions about the integration, higher limits or additional fields: [email protected] or the contact form. For technical problems please include the time of the request and the first characters of your key, then we can find the request in the logs straight away.

If you want to connect AI agents rather than write HTTP clients, the same data is available through a Model Context Protocol server, documented at MCP server. Both share keys, limits and contract.