Forderungen – API-Referenz

Finanzanalyse eines Kontakts

GET/api/v1/contacts/{id}/finances

Alle Forderungen des Kontakts mit Kosten (gesamt und erstattungsfähig), Zahlungen inkl. Raten, Restbetrag und Rückzahlungsquote. Grundlage der Gläubiger-KI.

Berechtigung: debts:read

Pfadparameter

idstringPflicht
ID der Ressource
max. 128 Zeichen

Antwort 200 · ContactFinances

object"contact_finances"Pflicht
contactIdstringPflicht
principalCentsintegerPflicht
Summe der Hauptforderungen
-100000000000–100000000000
totalCostsCentsintegerPflicht
Alle Kosten
-100000000000–100000000000
chargeableCostsCentsintegerPflicht
Erstattungsfähige Kosten (vom Schuldner zu tragen)
-100000000000–100000000000
adjustedCentsintegerPflicht
Hauptforderungen + erstattungsfähige Kosten
-100000000000–100000000000
paidCentsintegerPflicht
Zahlungen inkl. Raten
-100000000000–100000000000
remainingCentsintegerPflicht
adjustedCents − paidCents (mindestens 0)
-100000000000–100000000000
paymentPercentagenumberPflicht
Rückzahlungsquote in Prozent
0–100
isFullyPaidbooleanPflicht
debtsArray<object>Pflicht
- debtIdstringPflicht
- descriptionstringPflicht
- status"open" | "paid"Pflicht
- principalCentsintegerPflicht
  Betrag in Cent
  -100000000000–100000000000
- costsCentsintegerPflicht
  Betrag in Cent
  -100000000000–100000000000
- chargeableCostsCentsintegerPflicht
  Betrag in Cent
  -100000000000–100000000000
- paidCentsintegerPflicht
  Betrag in Cent
  -100000000000–100000000000
- openCentsintegerPflicht
  wie Forderung.openCents
  -100000000000–100000000000
- paymentsArray<object>Pflicht
  - idstringPflicht
  - type"single" | "installment"Pflicht
  - amountCentsintegerPflicht
    Betrag in Cent
    -100000000000–100000000000
  - datestring (date) | nullPflicht
    Datum (YYYY-MM-DD)
  - methodstringPflicht
- costsArray<object>Pflicht
  - idstringPflicht
  - amountCentsintegerPflicht
    Betrag in Cent
    -100000000000–100000000000
  - datestring (date) | nullPflicht
    Datum (YYYY-MM-DD)
  - costTypestringPflicht
  - descriptionstringPflicht
  - isPaidbooleanPflicht
  - isChargeablebooleanPflicht

Mögliche Fehler: 400, 401, 403, 404, 429, 500

curl 'https://www.debt-flow.io/api/v1/contacts/ID/finances' \
  -H "Authorization: Bearer $DEBTFLOW_API_KEY"

Antwort 200

{
  "object": "contact_finances",
  "contactId": "string",
  "principalCents": 0,
  "totalCostsCents": 0,
  "chargeableCostsCents": 0,
  "adjustedCents": 0,
  "paidCents": 0,
  "remainingCents": 0,
  "paymentPercentage": 0,
  "isFullyPaid": false,
  "debts": [
    {
      "debtId": "string",
      "description": "string",
      "status": "open",
      "principalCents": 0,
      "costsCents": 0,
      "chargeableCostsCents": 0,
      "paidCents": 0,
      "openCents": 0,
      "payments": [
        {
          "id": "string",
          "type": "single",
          "amountCents": 0,
          "date": null,
          "method": "string"
        }
      ],
      "costs": [
        {
          "id": "string",
          "amountCents": 0,
          "date": null,
          "costType": "string",
          "description": "string",
          "isPaid": false,
          "isChargeable": false
        }
      ]
    }
  ]
}

Forderungen auflisten

GET/api/v1/debts

Mit Beträgen in Cent (Hauptforderung, Kosten, Zahlungen inkl. Raten, offen), Phase und Fälligkeit. Neueste zuerst.

Berechtigung: debts:read

Query-Parameter

contactIdstring
max. 128 Zeichen
clientIdstring
max. 128 Zeichen
status"open" | "paid" | "all"
Standard: "all"
phaseenum
Werte: new, reminder1, reminder2, reminder3, waiting, paymentplan, court, titled, enforcement, completed
overdue"true" | "false"
limitinteger
Anzahl Einträge (1–100)
1–100 · Standard: 25
cursorstring
`nextCursor` der vorherigen Seite
max. 500 Zeichen

Antwort 200

object"list"Pflicht
dataArray<Debt>Pflicht
- idstringPflicht
- object"debt"Pflicht
- contactIdstringPflicht
- contactNamestringPflicht
- clientIdstring | nullPflicht
- descriptionstringPflicht
- referencestringPflicht
- source"manual" | "invoice"Pflicht
  invoice = aus einer Rechnung ans Mahnwesen übergeben
- invoiceIdstring | nullPflicht
  Rechnung, aus der die Forderung stammt – Zahlungen werden abgeglichen
- invoiceNumberstring | nullPflicht
- currency"EUR"Pflicht
- principalCentsintegerPflicht
  Hauptforderung
  -100000000000–100000000000
- costsCentsintegerPflicht
  Summe der Kosten
  -100000000000–100000000000
- paidCentsintegerPflicht
  Summe der Zahlungen inkl. Raten
  -100000000000–100000000000
- openCentsintegerPflicht
  Offen: Hauptforderung + Kosten − Zahlungen (0 wenn bezahlt)
  -100000000000–100000000000
- status"open" | "paid"Pflicht
- overduebooleanPflicht
- dueDatestring (date) | nullPflicht
  Datum (YYYY-MM-DD)
- paidAtstring (date-time) | nullPflicht
  Zeitpunkt (ISO 8601)
- phaseenumPflicht
  Werte: new, reminder1, reminder2, reminder3, waiting, paymentplan, court, titled, enforcement, completed
- courtStatus"pending" | "objection" | "hearing" | "judgment" | "appeal" | nullPflicht
- enforcementStatusenum | nullPflicht
  Werte: monitoring, asset_disclosure, bank_attachment, property_attachment, wage_attachment, vehicle_attachment, completed
- isTitledbooleanPflicht
  Vollstreckungstitel liegt vor (Kennzeichen; Details in `title`)
- inCourtbooleanPflicht
  Gerichtsverfahren läuft (Kennzeichen)
- reminderLevelintegerPflicht
  0–3
- followUpDatestring (date) | nullPflicht
  Wiedervorlage
- autoPostalboolean | nullPflicht
  Mahnungen automatisch per Post (null = Voreinstellung)
- notesstringPflicht
- titleDebtTitle | nullPflicht
  - typeenumPflicht
    Werte: vollstreckungsbescheid, urteil, versaeumnisurteil, vergleich, kostenfestsetzungsbeschluss, notarielle_urkunde, sonstiger
  - courtstring
    max. 200 Zeichen
  - fileNumberstring
    Aktenzeichen
    max. 80 Zeichen
  - datestring (date)
    Datum (YYYY-MM-DD)
  - servedAtstring (date)
    Zustellung
  - enforceableAtstring (date)
    Vollstreckbare Ausfertigung
  - notesstring
    max. 2000 Zeichen
- interestDebtInterestPflicht
- hasInstallmentPlanbooleanPflicht
- lastReminderSentAtstring (date-time) | nullPflicht
  Zeitpunkt (ISO 8601)
- lastLetterSentAtstring (date-time) | nullPflicht
  Zeitpunkt (ISO 8601)
- createdAtstring (date-time)Pflicht
  Zeitpunkt (ISO 8601)
- updatedAtstring (date-time)Pflicht
  Zeitpunkt (ISO 8601)
hasMorebooleanPflicht
nextCursorstring | nullPflicht

Mögliche Fehler: 400, 401, 403, 429, 500

curl 'https://www.debt-flow.io/api/v1/debts' \
  -H "Authorization: Bearer $DEBTFLOW_API_KEY"

Antwort 200

