API-documentatie

Inleiding

Duitse insolventierechtbanken publiceren elke stap van een procedure op het officiële portaal insolvenzbekanntmachungen.de: Sicherungsmaßnahmen, de opening, afwijzingen wegens gebrek aan boedel, verdelingslijsten en de kwijtschelding van restschulden. Het portaal is gebouwd om afzonderlijke zaken op te zoeken, niet om data te verwerken. Het heeft geen interface en geen export, en het verwijdert bekendmakingen na wettelijke termijnen.

De API vult dat gat. Wij verzamelen elke nieuwe bekendmaking op de dag van publicatie, normaliseren rechtbank, deelstaat, registernummer en soort melding, koppelen die aan een bedrijfsprofiel en stellen alles beschikbaar als JSON of CSV. Kredietverzekeraars, incassobureaus, advocatenkantoren, debiteurenafdelingen en datajournalisten gebruiken de API om hun eigen systemen te voeden.

Alle verzoeken gaan naar https://germanyinsolvencies.com/api/v1. De API spreekt uitsluitend HTTPS, accepteert JSON en antwoordt met JSON. Een SDK is niet verplicht: elke taal die een HTTP-verzoek kan versturen volstaat. De voorbeelden op deze pagina gebruiken curl, Python en Node.

Toegang

Er is bewust geen zelfregistratie. Wij activeren sleutels handmatig, omdat insolventiedata persoonsgegevens bevat en wij willen weten waarvoor een integratie dient. In de praktijk komt dat neer op één kort bericht en één werkdag.

Gebruik het contactformulier of schrijf naar [email protected] en noem vier punten:

• Wat u wilt bouwen, in twee of drie zinnen.
• Welke soorten meldingen en regio's u nodig hebt.
• Ongeveer hoeveel verzoeken of gecontroleerde bedrijven per maand.
• Of u webhooks kunt ontvangen of liever zelf opvraagt (polling).

Vervolgens ontvangt u een persoonlijke sleutel die direct werkt op alle endpoints die uw contract dekt. Een account kan meerdere actieve sleutels hebben, zodat een sleutel zonder downtime kan worden vervangen.

Authenticatie

Elk verzoek bevat de sleutel in de header X-API-Key. Als alternatief accepteert de API dezelfde sleutel als bearer-token in de header Authorization, handig voor tools die alleen die header kennen.

X-API-Key: YOUR_API_KEY

# equivalent
Authorization: Bearer YOUR_API_KEY

Zonder sleutel antwoordt de API met 401 missing_api_key. Een onbekende of gedeactiveerde sleutel levert 403 invalid_api_key op en een verlopen abonnement 403 subscription_expired. De reden staat altijd in het veld error van het antwoord.

Behandel de sleutel als een wachtwoord: gebruik hem alleen aan de serverkant, nooit in frontendcode en nooit in een openbare repository. Lekt een sleutel uit, laat het ons weten. Wij trekken hem dan direct in en geven u een nieuwe.

Quickstart

Het meest gebruikte verzoek is ook het eenvoudigste: alle openingen, beschermingsmaatregelen en afwijzingen van één dag. Eén aanroep, geen paginering, het antwoord komt binnen een seconde.

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

Zonder datum geeft de API de vorige dag terug. Dat maakt een dagelijkse taak triviaal: een cron-regel kort na 6 uur haalt de meldingen van gisteren op en schrijft ze naar uw systeem. Rechtbanken publiceren op werkdagen, dus op zondagen en feestdagen is het resultaat meestal leeg of zeer kort.

Voor een historische aanvulling loopt u de periode door in vensters van maximaal 31 dagen:

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 in het kort

Paden zijn relatief ten opzichte van https://germanyinsolvencies.com/api. Het volledige adres van het eerste endpoint is dus https://germanyinsolvencies.com/api/v1/filings.

Meldingen opvragen

GET /v1/filings is de kern van de API. Het geeft elke bekendmaking terug die in de gevraagde periode is gepubliceerd, gesorteerd op publicatiedatum en binnen een dag in volgorde van publicatie.

Het antwoord bevat de effectieve periode, de gevraagde typecodes, het aantal treffers en de array met bekendmakingen. Een periode wordt altijd in één keer teruggegeven, dit endpoint kent geen paginering. Ook drukke dagen blijven ruim onder een 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 ..."
    }
  ]
}

Hetzelfde verzoek in Node, gefilterd op Beieren:

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");

Een afzonderlijke bekendmaking met volledige tekst levert GET /v1/filings/{id}. De ID blijft stabiel, dus u kunt hem opslaan en later gebruiken om te controleren of een bekendmaking al is verwerkt.

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

Soorten meldingen

Insolventierechtbanken delen hun bekendmakingen in negen rubrieken in. De API accepteert in de parameter types zowel de numerieke code als een leesbare alias. Ook meervoudsvormen en spellingen met umlauten worden geaccepteerd (eroeffnungen, eröffnung).

De officiële naam van het type staat in het veld type in het Duits, precies zoals de rechtbank hem publiceert. Gebruik voor machinale verwerking type_code, die nooit verandert. Een onbekende waarde in types levert 400 bad_type op, samen met de lijst van toegestane codes.

