Kundenbestand mit Insolvenzen abgleichen

Zugang und Limits

Jede Anfrage braucht einen API-Schlüssel im Authorization-Header. Schlüssel erzeugen Sie im Dashboard unter API-Zugang; er wird nur einmal angezeigt — behandeln Sie ihn wie ein Passwort.

Authorization: Bearer imk_<ihr-api-schlüssel>
Content-Type: application/json

Jeder Aufruf zählt als eine Anfrage, unabhängig davon, wie viele Kunden er enthält. Auf API Standard wird bei Überschreiten des Minutenlimits nichts blockiert, nur der Header X-RateLimit-Burst: limited gesetzt.

Anfrage

{
  "since": "2026-01-01",          // optional
  "min_confidence": 0.85,          // optional
  "customers": [                  // Pflicht
    {
      "ref": "crm-1001",          // optional, wird zurückgegeben
      "name": "Muster Bau GmbH",  // Pflicht
      "zip": "50667",             // optional, 5-stellige PLZ
      "hr": "HRB 12345",          // optional
      "court": "Amtsgericht Köln",// optional
      "case_number": "71 IN 123/26" // optional
    }
  ]
}

Antwort

Status 200 OK. results steht in derselben Reihenfolge wie customers.

{
  "since": "2026-01-01",
  "results": [
    {
      "ref": "crm-1001",
      "status": "match",
      "matches": [
        {
          "confidence": 0.972,
          "match_basis": "fuzzy_name",
          "debtor_name": "Muster Bau GmbH",
          "location": "Köln",
          "court": "Amtsgericht Köln",
          "case_number": "71 IN 123/26",
          "category": "Eröffnungen",
          "publication_date": "2026-03-14",
          "notice_text": "Amtsgericht Köln, Aktenzeichen 71 IN 123/26 ...",
          "bundesland": "Nordrhein-Westfalen",
          "branche": "Baugewerbe & Handwerk (Inkl. Baunebengewerbe)",
          "insolvency_id": 1839201,
          "company_page_url": "https://insolvenzmonitor.online/insolvenz/muster-bau-gmbh-koeln-hrb-12345"
        }
      ]
    },
    { "ref": "crm-1002", "status": "no_match", "matches": [] }
  ]
}

So funktioniert der Abgleich

Für jeden Kunden wird zuerst eine Kandidatenmenge aus rund vier Millionen Bekanntmachungen gezogen, dann wird jeder Kandidat bewertet. Die Bewertung ist eine Kaskade; die erste zutreffende Stufe gewinnt.

Kandidatenauswahl

Kandidaten sind Bekanntmachungen ab since, deren Schuldnername mit einem Wort Ihres Kundennamens beginnt (Umlaute und ihre Schreibweise mit ae/oe/ue werden beide berücksichtigt), und — falls eine zip übergeben wurde — in deren Text diese PLZ vorkommt. Neueste zuerst, einige hundert je Kunde.

Normalisierung

• Namen: Umlaute und ß aufgelöst (ä→ae, ö→oe, ü→ue, ß→ss), Akzente entfernt, kleingeschrieben. „Müller“ und „Mueller“ sind gleich.
• Aktenzeichen und Handelsregisternummern: alle Leerzeichen entfernt, kleingeschrieben — „HRB 12345“ wird „hrb12345“.
• Gerichte: Leerzeichen zusammengefasst, kleingeschrieben; Umlaute werden hier nicht aufgelöst.

Die Kaskade

1. 1
   Aktenzeichen und Gericht

   Beide stimmen nach Normalisierung exakt überein.

   1,00 · exact_case_court
2. 2
   Handelsregisternummer

   Die Nummer stimmt überein; stimmt zusätzlich das Gericht, steigt die Sicherheit auf 1,00.

   0,95 · exact_registration → 1,00 · exact_registration_court
3. 3
   Unscharfer Namensabgleich

   Der Namensscore erreicht mindestens min_confidence und wird selbst zur Trefferquote.

   Score · fuzzy_name
4. 4
   PLZ-Prüfung

   Nur für Namenstreffer: Wurde eine zip übergeben, muss sie als eigenständige fünfstellige Zahl im Text stehen, sonst wird der Treffer verworfen. Kein Bonus, nur bestanden oder nicht. Stufen 1–2 werden nie gefiltert.

   Filter

Stufe 3 im Detail

Handelsregisternummern

Die Suche läuft über den Namen; eine HR-Nummer allein bringt keinen Schuldner in die Kandidaten. Unter den gefundenen Kandidaten vergleicht Stufe 2 Ihre hr mit dem gespeicherten Registereintrag. Der ist oft mit dem Gericht davor gespeichert („Dortmund, HRB 29750“) — senden Sie die schlichte Form „HRB 29750“.

Beispiel

curl -sS -X POST "https://insolvenzmonitor.online/api/v1/match" \
  -H "Authorization: Bearer imk_ihr_schluessel" \
  -H "Content-Type: application/json" \
  -d '{
    "since": "2026-01-01",
    "customers": [
      { "ref": "crm-1001", "name": "Muster Bau GmbH", "zip": "50667", "hr": "HRB 12345" },
      { "ref": "crm-1002", "name": "Beispiel Handel GmbH", "zip": "80331" }
    ]
  }'

Die Antwort hat die oben gezeigte Form: ein Eintrag je Kunde in results, mit status und den Treffern.

Fehler

Fehler haben die Form { "error": { "code": "…", "message": "…" } }.

Empfehlungen für die Praxis

• Neuer Kunde: ein einzelner Kunde, since etwa ein Jahr zurück.
• Täglicher Lauf: den aktiven Bestand in Paketen zu 50 senden, since = heute − 5 Tage. Die Überlappung erfasst spät veröffentlichte Bekanntmachungen.
• PLZ mitsenden: Ohne zip erfolgt der Abgleich nur über den Namen, und gleichnamige Firmen aus anderen Orten kommen mit. hr und case_number zusätzlich, wann immer vorhanden.
• Treffer prüfen: Vor einer automatischen Reaktion debtor_name, location und category ansehen — die Trefferquote ist eine Wahrscheinlichkeit, keine Gewissheit.
• Liste soll im Haus bleiben? Dann laden Sie die Rohdaten über GET /api/v1/insolvencies und gleichen selbst ab.