{
  "object": "list",
  "data": [
    {
      "id": "string",
      "object": "debt",
      "contactId": "string",
      "contactName": "string",
      "clientId": "string",
      "description": "string",
      "reference": "string",
      "source": "manual",
      "invoiceId": "string",
      "invoiceNumber": "string",
      "currency": "EUR",
      "principalCents": 0,
      "costsCents": 0,
      "paidCents": 0,
      "openCents": 0,
      "status": "open",
      "overdue": false,
      "dueDate": "2026-11-01",
      "paidAt": "2026-11-01T09:30:00.000Z",
      "phase": "new",
      "courtStatus": "pending",
      "enforcementStatus": "monitoring",
      "isTitled": false,
      "inCourt": false,
      "reminderLevel": 0,
      "followUpDate": "2026-11-01",
      "autoPostal": false,
      "notes": "string",
      "title": {
        "type": null,
        "court": null,
        "fileNumber": null,
        "date": null,
        "servedAt": null,
        "enforceableAt": null,
        "notes": null
      },
      "interest": {
        "mode": null
      },
      "hasInstallmentPlan": false,
      "lastReminderSentAt": "2026-11-01T09:30:00.000Z",
      "lastLetterSentAt": "2026-11-01T09:30:00.000Z",
      "createdAt": "2026-11-01T09:30:00.000Z",
      "updatedAt": "2026-11-01T09:30:00.000Z"
    }
  ],
  "hasMore": false,
  "nextCursor": "string"
}

Forderung anlegen

POST/api/v1/debts

Neue Forderung in Phase new. Ereignis debt.created.

Berechtigung: debts:write

Header

Idempotency-Keystring
Eindeutiger Schlüssel (8–255 Zeichen). Wiederholte Anfragen mit gleichem Schlüssel liefern 24 h lang dieselbe Antwort.
max. 255 Zeichen

Body (JSON) · DebtCreate

contactIdstringPflicht
max. 128 Zeichen
amountCentsintegerPflicht
Hauptforderung in Cent
0–100000000000
descriptionstringPflicht
max. 1000 Zeichen
dueDatestring (date)Pflicht
Datum (YYYY-MM-DD)
referencestring
Rechnungs- oder Aktenzeichen
max. 100 Zeichen
clientIdstring
max. 128 Zeichen
notesstring
max. 10000 Zeichen
autoPostalboolean
interestDebtInterest

Antwort 201 · Debt

idstringPflicht
object"debt"Pflicht
contactIdstringPflicht
contactNamestringPflicht
clientIdstring | nullPflicht
descriptionstringPflicht
referencestringPflicht
source"manual" | "invoice"Pflicht
invoice = aus einer Rechnung ans Mahnwesen übergeben
invoiceIdstring | nullPflicht
Rechnung, aus der die Forderung stammt – Zahlungen werden abgeglichen
invoiceNumberstring | nullPflicht
currency"EUR"Pflicht
principalCentsintegerPflicht
Hauptforderung
-100000000000–100000000000
costsCentsintegerPflicht
Summe der Kosten
-100000000000–100000000000
paidCentsintegerPflicht
Summe der Zahlungen inkl. Raten
-100000000000–100000000000
openCentsintegerPflicht
Offen: Hauptforderung + Kosten − Zahlungen (0 wenn bezahlt)
-100000000000–100000000000
status"open" | "paid"Pflicht
overduebooleanPflicht
dueDatestring (date) | nullPflicht
Datum (YYYY-MM-DD)
paidAtstring (date-time) | nullPflicht
Zeitpunkt (ISO 8601)
phaseenumPflicht
Werte: new, reminder1, reminder2, reminder3, waiting, paymentplan, court, titled, enforcement, completed
courtStatus"pending" | "objection" | "hearing" | "judgment" | "appeal" | nullPflicht
enforcementStatusenum | nullPflicht
Werte: monitoring, asset_disclosure, bank_attachment, property_attachment, wage_attachment, vehicle_attachment, completed
isTitledbooleanPflicht
Vollstreckungstitel liegt vor (Kennzeichen; Details in `title`)
inCourtbooleanPflicht
Gerichtsverfahren läuft (Kennzeichen)
reminderLevelintegerPflicht
0–3
followUpDatestring (date) | nullPflicht
Wiedervorlage
autoPostalboolean | nullPflicht
Mahnungen automatisch per Post (null = Voreinstellung)
notesstringPflicht
titleDebtTitle | nullPflicht
- typeenumPflicht
  Werte: vollstreckungsbescheid, urteil, versaeumnisurteil, vergleich, kostenfestsetzungsbeschluss, notarielle_urkunde, sonstiger
- courtstring
  max. 200 Zeichen
- fileNumberstring
  Aktenzeichen
  max. 80 Zeichen
- datestring (date)
  Datum (YYYY-MM-DD)
- servedAtstring (date)
  Zustellung
- enforceableAtstring (date)
  Vollstreckbare Ausfertigung
- notesstring
  max. 2000 Zeichen
interestDebtInterestPflicht
hasInstallmentPlanbooleanPflicht
lastReminderSentAtstring (date-time) | nullPflicht
Zeitpunkt (ISO 8601)
lastLetterSentAtstring (date-time) | nullPflicht
Zeitpunkt (ISO 8601)
createdAtstring (date-time)Pflicht
Zeitpunkt (ISO 8601)
updatedAtstring (date-time)Pflicht
Zeitpunkt (ISO 8601)

Mögliche Fehler: 400, 401, 403, 409, 422, 429, 500

curl -X POST 'https://www.debt-flow.io/api/v1/debts' \
  -H "Authorization: Bearer $DEBTFLOW_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
  "contactId": "string",
  "amountCents": 0,
  "description": "string",
  "dueDate": "2026-11-01",
  "reference": "string",
  "clientId": "string",
  "notes": "string",
  "autoPostal": false,
  "interest": {
    "mode": "none"
  }
}'

Antwort 201

{
  "id": "string",
  "object": "debt",
  "contactId": "string",
  "contactName": "string",
  "clientId": "string",
  "description": "string",
  "reference": "string",
  "source": "manual",
  "invoiceId": "string",
  "invoiceNumber": "string",
  "currency": "EUR",
  "principalCents": 0,
  "costsCents": 0,
  "paidCents": 0,
  "openCents": 0,
  "status": "open",
  "overdue": false,
  "dueDate": "2026-11-01",
  "paidAt": "2026-11-01T09:30:00.000Z",
  "phase": "new",
  "courtStatus": "pending",
  "enforcementStatus": "monitoring",
  "isTitled": false,
  "inCourt": false,
  "reminderLevel": 0,
  "followUpDate": "2026-11-01",
  "autoPostal": false,
  "notes": "string",
  "title": {
    "type": "vollstreckungsbescheid",
    "court": "string",
    "fileNumber": "string",
    "date": "2026-11-01",
    "servedAt": "2026-11-01",
    "enforceableAt": "2026-11-01",
    "notes": "string"
  },
  "interest": {
    "mode": "none"
  },
  "hasInstallmentPlan": false,
  "lastReminderSentAt": "2026-11-01T09:30:00.000Z",
  "lastLetterSentAt": "2026-11-01T09:30:00.000Z",
  "createdAt": "2026-11-01T09:30:00.000Z",
  "updatedAt": "2026-11-01T09:30:00.000Z"
}

Forderung abrufen

GET/api/v1/debts/{id}

Berechtigung: debts:read

Pfadparameter

idstringPflicht
ID der Ressource
max. 128 Zeichen

Antwort 200 · Debt