Het meldingsobject

Alle tekstvelden zijn UTF-8. Namen en teksten worden doorgegeven zoals de rechtbank ze schreef, inclusief tikfouten. Genormaliseerde waarden vindt u alleen in de velden die uitdrukkelijk genormaliseerd zijn: type_code, bundesland en company_id.

De combinatie van rechtbank en zaaknummer identificeert een procedure. Een procedure levert doorgaans meerdere bekendmakingen op over maanden of jaren: beschermingsmaatregelen, opening, beslissingen, verdelingslijst, beëindiging. Wilt u een procedure volgen, groepeer dan op court plus aktenzeichen.

CSV-export

Met format=csv geeft de API dezelfde data terug als CSV-bestand in plaats van JSON: één regel per bekendmaking, kopregel, komma als scheidingsteken, UTF-8. Het bestand wordt geleverd met Content-Disposition: attachment en een bestandsnaam met de periode.

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

De volledige tekst in de kolom text bevat regeleinden en staat daarom tussen aanhalingstekens. Excel opent het bestand correct via "Gegevens, uit tekst/CSV" met UTF-8-codering. Gewoon dubbelklikken kan, afhankelijk van de systeeminstellingen, umlauten verminken.

Bedrijven

Bekendmakingen gaan over procedures, maar de meeste toepassingen gaan over bedrijven. Daarom wordt elke bekendmaking waar mogelijk gekoppeld aan een bedrijfsprofiel, op basis van registernummer, naam en statutaire zetel. GET /v1/companies doorzoekt die profielen.

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

Zoekparameters zijn q (naam, minstens drie tekens), register, city, bundesland, status en industry. Lijsten worden teruggegeven in pagina's van maximaal 100 items met een cursor:

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

Zolang has_more true is, geeft u next_cursor mee als parameter cursor van het volgende verzoek. Een cursor blijft 24 uur geldig.

Het bedrijfsobject

{
  "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/"
}

Statuswaarden

De status wordt afgeleid van de meest recente relevante bekendmaking van de procedure. Het is een praktische samenvatting, geen juridische beoordeling: bij twijfel geldt de volledige tekst van de bekendmaking.

GET /v1/companies/{id}/filings geeft alle bekendmakingen van een bedrijf terug, oudste eerst. Zo hebt u de volledige geschiedenis van een procedure zonder zelf op zaaknummer te zoeken.

Balanscijfers

Voor kapitaalvennootschappen zijn de bij het handelsregister gedeponeerde jaarrekeningen vaak beschikbaar. GET /v1/companies/{id}/financials geeft de kerncijfers van de laatste boekjaren terug, nieuwste eerst. Bedragen staan in hele euro's.

{
  "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"
    }
  ]
}

Kleine bedrijven hoeven slechts een verkorte balans te publiceren. Velden die niet in de deponering staan, zijn null en worden nooit geschat. Het jaarresultaat ontbreekt om die reden vaak.

Typisch gebruik: bij een kredietbeslissing zegt de ontwikkeling van het eigen vermogen over de laatste twee of drie boekjaren meer dan de insolventiebekendmaking alleen. Negatief eigen vermogen in combinatie met een beschermingsmaatregel is een duidelijk beeld.

Tegenpartijcontrole

POST /v1/check controleert een hele lijst klanten of leveranciers in één aanroep. U stuurt uw eigen referentie mee en wat u van het bedrijf weet: naam, plaats, registernummer. De API geeft per regel een overeenkomst en de status van de procedure terug.

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 }
  ]
}

Een aanroep accepteert tot 500 regels. since beperkt de zoekopdracht tot bekendmakingen vanaf die datum, standaard drie jaar terug. Voor grotere portefeuilles raden wij de watchlist aan: eenmaal controleren, daarna alleen nog wijzigingen ontvangen.

Watchlist

De watchlist maakt van een eenmalige controle continue monitoring. U voegt bedrijven toe en zodra er een nieuwe bekendmaking verschijnt voor een van hen, ontvangt u via webhook een watchlist.match-event. Items kunnen worden aangeduid met company_id, met registernummer en rechtbank, of met naam en plaats.

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
}

Ook bedrijven die nooit insolvent zijn geweest kunnen worden gevolgd. Het item wacht dan tot de eerste bekendmaking verschijnt, en dat is precies de bedoeling. Uw eigen referentie in ref komt in elk event terug, zodat u een treffer zonder extra opzoeking aan uw klantnummer kunt koppelen.

GET /v1/watchlist toont alle items met de datum van de laatste treffer, DELETE /v1/watchlist/{id} verwijdert er een. Dezelfde watchlist is zichtbaar in uw Germany Insolvencies-dashboard, wijzigingen worden in beide richtingen gesynchroniseerd.

Webhooks

In plaats van te pollen kunt u events laten pushen. Registreer een HTTPS-endpoint en kies de events, eventueel met dezelfde filters als bij /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"
    }
  }
}