idstringPflicht
object"debt"Pflicht
contactIdstringPflicht
contactNamestringPflicht
clientIdstring | nullPflicht
descriptionstringPflicht
referencestringPflicht
source"manual" | "invoice"Pflicht
invoice = aus einer Rechnung ans Mahnwesen übergeben
invoiceIdstring | nullPflicht
Rechnung, aus der die Forderung stammt – Zahlungen werden abgeglichen
invoiceNumberstring | nullPflicht
currency"EUR"Pflicht
principalCentsintegerPflicht
Hauptforderung
-100000000000–100000000000
costsCentsintegerPflicht
Summe der Kosten
-100000000000–100000000000
paidCentsintegerPflicht
Summe der Zahlungen inkl. Raten
-100000000000–100000000000
openCentsintegerPflicht
Offen: Hauptforderung + Kosten − Zahlungen (0 wenn bezahlt)
-100000000000–100000000000
status"open" | "paid"Pflicht
overduebooleanPflicht
dueDatestring (date) | nullPflicht
Datum (YYYY-MM-DD)
paidAtstring (date-time) | nullPflicht
Zeitpunkt (ISO 8601)
phaseenumPflicht
Werte: new, reminder1, reminder2, reminder3, waiting, paymentplan, court, titled, enforcement, completed
courtStatus"pending" | "objection" | "hearing" | "judgment" | "appeal" | nullPflicht
enforcementStatusenum | nullPflicht
Werte: monitoring, asset_disclosure, bank_attachment, property_attachment, wage_attachment, vehicle_attachment, completed
isTitledbooleanPflicht
Vollstreckungstitel liegt vor (Kennzeichen; Details in `title`)
inCourtbooleanPflicht
Gerichtsverfahren läuft (Kennzeichen)
reminderLevelintegerPflicht
0–3
followUpDatestring (date) | nullPflicht
Wiedervorlage
autoPostalboolean | nullPflicht
Mahnungen automatisch per Post (null = Voreinstellung)
notesstringPflicht
titleDebtTitle | nullPflicht
- typeenumPflicht
  Werte: vollstreckungsbescheid, urteil, versaeumnisurteil, vergleich, kostenfestsetzungsbeschluss, notarielle_urkunde, sonstiger
- courtstring
  max. 200 Zeichen
- fileNumberstring
  Aktenzeichen
  max. 80 Zeichen
- datestring (date)
  Datum (YYYY-MM-DD)
- servedAtstring (date)
  Zustellung
- enforceableAtstring (date)
  Vollstreckbare Ausfertigung
- notesstring
  max. 2000 Zeichen
interestDebtInterestPflicht
hasInstallmentPlanbooleanPflicht
lastReminderSentAtstring (date-time) | nullPflicht
Zeitpunkt (ISO 8601)
lastLetterSentAtstring (date-time) | nullPflicht
Zeitpunkt (ISO 8601)
createdAtstring (date-time)Pflicht
Zeitpunkt (ISO 8601)
updatedAtstring (date-time)Pflicht
Zeitpunkt (ISO 8601)

Mögliche Fehler: 400, 401, 403, 404, 429, 500

curl 'https://www.debt-flow.io/api/v1/debts/ID' \
  -H "Authorization: Bearer $DEBTFLOW_API_KEY"

Antwort 200

{
  "id": "string",
  "object": "debt",
  "contactId": "string",
  "contactName": "string",
  "clientId": "string",
  "description": "string",
  "reference": "string",
  "source": "manual",
  "invoiceId": "string",
  "invoiceNumber": "string",
  "currency": "EUR",
  "principalCents": 0,
  "costsCents": 0,
  "paidCents": 0,
  "openCents": 0,
  "status": "open",
  "overdue": false,
  "dueDate": "2026-11-01",
  "paidAt": "2026-11-01T09:30:00.000Z",
  "phase": "new",
  "courtStatus": "pending",
  "enforcementStatus": "monitoring",
  "isTitled": false,
  "inCourt": false,
  "reminderLevel": 0,
  "followUpDate": "2026-11-01",
  "autoPostal": false,
  "notes": "string",
  "title": {
    "type": "vollstreckungsbescheid",
    "court": "string",
    "fileNumber": "string",
    "date": "2026-11-01",
    "servedAt": "2026-11-01",
    "enforceableAt": "2026-11-01",
    "notes": "string"
  },
  "interest": {
    "mode": "none"
  },
  "hasInstallmentPlan": false,
  "lastReminderSentAt": "2026-11-01T09:30:00.000Z",
  "lastLetterSentAt": "2026-11-01T09:30:00.000Z",
  "createdAt": "2026-11-01T09:30:00.000Z",
  "updatedAt": "2026-11-01T09:30:00.000Z"
}

Forderung ändern

PATCH/api/v1/debts/{id}

Stammdaten, Wiedervorlage, Mandant, Vollstreckungstitel (title) und Verzinsung (interest). Phase über POST /debts/{id}/phase, Bezahlt-Status über /mark-paid bzw. /mark-unpaid.

Berechtigung: debts:write

Pfadparameter

idstringPflicht
ID der Ressource
max. 128 Zeichen

Body (JSON) · DebtUpdate

descriptionstring
max. 1000 Zeichen
amountCentsinteger
Betrag in Cent
0–100000000000
dueDatestring (date)
Datum (YYYY-MM-DD)
followUpDatestring (date) | null
Datum (YYYY-MM-DD)
referencestring
max. 100 Zeichen
notesstring
max. 10000 Zeichen
autoPostalboolean | null
reminderLevelinteger
0–3
clientIdstring | null
max. 128 Zeichen
isTitledboolean
inCourtboolean
titleDebtTitle | null
Titel erfassen (null entfernt)
- typeenumPflicht
  Werte: vollstreckungsbescheid, urteil, versaeumnisurteil, vergleich, kostenfestsetzungsbeschluss, notarielle_urkunde, sonstiger
- courtstring
  max. 200 Zeichen
- fileNumberstring
  Aktenzeichen
  max. 80 Zeichen
- datestring (date)
  Datum (YYYY-MM-DD)
- servedAtstring (date)
  Zustellung
- enforceableAtstring (date)
  Vollstreckbare Ausfertigung
- notesstring
  max. 2000 Zeichen
interestDebtInterest

Antwort 200 · Debt

idstringPflicht
object"debt"Pflicht
contactIdstringPflicht
contactNamestringPflicht
clientIdstring | nullPflicht
descriptionstringPflicht
referencestringPflicht
source"manual" | "invoice"Pflicht
invoice = aus einer Rechnung ans Mahnwesen übergeben
invoiceIdstring | nullPflicht
Rechnung, aus der die Forderung stammt – Zahlungen werden abgeglichen
invoiceNumberstring | nullPflicht
currency"EUR"Pflicht
principalCentsintegerPflicht
Hauptforderung
-100000000000–100000000000
costsCentsintegerPflicht
Summe der Kosten
-100000000000–100000000000
paidCentsintegerPflicht
Summe der Zahlungen inkl. Raten
-100000000000–100000000000
openCentsintegerPflicht
Offen: Hauptforderung + Kosten − Zahlungen (0 wenn bezahlt)
-100000000000–100000000000
status"open" | "paid"Pflicht
overduebooleanPflicht
dueDatestring (date) | nullPflicht
Datum (YYYY-MM-DD)
paidAtstring (date-time) | nullPflicht
Zeitpunkt (ISO 8601)
phaseenumPflicht
Werte: new, reminder1, reminder2, reminder3, waiting, paymentplan, court, titled, enforcement, completed
courtStatus"pending" | "objection" | "hearing" | "judgment" | "appeal" | nullPflicht
enforcementStatusenum | nullPflicht
Werte: monitoring, asset_disclosure, bank_attachment, property_attachment, wage_attachment, vehicle_attachment, completed
isTitledbooleanPflicht
Vollstreckungstitel liegt vor (Kennzeichen; Details in `title`)
inCourtbooleanPflicht
Gerichtsverfahren läuft (Kennzeichen)
reminderLevelintegerPflicht
0–3
followUpDatestring (date) | nullPflicht
Wiedervorlage
autoPostalboolean | nullPflicht
Mahnungen automatisch per Post (null = Voreinstellung)
notesstringPflicht
titleDebtTitle | nullPflicht
- typeenumPflicht
  Werte: vollstreckungsbescheid, urteil, versaeumnisurteil, vergleich, kostenfestsetzungsbeschluss, notarielle_urkunde, sonstiger
- courtstring
  max. 200 Zeichen
- fileNumberstring
  Aktenzeichen
  max. 80 Zeichen
- datestring (date)
  Datum (YYYY-MM-DD)
- servedAtstring (date)
  Zustellung
- enforceableAtstring (date)
  Vollstreckbare Ausfertigung
- notesstring
  max. 2000 Zeichen
interestDebtInterestPflicht
hasInstallmentPlanbooleanPflicht
lastReminderSentAtstring (date-time) | nullPflicht
Zeitpunkt (ISO 8601)
lastLetterSentAtstring (date-time) | nullPflicht
Zeitpunkt (ISO 8601)
createdAtstring (date-time)Pflicht
Zeitpunkt (ISO 8601)
updatedAtstring (date-time)Pflicht
Zeitpunkt (ISO 8601)

Mögliche Fehler: 400, 401, 403, 404, 429, 500

curl -X PATCH 'https://www.debt-flow.io/api/v1/debts/ID' \
  -H "Authorization: Bearer $DEBTFLOW_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
  "description": "string",
  "amountCents": 0,
  "dueDate": "2026-11-01",
  "followUpDate": "2026-11-01",
  "reference": "string",
  "notes": "string",
  "autoPostal": false,
  "reminderLevel": 0,
  "clientId": "string",
  "isTitled": false,
  "inCourt": false,
  "title": {
    "type": "vollstreckungsbescheid",
    "court": "string",
    "fileNumber": "string",
    "date": "2026-11-01",
    "servedAt": "2026-11-01",
    "enforceableAt": "2026-11-01",
    "notes": "string"
  },
  "interest": {
    "mode": "none"
  }
}'

Antwort 200

{
  "id": "string",
  "object": "debt",
  "contactId": "string",
  "contactName": "string",
  "clientId": "string",
  "description": "string",
  "reference": "string",
  "source": "manual",
  "invoiceId": "string",
  "invoiceNumber": "string",
  "currency": "EUR",
  "principalCents": 0,
  "costsCents": 0,
  "paidCents": 0,
  "openCents": 0,
  "status": "open",
  "overdue": false,
  "dueDate": "2026-11-01",
  "paidAt": "2026-11-01T09:30:00.000Z",
  "phase": "new",
  "courtStatus": "pending",
  "enforcementStatus": "monitoring",
  "isTitled": false,
  "inCourt": false,
  "reminderLevel": 0,
  "followUpDate": "2026-11-01",
  "autoPostal": false,
  "notes": "string",
  "title": {
    "type": "vollstreckungsbescheid",
    "court": "string",
    "fileNumber": "string",
    "date": "2026-11-01",
    "servedAt": "2026-11-01",
    "enforceableAt": "2026-11-01",
    "notes": "string"
  },
  "interest": {
    "mode": "none"
  },
  "hasInstallmentPlan": false,
  "lastReminderSentAt": "2026-11-01T09:30:00.000Z",
  "lastLetterSentAt": "2026-11-01T09:30:00.000Z",
  "createdAt": "2026-11-01T09:30:00.000Z",
  "updatedAt": "2026-11-01T09:30:00.000Z"
}

Forderung löschen

DELETE/api/v1/debts/{id}

Berechtigung: debts:write

Pfadparameter

idstringPflicht
ID der Ressource
max. 128 Zeichen

Antwort 204

Erfolg, keine Antwort

Mögliche Fehler: 400, 401, 403, 404, 429, 500

curl -X DELETE 'https://www.debt-flow.io/api/v1/debts/ID' \
  -H "Authorization: Bearer $DEBTFLOW_API_KEY"

Kosten einer Forderung

GET/api/v1/debts/{id}/costs

Berechtigung: debts:read

Pfadparameter

idstringPflicht
ID der Ressource
max. 128 Zeichen

Antwort 200

object"list"Pflicht
dataArray<DebtCost>Pflicht
- idstringPflicht
- object"cost"Pflicht
- debtIdstringPflicht
- amountCentsintegerPflicht
  Betrag in Cent
  -100000000000–100000000000
- datestring (date) | nullPflicht
  Datum (YYYY-MM-DD)
- costTypestringPflicht
- descriptionstringPflicht
- invoiceNumberstringPflicht
- isPaidbooleanPflicht
- isChargeablebooleanPflicht
  Erstattungsfähig (vom Schuldner zu tragen)
- interestBearingbooleanPflicht
  Fließt in die Zinsberechnung ein

Mögliche Fehler: 400, 401, 403, 404, 429, 500

curl 'https://www.debt-flow.io/api/v1/debts/ID/costs' \
  -H "Authorization: Bearer $DEBTFLOW_API_KEY"

Antwort 200

{
  "object": "list",
  "data": [
    {
      "id": "string",
      "object": "cost",
      "debtId": "string",
      "amountCents": 0,
      "date": "2026-11-01",
      "costType": "string",
      "description": "string",
      "invoiceNumber": "string",
      "isPaid": false,
      "isChargeable": false,
      "interestBearing": false
    }
  ]
}

Kosten erfassen

POST/api/v1/debts/{id}/costs

Mahn-, Gerichts-, Anwalts- oder Vollstreckungskosten. Erhöht den offenen Betrag.

Berechtigung: debts:write

Pfadparameter

idstringPflicht
ID der Ressource
max. 128 Zeichen

Header

Idempotency-Keystring
Eindeutiger Schlüssel (8–255 Zeichen). Wiederholte Anfragen mit gleichem Schlüssel liefern 24 h lang dieselbe Antwort.
max. 255 Zeichen

Body (JSON) · DebtCostCreate

amountCentsintegerPflicht
Betrag in Cent
0–100000000000
costTypestringPflicht
z. B. dunning_fee, court_fee, lawyer_fee, bailiff_fee, other
max. 60 Zeichen
descriptionstringPflicht
max. 500 Zeichen
datestring (date)
Datum (YYYY-MM-DD)
invoiceNumberstring
max. 60 Zeichen
isPaidboolean
isChargeableboolean
interestBearingboolean

Antwort 201 · DebtCost

idstringPflicht
object"cost"Pflicht
debtIdstringPflicht
amountCentsintegerPflicht
Betrag in Cent
-100000000000–100000000000
datestring (date) | nullPflicht
Datum (YYYY-MM-DD)
costTypestringPflicht
descriptionstringPflicht
invoiceNumberstringPflicht
isPaidbooleanPflicht
isChargeablebooleanPflicht
Erstattungsfähig (vom Schuldner zu tragen)
interestBearingbooleanPflicht
Fließt in die Zinsberechnung ein

Mögliche Fehler: 400, 401, 403, 404, 409, 422, 429, 500

curl -X POST 'https://www.debt-flow.io/api/v1/debts/ID/costs' \
  -H "Authorization: Bearer $DEBTFLOW_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
  "amountCents": 0,
  "costType": "string",
  "description": "string",
  "date": "2026-11-01",
  "invoiceNumber": "string",
  "isPaid": false,
  "isChargeable": false,
  "interestBearing": false
}'

Antwort 201

{
  "id": "string",
  "object": "cost",
  "debtId": "string",
  "amountCents": 0,
  "date": "2026-11-01",
  "costType": "string",
  "description": "string",
  "invoiceNumber": "string",
  "isPaid": false,
  "isChargeable": false,
  "interestBearing": false
}

Kosten entfernen

DELETE/api/v1/debts/{id}/costs/{costId}

Berechtigung: debts:write

Pfadparameter

idstringPflicht
max. 128 Zeichen
costIdstringPflicht
max. 128 Zeichen

Antwort 204

Erfolg, keine Antwort

Mögliche Fehler: 400, 401, 403, 404, 429, 500

curl -X DELETE 'https://www.debt-flow.io/api/v1/debts/ID/costs/COSTID' \
  -H "Authorization: Bearer $DEBTFLOW_API_KEY"

Verlauf einer Forderung

GET/api/v1/debts/{id}/history

Protokoll aller Aktionen (Phasenwechsel, Zahlungen, Briefe …), neueste zuerst.

Berechtigung: debts:read

Pfadparameter

idstringPflicht
ID der Ressource
max. 128 Zeichen

Antwort 200

object"list"Pflicht
dataArray<DebtHistoryEntry>Pflicht
- idstringPflicht
- actionstringPflicht
- detailsstringPflicht
- performedBystring | nullPflicht
- createdAtstring (date-time)Pflicht
  Zeitpunkt (ISO 8601)

Mögliche Fehler: 400, 401, 403, 404, 429, 500