Elke aanroep is ondertekend. De header X-Webhook-Signature bevat een tijdstempel en een HMAC-SHA256 over tijdstempel en ruwe body, berekend met het geheim dat u bij de registratie ontvangt.

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

Antwoord binnen tien seconden met een 2xx-status. Lukt dat niet, dan proberen wij het opnieuw met toenemende tussenpozen over 24 uur, in totaal acht keer. Events kunnen dubbel aankomen, gebruik daarom de id van het event om duplicaten te negeren.

Statistieken

GET /v1/stats geeft aantallen terug in plaats van afzonderlijke bekendmakingen. Dit is het endpoint voor dashboards, rapportages en journalistieke analyses, omdat u geen duizenden records hoeft te downloaden en te tellen.

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 accepteert day, week, month, bundesland, court, type en legal_form, maximaal twee tegelijk. Dezelfde filters als bij /v1/filings zijn van toepassing. Anders dan bij meldingen mag de periode hier tot 24 maanden beslaan.

Referentiedata

Twee kleine endpoints geven de geldige waarden voor filters terug. Ze veranderen zelden en mogen een dag worden gecachet.

[
  { "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 geeft alle insolventierechtbanken terug met de exacte spelling die het filter court verwacht, plus de deelstaat. GET /v1/account toont uw contractomvang, de actieve limieten en het verbruik in de lopende maand.

Fouten

Fouten komen terug als JSON met een passende HTTP-status. Het veld error is machineleesbaar en stabiel, message legt het probleem uit aan mensen en kan veranderen.

{
  "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"]
}

Limieten

Elk antwoord bevat in zijn headers de actuele stand van de rate limit. Overschrijdt u die, dan ontvangt u 429 rate_limited en een header Retry-After in seconden.

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

Versiebeheer

De hoofdversie maakt deel uit van het pad (/v1/). Binnen een hoofdversie maken wij alleen aanvullende wijzigingen: nieuwe endpoints, nieuwe optionele parameters, nieuwe velden in antwoorden. Uw client moet onbekende velden daarom negeren in plaats van erop te falen.

Wijzigingen die bestaande integraties kunnen breken, gebeuren alleen in een nieuwe hoofdversie. De vorige versie blijft dan minstens twaalf maanden draaien en wij informeren elke sleutelhouder vooraf per e-mail. De versiedatum van het antwoord staat in de header X-API-Version.

X-API-Version: 2026-09-01

Databronnen en actualiteit

De enige bron voor bekendmakingen is het officiële gezamenlijke portaal van de deelstaten, insolvenzbekanntmachungen.de, waarop alle Duitse insolventierechtbanken publiceren op grond van § 9 van de Duitse Insolvenzordnung (Insolvency Code). Wij voegen geen bekendmakingen uit andere bronnen toe en wijzigen hun inhoud niet.

Rechtbanken publiceren op werkdagen, meestal 's nachts en 's ochtends. Nieuwe bekendmakingen zijn meestal de volgende ochtend vóór 7 uur beschikbaar in de API. Bedrijfsprofielen en registernummers worden verrijkt vanuit het handelsregister; balanscijfers komen uit de daar gepubliceerde jaarrekeningen.

De koppeling van bekendmakingen aan bedrijven is geautomatiseerd. Met een registernummer is die betrouwbaar; zonder (eenmanszaken, zeer gangbare namen) zijn fouten mogelijk. Daarom kan company_id null zijn en daarom maakt de tegenpartijcontrole onderscheid tussen exact en probable.

Gegevensbescherming en toegestaan gebruik

Insolventiebekendmakingen zijn openbaar, maar bevatten persoonsgegevens, vooral bij consumentenprocedures. Het gebruik ervan valt onder de AVG en onder de verwijdertermijnen van de Duitse verordening inzake insolventiebekendmakingen (Insolvenzbekanntmachungsverordnung). Wij verwijderen bekendmakingen daarom uiterlijk uit de API wanneer het officiële portaal ze moet verwijderen, en GET /v1/filings/{id} geeft dan 404 not_found terug.

Neem die verwijdering over in uw eigen systemen. Een regelmatige vergelijking aan de hand van de opgeslagen ID's volstaat: wat de API niet meer kent, hoort ook niet meer in uw database te staan.

Toegestaan gebruik is de beoordeling van bedrijfsrisico's, debiteurenbeheer, juridisch advies, onderzoek en journalistiek. Niet toegestaan: bekendmakingen over particulieren publiceren, de ruwe data doorverkopen en beslissingen over natuurlijke personen nemen die uitsluitend op deze data berusten. Verwerkt u namens ons persoonsgegevens, dan is een verwerkersovereenkomst beschikbaar.

Support

Vragen over de integratie, hogere limieten of aanvullende velden: [email protected] of het contactformulier. Vermeld bij technische problemen het tijdstip van het verzoek en de eerste tekens van uw sleutel, dan vinden wij het verzoek meteen in de logs.

Wilt u AI-agents koppelen in plaats van HTTP-clients te schrijven, dan zijn dezelfde data beschikbaar via een Model Context Protocol-server, gedocumenteerd op MCP-server. Beide delen sleutels, limieten en contract.