curl 'https://www.debt-flow.io/api/v1/debts/ID/history' \
  -H "Authorization: Bearer $DEBTFLOW_API_KEY"

Antwort 200

{
  "object": "list",
  "data": [
    {
      "id": "string",
      "action": "string",
      "details": "string",
      "performedBy": "string",
      "createdAt": "2026-11-01T09:30:00.000Z"
    }
  ]
}

Als bezahlt markieren

POST/api/v1/debts/{id}/mark-paid

Setzt die Phase auf completed (vorherige Phase wird gemerkt). Ereignis debt.paid.

Berechtigung: debts:write

Pfadparameter

idstringPflicht
ID der Ressource
max. 128 Zeichen

Header

Idempotency-Keystring
Eindeutiger Schlüssel (8–255 Zeichen). Wiederholte Anfragen mit gleichem Schlüssel liefern 24 h lang dieselbe Antwort.
max. 255 Zeichen

Antwort 200 · Debt

idstringPflicht
object"debt"Pflicht
contactIdstringPflicht
contactNamestringPflicht
clientIdstring | nullPflicht
descriptionstringPflicht
referencestringPflicht
source"manual" | "invoice"Pflicht
invoice = aus einer Rechnung ans Mahnwesen übergeben
invoiceIdstring | nullPflicht
Rechnung, aus der die Forderung stammt – Zahlungen werden abgeglichen
invoiceNumberstring | nullPflicht
currency"EUR"Pflicht
principalCentsintegerPflicht
Hauptforderung
-100000000000–100000000000
costsCentsintegerPflicht
Summe der Kosten
-100000000000–100000000000
paidCentsintegerPflicht
Summe der Zahlungen inkl. Raten
-100000000000–100000000000
openCentsintegerPflicht
Offen: Hauptforderung + Kosten − Zahlungen (0 wenn bezahlt)
-100000000000–100000000000
status"open" | "paid"Pflicht
overduebooleanPflicht
dueDatestring (date) | nullPflicht
Datum (YYYY-MM-DD)
paidAtstring (date-time) | nullPflicht
Zeitpunkt (ISO 8601)
phaseenumPflicht
Werte: new, reminder1, reminder2, reminder3, waiting, paymentplan, court, titled, enforcement, completed
courtStatus"pending" | "objection" | "hearing" | "judgment" | "appeal" | nullPflicht
enforcementStatusenum | nullPflicht
Werte: monitoring, asset_disclosure, bank_attachment, property_attachment, wage_attachment, vehicle_attachment, completed
isTitledbooleanPflicht
Vollstreckungstitel liegt vor (Kennzeichen; Details in `title`)
inCourtbooleanPflicht
Gerichtsverfahren läuft (Kennzeichen)
reminderLevelintegerPflicht
0–3
followUpDatestring (date) | nullPflicht
Wiedervorlage
autoPostalboolean | nullPflicht
Mahnungen automatisch per Post (null = Voreinstellung)
notesstringPflicht
titleDebtTitle | nullPflicht
- typeenumPflicht
  Werte: vollstreckungsbescheid, urteil, versaeumnisurteil, vergleich, kostenfestsetzungsbeschluss, notarielle_urkunde, sonstiger
- courtstring
  max. 200 Zeichen
- fileNumberstring
  Aktenzeichen
  max. 80 Zeichen
- datestring (date)
  Datum (YYYY-MM-DD)
- servedAtstring (date)
  Zustellung
- enforceableAtstring (date)
  Vollstreckbare Ausfertigung
- notesstring
  max. 2000 Zeichen
interestDebtInterestPflicht
hasInstallmentPlanbooleanPflicht
lastReminderSentAtstring (date-time) | nullPflicht
Zeitpunkt (ISO 8601)
lastLetterSentAtstring (date-time) | nullPflicht
Zeitpunkt (ISO 8601)
createdAtstring (date-time)Pflicht
Zeitpunkt (ISO 8601)
updatedAtstring (date-time)Pflicht
Zeitpunkt (ISO 8601)

Mögliche Fehler: 400, 401, 403, 404, 409, 422, 429, 500

curl -X POST 'https://www.debt-flow.io/api/v1/debts/ID/mark-paid' \
  -H "Authorization: Bearer $DEBTFLOW_API_KEY"

Antwort 200

{
  "id": "string",
  "object": "debt",
  "contactId": "string",
  "contactName": "string",
  "clientId": "string",
  "description": "string",
  "reference": "string",
  "source": "manual",
  "invoiceId": "string",
  "invoiceNumber": "string",
  "currency": "EUR",
  "principalCents": 0,
  "costsCents": 0,
  "paidCents": 0,
  "openCents": 0,
  "status": "open",
  "overdue": false,
  "dueDate": "2026-11-01",
  "paidAt": "2026-11-01T09:30:00.000Z",
  "phase": "new",
  "courtStatus": "pending",
  "enforcementStatus": "monitoring",
  "isTitled": false,
  "inCourt": false,
  "reminderLevel": 0,
  "followUpDate": "2026-11-01",
  "autoPostal": false,
  "notes": "string",
  "title": {
    "type": "vollstreckungsbescheid",
    "court": "string",
    "fileNumber": "string",
    "date": "2026-11-01",
    "servedAt": "2026-11-01",
    "enforceableAt": "2026-11-01",
    "notes": "string"
  },
  "interest": {
    "mode": "none"
  },
  "hasInstallmentPlan": false,
  "lastReminderSentAt": "2026-11-01T09:30:00.000Z",
  "lastLetterSentAt": "2026-11-01T09:30:00.000Z",
  "createdAt": "2026-11-01T09:30:00.000Z",
  "updatedAt": "2026-11-01T09:30:00.000Z"
}

Bezahlt-Markierung aufheben

POST/api/v1/debts/{id}/mark-unpaid

Stellt die Phase vor der Markierung wieder her.

Berechtigung: debts:write

Pfadparameter

idstringPflicht
ID der Ressource
max. 128 Zeichen

Header

Idempotency-Keystring
Eindeutiger Schlüssel (8–255 Zeichen). Wiederholte Anfragen mit gleichem Schlüssel liefern 24 h lang dieselbe Antwort.
max. 255 Zeichen

Antwort 200 · Debt

idstringPflicht
object"debt"Pflicht
contactIdstringPflicht
contactNamestringPflicht
clientIdstring | nullPflicht
descriptionstringPflicht
referencestringPflicht
source"manual" | "invoice"Pflicht
invoice = aus einer Rechnung ans Mahnwesen übergeben
invoiceIdstring | nullPflicht
Rechnung, aus der die Forderung stammt – Zahlungen werden abgeglichen
invoiceNumberstring | nullPflicht
currency"EUR"Pflicht
principalCentsintegerPflicht
Hauptforderung
-100000000000–100000000000
costsCentsintegerPflicht
Summe der Kosten
-100000000000–100000000000
paidCentsintegerPflicht
Summe der Zahlungen inkl. Raten
-100000000000–100000000000
openCentsintegerPflicht
Offen: Hauptforderung + Kosten − Zahlungen (0 wenn bezahlt)
-100000000000–100000000000
status"open" | "paid"Pflicht
overduebooleanPflicht
dueDatestring (date) | nullPflicht
Datum (YYYY-MM-DD)
paidAtstring (date-time) | nullPflicht
Zeitpunkt (ISO 8601)
phaseenumPflicht
Werte: new, reminder1, reminder2, reminder3, waiting, paymentplan, court, titled, enforcement, completed
courtStatus"pending" | "objection" | "hearing" | "judgment" | "appeal" | nullPflicht
enforcementStatusenum | nullPflicht
Werte: monitoring, asset_disclosure, bank_attachment, property_attachment, wage_attachment, vehicle_attachment, completed
isTitledbooleanPflicht
Vollstreckungstitel liegt vor (Kennzeichen; Details in `title`)
inCourtbooleanPflicht
Gerichtsverfahren läuft (Kennzeichen)
reminderLevelintegerPflicht
0–3
followUpDatestring (date) | nullPflicht
Wiedervorlage
autoPostalboolean | nullPflicht
Mahnungen automatisch per Post (null = Voreinstellung)
notesstringPflicht
titleDebtTitle | nullPflicht
- typeenumPflicht
  Werte: vollstreckungsbescheid, urteil, versaeumnisurteil, vergleich, kostenfestsetzungsbeschluss, notarielle_urkunde, sonstiger
- courtstring
  max. 200 Zeichen
- fileNumberstring
  Aktenzeichen
  max. 80 Zeichen
- datestring (date)
  Datum (YYYY-MM-DD)
- servedAtstring (date)
  Zustellung
- enforceableAtstring (date)
  Vollstreckbare Ausfertigung
- notesstring
  max. 2000 Zeichen
interestDebtInterestPflicht
hasInstallmentPlanbooleanPflicht
lastReminderSentAtstring (date-time) | nullPflicht
Zeitpunkt (ISO 8601)
lastLetterSentAtstring (date-time) | nullPflicht
Zeitpunkt (ISO 8601)
createdAtstring (date-time)Pflicht
Zeitpunkt (ISO 8601)
updatedAtstring (date-time)Pflicht
Zeitpunkt (ISO 8601)

Mögliche Fehler: 400, 401, 403, 404, 409, 422, 429, 500

curl -X POST 'https://www.debt-flow.io/api/v1/debts/ID/mark-unpaid' \
  -H "Authorization: Bearer $DEBTFLOW_API_KEY"

Antwort 200

{
  "id": "string",
  "object": "debt",
  "contactId": "string",
  "contactName": "string",
  "clientId": "string",
  "description": "string",
  "reference": "string",
  "source": "manual",
  "invoiceId": "string",
  "invoiceNumber": "string",
  "currency": "EUR",
  "principalCents": 0,
  "costsCents": 0,
  "paidCents": 0,
  "openCents": 0,
  "status": "open",
  "overdue": false,
  "dueDate": "2026-11-01",
  "paidAt": "2026-11-01T09:30:00.000Z",
  "phase": "new",
  "courtStatus": "pending",
  "enforcementStatus": "monitoring",
  "isTitled": false,
  "inCourt": false,
  "reminderLevel": 0,
  "followUpDate": "2026-11-01",
  "autoPostal": false,
  "notes": "string",
  "title": {
    "type": "vollstreckungsbescheid",
    "court": "string",
    "fileNumber": "string",
    "date": "2026-11-01",
    "servedAt": "2026-11-01",
    "enforceableAt": "2026-11-01",
    "notes": "string"
  },
  "interest": {
    "mode": "none"
  },
  "hasInstallmentPlan": false,
  "lastReminderSentAt": "2026-11-01T09:30:00.000Z",
  "lastLetterSentAt": "2026-11-01T09:30:00.000Z",
  "createdAt": "2026-11-01T09:30:00.000Z",
  "updatedAt": "2026-11-01T09:30:00.000Z"
}

Kommunikationsprotokoll

GET/api/v1/debts/{id}/messages

Berechtigung: debts:read

Pfadparameter

idstringPflicht
ID der Ressource
max. 128 Zeichen

Antwort 200

object"list"Pflicht
dataArray<DebtMessage>Pflicht
- idstringPflicht
- object"debt_message"Pflicht
- debtIdstringPflicht
- typestringPflicht
  note, email, phone, letter …
- textstringPflicht
- sentToEmailstring | nullPflicht
- sentBystringPflicht
- createdAtstring (date-time)Pflicht
  Zeitpunkt (ISO 8601)

Mögliche Fehler: 400, 401, 403, 404, 429, 500

curl 'https://www.debt-flow.io/api/v1/debts/ID/messages' \
  -H "Authorization: Bearer $DEBTFLOW_API_KEY"

Antwort 200

{
  "object": "list",
  "data": [
    {
      "id": "string",
      "object": "debt_message",
      "debtId": "string",
      "type": "string",
      "text": "string",
      "sentToEmail": "string",
      "sentBy": "string",
      "createdAt": "2026-11-01T09:30:00.000Z"
    }
  ]
}

Kommunikation protokollieren

POST/api/v1/debts/{id}/messages

Notiz, Telefonat, E-Mail o. Ä. festhalten. Es wird nichts versendet.

Berechtigung: debts:write

Pfadparameter

idstringPflicht
ID der Ressource
max. 128 Zeichen

Header

Idempotency-Keystring
Eindeutiger Schlüssel (8–255 Zeichen). Wiederholte Anfragen mit gleichem Schlüssel liefern 24 h lang dieselbe Antwort.
max. 255 Zeichen

Body (JSON) · DebtMessageCreate

typeenumPflicht
Werte: note, email, phone, sms, letter, meeting, other
textstringPflicht
max. 10000 Zeichen
sentToEmailstring (email)
max. 254 Zeichen

Antwort 201 · DebtMessage

idstringPflicht
object"debt_message"Pflicht
debtIdstringPflicht
typestringPflicht
note, email, phone, letter …
textstringPflicht
sentToEmailstring | nullPflicht
sentBystringPflicht
createdAtstring (date-time)Pflicht
Zeitpunkt (ISO 8601)

Mögliche Fehler: 400, 401, 403, 404, 409, 422, 429, 500

curl -X POST 'https://www.debt-flow.io/api/v1/debts/ID/messages' \
  -H "Authorization: Bearer $DEBTFLOW_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
  "type": "note",
  "text": "string",
  "sentToEmail": "[email protected]"
}'

Antwort 201

{
  "id": "string",
  "object": "debt_message",
  "debtId": "string",
  "type": "string",
  "text": "string",
  "sentToEmail": "string",
  "sentBy": "string",
  "createdAt": "2026-11-01T09:30:00.000Z"
}

Phasen: new → reminder1/2/3 → waiting → paymentplan → court (courtStatus) → titled → enforcement (enforcementStatus) → completed. Ereignis debt.phase_changed mit vorheriger Phase in data.previous.

Berechtigung: debts:write

Pfadparameter

idstringPflicht
ID der Ressource
max. 128 Zeichen

Header

Idempotency-Keystring
Eindeutiger Schlüssel (8–255 Zeichen). Wiederholte Anfragen mit gleichem Schlüssel liefern 24 h lang dieselbe Antwort.
max. 255 Zeichen

Body (JSON) · DebtPhaseChange

phaseenumPflicht
Werte: new, reminder1, reminder2, reminder3, waiting, paymentplan, court, titled, enforcement, completed
courtStatus"pending" | "objection" | "hearing" | "judgment" | "appeal"
nur bei phase=court
enforcementStatusenum
nur bei phase=enforcement
Werte: monitoring, asset_disclosure, bank_attachment, property_attachment, wage_attachment, vehicle_attachment, completed

Antwort 200 · Debt

idstringPflicht
object"debt"Pflicht
contactIdstringPflicht
contactNamestringPflicht
clientIdstring | nullPflicht
descriptionstringPflicht
referencestringPflicht
source"manual" | "invoice"Pflicht
invoice = aus einer Rechnung ans Mahnwesen übergeben
invoiceIdstring | nullPflicht
Rechnung, aus der die Forderung stammt – Zahlungen werden abgeglichen
invoiceNumberstring | nullPflicht
currency"EUR"Pflicht
principalCentsintegerPflicht
Hauptforderung
-100000000000–100000000000
costsCentsintegerPflicht
Summe der Kosten
-100000000000–100000000000
paidCentsintegerPflicht
Summe der Zahlungen inkl. Raten
-100000000000–100000000000
openCentsintegerPflicht
Offen: Hauptforderung + Kosten − Zahlungen (0 wenn bezahlt)
-100000000000–100000000000
status"open" | "paid"Pflicht
overduebooleanPflicht
dueDatestring (date) | nullPflicht
Datum (YYYY-MM-DD)
paidAtstring (date-time) | nullPflicht
Zeitpunkt (ISO 8601)
phaseenumPflicht
Werte: new, reminder1, reminder2, reminder3, waiting, paymentplan, court, titled, enforcement, completed
courtStatus"pending" | "objection" | "hearing" | "judgment" | "appeal" | nullPflicht
enforcementStatusenum | nullPflicht
Werte: monitoring, asset_disclosure, bank_attachment, property_attachment, wage_attachment, vehicle_attachment, completed
isTitledbooleanPflicht
Vollstreckungstitel liegt vor (Kennzeichen; Details in `title`)
inCourtbooleanPflicht
Gerichtsverfahren läuft (Kennzeichen)
reminderLevelintegerPflicht
0–3
followUpDatestring (date) | nullPflicht
Wiedervorlage
autoPostalboolean | nullPflicht
Mahnungen automatisch per Post (null = Voreinstellung)
notesstringPflicht
titleDebtTitle | nullPflicht
- typeenumPflicht
  Werte: vollstreckungsbescheid, urteil, versaeumnisurteil, vergleich, kostenfestsetzungsbeschluss, notarielle_urkunde, sonstiger
- courtstring
  max. 200 Zeichen
- fileNumberstring
  Aktenzeichen
  max. 80 Zeichen
- datestring (date)
  Datum (YYYY-MM-DD)
- servedAtstring (date)
  Zustellung
- enforceableAtstring (date)
  Vollstreckbare Ausfertigung
- notesstring
  max. 2000 Zeichen
interestDebtInterestPflicht
hasInstallmentPlanbooleanPflicht
lastReminderSentAtstring (date-time) | nullPflicht
Zeitpunkt (ISO 8601)
lastLetterSentAtstring (date-time) | nullPflicht
Zeitpunkt (ISO 8601)
createdAtstring (date-time)Pflicht
Zeitpunkt (ISO 8601)
updatedAtstring (date-time)Pflicht
Zeitpunkt (ISO 8601)

Mögliche Fehler: 400, 401, 403, 404, 409, 422, 429, 500

curl -X POST 'https://www.debt-flow.io/api/v1/debts/ID/phase' \
  -H "Authorization: Bearer $DEBTFLOW_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
  "phase": "new",
  "courtStatus": "pending",
  "enforcementStatus": "monitoring"
}'

Antwort 200

{
  "id": "string",
  "object": "debt",
  "contactId": "string",
  "contactName": "string",
  "clientId": "string",
  "description": "string",
  "reference": "string",
  "source": "manual",
  "invoiceId": "string",
  "invoiceNumber": "string",
  "currency": "EUR",
  "principalCents": 0,
  "costsCents": 0,
  "paidCents": 0,
  "openCents": 0,
  "status": "open",
  "overdue": false,
  "dueDate": "2026-11-01",
  "paidAt": "2026-11-01T09:30:00.000Z",
  "phase": "new",
  "courtStatus": "pending",
  "enforcementStatus": "monitoring",
  "isTitled": false,
  "inCourt": false,
  "reminderLevel": 0,
  "followUpDate": "2026-11-01",
  "autoPostal": false,
  "notes": "string",
  "title": {
    "type": "vollstreckungsbescheid",
    "court": "string",
    "fileNumber": "string",
    "date": "2026-11-01",
    "servedAt": "2026-11-01",
    "enforceableAt": "2026-11-01",
    "notes": "string"
  },
  "interest": {
    "mode": "none"
  },
  "hasInstallmentPlan": false,
  "lastReminderSentAt": "2026-11-01T09:30:00.000Z",
  "lastLetterSentAt": "2026-11-01T09:30:00.000Z",
  "createdAt": "2026-11-01T09:30:00.000Z",
  "updatedAt": "2026-11-01T09:30:00.000Z"
}

Forderungsaufstellung

GET/api/v1/debts/{id}/statement

Aufstellung zum Stichtag mit taggenauen Verzugszinsen (Basiszins + 5/9 Prozentpunkte oder fester Satz), Tilgungsreihenfolge Kosten → Zinsen → Hauptforderung (§ 367 BGB).

Berechtigung: debts:read

Pfadparameter

idstringPflicht
ID der Ressource
max. 128 Zeichen

Query-Parameter

untilstring (date)
Stichtag, Standard: heute

Antwort 200 · DebtStatement

untilstring (date)Pflicht
Datum (YYYY-MM-DD)
rateLabelstringPflicht
principalCentsintegerPflicht
Betrag in Cent
-100000000000–100000000000
costsCentsintegerPflicht
Betrag in Cent
-100000000000–100000000000
interestCentsintegerPflicht
Betrag in Cent
-100000000000–100000000000
paymentsCentsintegerPflicht
Betrag in Cent
-100000000000–100000000000
openobjectPflicht
- principalCentsintegerPflicht
  Betrag in Cent
  -100000000000–100000000000
- interestCentsintegerPflicht
  Betrag in Cent
  -100000000000–100000000000
- costsCentsintegerPflicht
  Betrag in Cent
  -100000000000–100000000000
- totalCentsintegerPflicht
  Betrag in Cent
  -100000000000–100000000000
interestRowsArray<object>Pflicht
- fromstring (date)Pflicht
  Datum (YYYY-MM-DD)
- tostring (date)Pflicht
  Datum (YYYY-MM-DD)
- daysintegerPflicht
  -9007199254740991–9007199254740991
- ratenumberPflicht
- basisCentsintegerPflicht
  Betrag in Cent
  -100000000000–100000000000
- amountCentsintegerPflicht
  Betrag in Cent
  -100000000000–100000000000
- on"principal" | "costs"Pflicht
paymentRowsArray<object>Pflicht
- datestring (date)Pflicht
  Datum (YYYY-MM-DD)
- amountCentsintegerPflicht
  Betrag in Cent
  -100000000000–100000000000
- labelstring | nullPflicht
- toCostsCentsintegerPflicht
  Betrag in Cent
  -100000000000–100000000000
- toInterestCentsintegerPflicht
  Betrag in Cent
  -100000000000–100000000000
- toPrincipalCentsintegerPflicht
  Betrag in Cent
  -100000000000–100000000000
- surplusCentsintegerPflicht
  Betrag in Cent
  -100000000000–100000000000
costsArray<object>Pflicht
- datestring (date)Pflicht
  Datum (YYYY-MM-DD)
- amountCentsintegerPflicht
  Betrag in Cent
  -100000000000–100000000000
- labelstringPflicht
- interestBearingbooleanPflicht
warningsArray<string>Pflicht

Mögliche Fehler: 400, 401, 403, 404, 429, 500

curl 'https://www.debt-flow.io/api/v1/debts/ID/statement' \
  -H "Authorization: Bearer $DEBTFLOW_API_KEY"

Antwort 200

{
  "until": "2026-11-01",
  "rateLabel": "string",
  "principalCents": 0,
  "costsCents": 0,
  "interestCents": 0,
  "paymentsCents": 0,
  "open": {
    "principalCents": 0,
    "interestCents": 0,
    "costsCents": 0,
    "totalCents": 0
  },
  "interestRows": [
    {
      "from": "2026-11-01",
      "to": "2026-11-01",
      "days": 0,
      "rate": 0,
      "basisCents": 0,
      "amountCents": 0,
      "on": "principal"
    }
  ],
  "paymentRows": [
    {
      "date": "2026-11-01",
      "amountCents": 0,
      "label": "string",
      "toCostsCents": 0,
      "toInterestCents": 0,
      "toPrincipalCents": 0,
      "surplusCents": 0
    }
  ],
  "costs": [
    {
      "date": "2026-11-01",
      "amountCents": 0,
      "label": "string",
      "interestBearing": false
    }
  ],
  "warnings": [
    "string"
  ]
}

Zinsen berechnen (Zinsrechner)

POST/api/v1/interest-calculations

Berechnet eine Forderungsaufstellung aus den übergebenen Werten, ohne etwas zu speichern. Basiszinssätze der Bundesbank sind hinterlegt.

Berechtigung: debts:read

Body (JSON) · InterestCalculation

principalCentsintegerPflicht
Betrag in Cent
0–100000000000
interestDebtInterestPflicht
untilstring (date)Pflicht
Stichtag (einschließlich)
costsArray<object>
- datestring (date)Pflicht
  Datum (YYYY-MM-DD)
- amountCentsintegerPflicht
  Betrag in Cent
  0–100000000000
- labelstring
  max. 200 Zeichen · Standard: "Kosten"
- interestBearingboolean
  Standard: false
paymentsArray<object>
- datestring (date)Pflicht
  Datum (YYYY-MM-DD)
- amountCentsintegerPflicht
  Betrag in Cent
  0–100000000000
- labelstring
  max. 200 Zeichen

Antwort 200 · DebtStatement

untilstring (date)Pflicht
Datum (YYYY-MM-DD)
rateLabelstringPflicht
principalCentsintegerPflicht
Betrag in Cent
-100000000000–100000000000
costsCentsintegerPflicht
Betrag in Cent
-100000000000–100000000000
interestCentsintegerPflicht
Betrag in Cent
-100000000000–100000000000
paymentsCentsintegerPflicht
Betrag in Cent
-100000000000–100000000000
openobjectPflicht
- principalCentsintegerPflicht
  Betrag in Cent
  -100000000000–100000000000
- interestCentsintegerPflicht
  Betrag in Cent
  -100000000000–100000000000
- costsCentsintegerPflicht
  Betrag in Cent
  -100000000000–100000000000
- totalCentsintegerPflicht
  Betrag in Cent
  -100000000000–100000000000
interestRowsArray<object>Pflicht
- fromstring (date)Pflicht
  Datum (YYYY-MM-DD)
- tostring (date)Pflicht
  Datum (YYYY-MM-DD)
- daysintegerPflicht
  -9007199254740991–9007199254740991
- ratenumberPflicht
- basisCentsintegerPflicht
  Betrag in Cent
  -100000000000–100000000000
- amountCentsintegerPflicht
  Betrag in Cent
  -100000000000–100000000000
- on"principal" | "costs"Pflicht
paymentRowsArray<object>Pflicht
- datestring (date)Pflicht
  Datum (YYYY-MM-DD)
- amountCentsintegerPflicht
  Betrag in Cent
  -100000000000–100000000000
- labelstring | nullPflicht
- toCostsCentsintegerPflicht
  Betrag in Cent
  -100000000000–100000000000
- toInterestCentsintegerPflicht
  Betrag in Cent
  -100000000000–100000000000
- toPrincipalCentsintegerPflicht
  Betrag in Cent
  -100000000000–100000000000
- surplusCentsintegerPflicht
  Betrag in Cent
  -100000000000–100000000000
costsArray<object>Pflicht
- datestring (date)Pflicht
  Datum (YYYY-MM-DD)
- amountCentsintegerPflicht
  Betrag in Cent
  -100000000000–100000000000
- labelstringPflicht
- interestBearingbooleanPflicht
warningsArray<string>Pflicht

Mögliche Fehler: 400, 401, 403, 429, 500

curl -X POST 'https://www.debt-flow.io/api/v1/interest-calculations' \
  -H "Authorization: Bearer $DEBTFLOW_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
  "principalCents": 0,
  "interest": {
    "mode": "none"
  },
  "until": "2026-11-01",
  "costs": [],
  "payments": []
}'

Antwort 200

{
  "until": "2026-11-01",
  "rateLabel": "string",
  "principalCents": 0,
  "costsCents": 0,
  "interestCents": 0,
  "paymentsCents": 0,
  "open": {
    "principalCents": 0,
    "interestCents": 0,
    "costsCents": 0,
    "totalCents": 0
  },
  "interestRows": [
    {
      "from": "2026-11-01",
      "to": "2026-11-01",
      "days": 0,
      "rate": 0,
      "basisCents": 0,
      "amountCents": 0,
      "on": "principal"
    }
  ],
  "paymentRows": [
    {
      "date": "2026-11-01",
      "amountCents": 0,
      "label": "string",
      "toCostsCents": 0,
      "toInterestCents": 0,
      "toPrincipalCents": 0,
      "surplusCents": 0
    }
  ],
  "costs": [
    {
      "date": "2026-11-01",
      "amountCents": 0,
      "label": "string",
      "interestBearing": false
    }
  ],
  "warnings": [
    "string"
  ]
}

Forderungsübersicht (Kennzahlen)

GET/api/v1/reports/receivables

Kennzahlen wie auf der Dashboard-Startseite: Summen, überfällige Forderungen, fällige Raten der nächsten 7 Tage, letzte Zahlungen, Eingänge der letzten 6 Monate und Verteilung nach Phase.

Berechtigung: debts:read

Antwort 200 · ReceivablesSummary

object"receivables_summary"Pflicht
statsobjectPflicht
- totalCentsintegerPflicht
  Summe aller Hauptforderungen
  -100000000000–100000000000
- contactCountintegerPflicht
  -9007199254740991–9007199254740991
- openCentsintegerPflicht
  Offen inkl. Kosten abzüglich Zahlungen
  -100000000000–100000000000
- overdueCentsintegerPflicht
  Betrag in Cent
  -100000000000–100000000000
- overdueCountintegerPflicht
  -9007199254740991–9007199254740991
- incomeThisMonthCentsintegerPflicht
  Betrag in Cent
  -100000000000–100000000000
- activeDebtsintegerPflicht
  -9007199254740991–9007199254740991
overdueDebtsArray<object>Pflicht
- debtIdstringPflicht
- contactIdstringPflicht
- contactNamestringPflicht
- descriptionstringPflicht
- openCentsintegerPflicht
  Betrag in Cent
  -100000000000–100000000000
- dueDatestring (date) | nullPflicht
  Datum (YYYY-MM-DD)
- daysOverdueintegerPflicht
  -9007199254740991–9007199254740991
upcomingInstallmentsArray<object>Pflicht
- debtIdstringPflicht
- installmentPlanIdstringPflicht
- contactNamestringPflicht
- descriptionstringPflicht
- amountCentsintegerPflicht
  Betrag in Cent
  -100000000000–100000000000
- dueDatestring (date)Pflicht
  Datum (YYYY-MM-DD)
recentPaymentsArray<object>Pflicht
- idstringPflicht
- debtIdstringPflicht
- contactIdstringPflicht
- contactNamestringPflicht
- descriptionstringPflicht
- amountCentsintegerPflicht
  Betrag in Cent
  -100000000000–100000000000
- datestring (date) | nullPflicht
  Datum (YYYY-MM-DD)
- type"single" | "installment"Pflicht
incomeByMonthArray<object>Pflicht
- monthstringPflicht
  YYYY-MM
- amountCentsintegerPflicht
  Betrag in Cent
  -100000000000–100000000000
phasesArray<object>Pflicht
- phasestringPflicht
- countintegerPflicht
  -9007199254740991–9007199254740991
- openCentsintegerPflicht
  Betrag in Cent
  -100000000000–100000000000
onboardingobjectPflicht
- hasSenderAddressbooleanPflicht
- hasContactsbooleanPflicht
- hasDebtsbooleanPflicht
- autoDunningbooleanPflicht

Mögliche Fehler: 400, 401, 403, 429, 500

curl 'https://www.debt-flow.io/api/v1/reports/receivables' \
  -H "Authorization: Bearer $DEBTFLOW_API_KEY"

Antwort 200

{
  "object": "receivables_summary",
  "stats": {
    "totalCents": 0,
    "contactCount": 0,
    "openCents": 0,
    "overdueCents": 0,
    "overdueCount": 0,
    "incomeThisMonthCents": 0,
    "activeDebts": 0
  },
  "overdueDebts": [
    {
      "debtId": "string",
      "contactId": "string",
      "contactName": "string",
      "description": "string",
      "openCents": 0,
      "dueDate": "2026-11-01",
      "daysOverdue": 0
    }
  ],
  "upcomingInstallments": [
    {
      "debtId": "string",
      "installmentPlanId": "string",
      "contactName": "string",
      "description": "string",
      "amountCents": 0,
      "dueDate": "2026-11-01"
    }
  ],
  "recentPayments": [
    {
      "id": "string",
      "debtId": "string",
      "contactId": "string",
      "contactName": "string",
      "description": "string",
      "amountCents": 0,
      "date": "2026-11-01",
      "type": "single"
    }
  ],
  "incomeByMonth": [
    {
      "month": "string",
      "amountCents": 0
    }
  ],
  "phases": [
    {
      "phase": "string",
      "count": 0,
      "openCents": 0
    }
  ],
  "onboarding": {
    "hasSenderAddress": false,
    "hasContacts": false,
    "hasDebts": false,
    "autoDunning": false
  }
}