Zum Inhalt springen
DebtFlow

Debts

Debts, costs, interest and phases (dunning, court, enforcement).

Financial analysis of a contact

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

All debts of the contact with costs (total and recoverable), payments including instalments, remaining balance and repayment rate. Basis of the creditor AI (Gläubiger-KI).

Permission: debts:read

Path parameters

  • idstringrequired
    Resource ID
    max. 128 characters

Response 200 · ContactFinances

  • object"contact_finances"required
  • contactIdstringrequired
  • principalCentsintegerrequired
    Total principal
    -100000000000–100000000000
  • totalCostsCentsintegerrequired
    All costs
    -100000000000–100000000000
  • chargeableCostsCentsintegerrequired
    Recoverable costs (to be borne by the debtor)
    -100000000000–100000000000
  • adjustedCentsintegerrequired
    Principal amounts + recoverable costs
    -100000000000–100000000000
  • paidCentsintegerrequired
    Payments including instalments
    -100000000000–100000000000
  • remainingCentsintegerrequired
    adjustedCents − paidCents (at least 0)
    -100000000000–100000000000
  • paymentPercentagenumberrequired
    Repayment rate in per cent
    0–100
  • isFullyPaidbooleanrequired
  • debtsArray<object>required
    • debtIdstringrequired
    • descriptionstringrequired
    • status"open" | "paid"required
    • principalCentsintegerrequired
      Amount in cents
      -100000000000–100000000000
    • costsCentsintegerrequired
      Amount in cents
      -100000000000–100000000000
    • chargeableCostsCentsintegerrequired
      Amount in cents
      -100000000000–100000000000
    • paidCentsintegerrequired
      Amount in cents
      -100000000000–100000000000
    • openCentsintegerrequired
      same as Debt.openCents
      -100000000000–100000000000
    • paymentsArray<object>required
      • idstringrequired
      • type"single" | "installment"required
      • amountCentsintegerrequired
        Amount in cents
        -100000000000–100000000000
      • datestring (date) | nullrequired
        Date (YYYY-MM-DD)
      • methodstringrequired
    • costsArray<object>required
      • idstringrequired
      • amountCentsintegerrequired
        Amount in cents
        -100000000000–100000000000
      • datestring (date) | nullrequired
        Date (YYYY-MM-DD)
      • costTypestringrequired
      • descriptionstringrequired
      • isPaidbooleanrequired
      • isChargeablebooleanrequired

Possible errors: 400, 401, 403, 404, 429, 500

curl 'https://www.debt-flow.io/api/v1/contacts/ID/finances' \
  -H "Authorization: Bearer $DEBTFLOW_API_KEY"
Response 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
        }
      ]
    }
  ]
}

List debts

GET/api/v1/debts

With amounts in cents (principal, costs, payments including instalments, outstanding), phase and due date. Newest first.

Permission: debts:read

Query parameters

  • contactIdstring
    max. 128 characters
  • clientIdstring
    max. 128 characters
  • status"open" | "paid" | "all"
    Default: "all"
  • phaseenum
    Values: new, reminder1, reminder2, reminder3, waiting, paymentplan, court, titled, enforcement, completed
  • overdue"true" | "false"
  • limitinteger
    Number of entries (1–100)
    1–100 · Default: 25
  • cursorstring
    `nextCursor` of the previous page
    max. 500 characters

Response 200

  • object"list"required
  • dataArray<Debt>required
    • idstringrequired
    • object"debt"required
    • contactIdstringrequired
    • contactNamestringrequired
    • clientIdstring | nullrequired
    • descriptionstringrequired
    • referencestringrequired
    • source"manual" | "invoice"required
      invoice = handed over to dunning from an invoice
    • invoiceIdstring | nullrequired
      Invoice the debt originates from – payments are reconciled
    • invoiceNumberstring | nullrequired
    • currency"EUR"required
    • principalCentsintegerrequired
      Principal amount
      -100000000000–100000000000
    • costsCentsintegerrequired
      Total costs
      -100000000000–100000000000
    • paidCentsintegerrequired
      Total payments including instalments
      -100000000000–100000000000
    • openCentsintegerrequired
      Outstanding: principal + costs − payments (0 if paid)
      -100000000000–100000000000
    • status"open" | "paid"required
    • overduebooleanrequired
    • dueDatestring (date) | nullrequired
      Date (YYYY-MM-DD)
    • paidAtstring (date-time) | nullrequired
      Timestamp (ISO 8601)
    • phaseenumrequired
      Values: new, reminder1, reminder2, reminder3, waiting, paymentplan, court, titled, enforcement, completed
    • courtStatus"pending" | "objection" | "hearing" | "judgment" | "appeal" | nullrequired
    • enforcementStatusenum | nullrequired
      Values: monitoring, asset_disclosure, bank_attachment, property_attachment, wage_attachment, vehicle_attachment, completed
    • isTitledbooleanrequired
      Enforceable title (Vollstreckungstitel) exists (flag; details in `title`)
    • inCourtbooleanrequired
      Court proceedings pending (flag)
    • reminderLevelintegerrequired
      0–3
    • followUpDatestring (date) | nullrequired
      Follow-up (Wiedervorlage)
    • autoPostalboolean | nullrequired
      Send dunning letters automatically by post (null = default)
    • notesstringrequired
    • titleDebtTitle | nullrequired
      • typeenumrequired
        Values: vollstreckungsbescheid, urteil, versaeumnisurteil, vergleich, kostenfestsetzungsbeschluss, notarielle_urkunde, sonstiger
      • courtstring
        max. 200 characters
      • fileNumberstring
        File reference (Aktenzeichen)
        max. 80 characters
      • datestring (date)
        Date (YYYY-MM-DD)
      • servedAtstring (date)
        Delivery
      • enforceableAtstring (date)
        Enforceable copy (vollstreckbare Ausfertigung)
      • notesstring
        max. 2000 characters
    • interestDebtInterestrequired
    • hasInstallmentPlanbooleanrequired
    • lastReminderSentAtstring (date-time) | nullrequired
      Timestamp (ISO 8601)
    • lastLetterSentAtstring (date-time) | nullrequired
      Timestamp (ISO 8601)
    • createdAtstring (date-time)required
      Timestamp (ISO 8601)
    • updatedAtstring (date-time)required
      Timestamp (ISO 8601)
  • hasMorebooleanrequired
  • nextCursorstring | nullrequired

Possible errors: 400, 401, 403, 429, 500

curl 'https://www.debt-flow.io/api/v1/debts' \
  -H "Authorization: Bearer $DEBTFLOW_API_KEY"
Response 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"
}

Create debt

POST/api/v1/debts

New debt in phase new. Event debt.created.

Permission: debts:write

Headers

  • Idempotency-Keystring
    Unique key (8–255 characters). Repeated requests with the same key return the same response for 24 h.
    max. 255 characters

Body (JSON) · DebtCreate

  • contactIdstringrequired
    max. 128 characters
  • amountCentsintegerrequired
    Principal amount in cents
    0–100000000000
  • descriptionstringrequired
    max. 1000 characters
  • dueDatestring (date)required
    Date (YYYY-MM-DD)
  • referencestring
    Invoice or file reference
    max. 100 characters
  • clientIdstring
    max. 128 characters
  • notesstring
    max. 10000 characters
  • autoPostalboolean
  • interestDebtInterest

Response 201 · Debt

  • idstringrequired
  • object"debt"required
  • contactIdstringrequired
  • contactNamestringrequired
  • clientIdstring | nullrequired
  • descriptionstringrequired
  • referencestringrequired
  • source"manual" | "invoice"required
    invoice = handed over to dunning from an invoice
  • invoiceIdstring | nullrequired
    Invoice the debt originates from – payments are reconciled
  • invoiceNumberstring | nullrequired
  • currency"EUR"required
  • principalCentsintegerrequired
    Principal amount
    -100000000000–100000000000
  • costsCentsintegerrequired
    Total costs
    -100000000000–100000000000
  • paidCentsintegerrequired
    Total payments including instalments
    -100000000000–100000000000
  • openCentsintegerrequired
    Outstanding: principal + costs − payments (0 if paid)
    -100000000000–100000000000
  • status"open" | "paid"required
  • overduebooleanrequired
  • dueDatestring (date) | nullrequired
    Date (YYYY-MM-DD)
  • paidAtstring (date-time) | nullrequired
    Timestamp (ISO 8601)
  • phaseenumrequired
    Values: new, reminder1, reminder2, reminder3, waiting, paymentplan, court, titled, enforcement, completed
  • courtStatus"pending" | "objection" | "hearing" | "judgment" | "appeal" | nullrequired
  • enforcementStatusenum | nullrequired
    Values: monitoring, asset_disclosure, bank_attachment, property_attachment, wage_attachment, vehicle_attachment, completed
  • isTitledbooleanrequired
    Enforceable title (Vollstreckungstitel) exists (flag; details in `title`)
  • inCourtbooleanrequired
    Court proceedings pending (flag)
  • reminderLevelintegerrequired
    0–3
  • followUpDatestring (date) | nullrequired
    Follow-up (Wiedervorlage)
  • autoPostalboolean | nullrequired
    Send dunning letters automatically by post (null = default)
  • notesstringrequired
  • titleDebtTitle | nullrequired
    • typeenumrequired
      Values: vollstreckungsbescheid, urteil, versaeumnisurteil, vergleich, kostenfestsetzungsbeschluss, notarielle_urkunde, sonstiger
    • courtstring
      max. 200 characters
    • fileNumberstring
      File reference (Aktenzeichen)
      max. 80 characters
    • datestring (date)
      Date (YYYY-MM-DD)
    • servedAtstring (date)
      Delivery
    • enforceableAtstring (date)
      Enforceable copy (vollstreckbare Ausfertigung)
    • notesstring
      max. 2000 characters
  • interestDebtInterestrequired
  • hasInstallmentPlanbooleanrequired
  • lastReminderSentAtstring (date-time) | nullrequired
    Timestamp (ISO 8601)
  • lastLetterSentAtstring (date-time) | nullrequired
    Timestamp (ISO 8601)
  • createdAtstring (date-time)required
    Timestamp (ISO 8601)
  • updatedAtstring (date-time)required
    Timestamp (ISO 8601)

Possible errors: 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"
  }
}'
Response 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"
}

Retrieve debt

GET/api/v1/debts/{id}

Permission: debts:read

Path parameters

  • idstringrequired
    Resource ID
    max. 128 characters

Response 200 · Debt

  • idstringrequired
  • object"debt"required
  • contactIdstringrequired
  • contactNamestringrequired
  • clientIdstring | nullrequired
  • descriptionstringrequired
  • referencestringrequired
  • source"manual" | "invoice"required
    invoice = handed over to dunning from an invoice
  • invoiceIdstring | nullrequired
    Invoice the debt originates from – payments are reconciled
  • invoiceNumberstring | nullrequired
  • currency"EUR"required
  • principalCentsintegerrequired
    Principal amount
    -100000000000–100000000000
  • costsCentsintegerrequired
    Total costs
    -100000000000–100000000000
  • paidCentsintegerrequired
    Total payments including instalments
    -100000000000–100000000000
  • openCentsintegerrequired
    Outstanding: principal + costs − payments (0 if paid)
    -100000000000–100000000000
  • status"open" | "paid"required
  • overduebooleanrequired
  • dueDatestring (date) | nullrequired
    Date (YYYY-MM-DD)
  • paidAtstring (date-time) | nullrequired
    Timestamp (ISO 8601)
  • phaseenumrequired
    Values: new, reminder1, reminder2, reminder3, waiting, paymentplan, court, titled, enforcement, completed
  • courtStatus"pending" | "objection" | "hearing" | "judgment" | "appeal" | nullrequired
  • enforcementStatusenum | nullrequired
    Values: monitoring, asset_disclosure, bank_attachment, property_attachment, wage_attachment, vehicle_attachment, completed
  • isTitledbooleanrequired
    Enforceable title (Vollstreckungstitel) exists (flag; details in `title`)
  • inCourtbooleanrequired
    Court proceedings pending (flag)
  • reminderLevelintegerrequired
    0–3
  • followUpDatestring (date) | nullrequired
    Follow-up (Wiedervorlage)
  • autoPostalboolean | nullrequired
    Send dunning letters automatically by post (null = default)
  • notesstringrequired
  • titleDebtTitle | nullrequired
    • typeenumrequired
      Values: vollstreckungsbescheid, urteil, versaeumnisurteil, vergleich, kostenfestsetzungsbeschluss, notarielle_urkunde, sonstiger
    • courtstring
      max. 200 characters
    • fileNumberstring
      File reference (Aktenzeichen)
      max. 80 characters
    • datestring (date)
      Date (YYYY-MM-DD)
    • servedAtstring (date)
      Delivery
    • enforceableAtstring (date)
      Enforceable copy (vollstreckbare Ausfertigung)
    • notesstring
      max. 2000 characters
  • interestDebtInterestrequired
  • hasInstallmentPlanbooleanrequired
  • lastReminderSentAtstring (date-time) | nullrequired
    Timestamp (ISO 8601)
  • lastLetterSentAtstring (date-time) | nullrequired
    Timestamp (ISO 8601)
  • createdAtstring (date-time)required
    Timestamp (ISO 8601)
  • updatedAtstring (date-time)required
    Timestamp (ISO 8601)

Possible errors: 400, 401, 403, 404, 429, 500

curl 'https://www.debt-flow.io/api/v1/debts/ID' \
  -H "Authorization: Bearer $DEBTFLOW_API_KEY"
Response 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"
}

Update debt

PATCH/api/v1/debts/{id}

Master data, follow-up date, client, enforceable title (title) and interest (interest). Change the phase via POST /debts/{id}/phase and the paid status via /mark-paid or /mark-unpaid respectively.

Permission: debts:write

Path parameters

  • idstringrequired
    Resource ID
    max. 128 characters

Body (JSON) · DebtUpdate

  • descriptionstring
    max. 1000 characters
  • amountCentsinteger
    Amount in cents
    0–100000000000
  • dueDatestring (date)
    Date (YYYY-MM-DD)
  • followUpDatestring (date) | null
    Date (YYYY-MM-DD)
  • referencestring
    max. 100 characters
  • notesstring
    max. 10000 characters
  • autoPostalboolean | null
  • reminderLevelinteger
    0–3
  • clientIdstring | null
    max. 128 characters
  • isTitledboolean
  • inCourtboolean
  • titleDebtTitle | null
    Record enforceable title (null removes it)
    • typeenumrequired
      Values: vollstreckungsbescheid, urteil, versaeumnisurteil, vergleich, kostenfestsetzungsbeschluss, notarielle_urkunde, sonstiger
    • courtstring
      max. 200 characters
    • fileNumberstring
      File reference (Aktenzeichen)
      max. 80 characters
    • datestring (date)
      Date (YYYY-MM-DD)
    • servedAtstring (date)
      Delivery
    • enforceableAtstring (date)
      Enforceable copy (vollstreckbare Ausfertigung)
    • notesstring
      max. 2000 characters
  • interestDebtInterest

Response 200 · Debt

  • idstringrequired
  • object"debt"required
  • contactIdstringrequired
  • contactNamestringrequired
  • clientIdstring | nullrequired
  • descriptionstringrequired
  • referencestringrequired
  • source"manual" | "invoice"required
    invoice = handed over to dunning from an invoice
  • invoiceIdstring | nullrequired
    Invoice the debt originates from – payments are reconciled
  • invoiceNumberstring | nullrequired
  • currency"EUR"required
  • principalCentsintegerrequired
    Principal amount
    -100000000000–100000000000
  • costsCentsintegerrequired
    Total costs
    -100000000000–100000000000
  • paidCentsintegerrequired
    Total payments including instalments
    -100000000000–100000000000
  • openCentsintegerrequired
    Outstanding: principal + costs − payments (0 if paid)
    -100000000000–100000000000
  • status"open" | "paid"required
  • overduebooleanrequired
  • dueDatestring (date) | nullrequired
    Date (YYYY-MM-DD)
  • paidAtstring (date-time) | nullrequired
    Timestamp (ISO 8601)
  • phaseenumrequired
    Values: new, reminder1, reminder2, reminder3, waiting, paymentplan, court, titled, enforcement, completed
  • courtStatus"pending" | "objection" | "hearing" | "judgment" | "appeal" | nullrequired
  • enforcementStatusenum | nullrequired
    Values: monitoring, asset_disclosure, bank_attachment, property_attachment, wage_attachment, vehicle_attachment, completed
  • isTitledbooleanrequired
    Enforceable title (Vollstreckungstitel) exists (flag; details in `title`)
  • inCourtbooleanrequired
    Court proceedings pending (flag)
  • reminderLevelintegerrequired
    0–3
  • followUpDatestring (date) | nullrequired
    Follow-up (Wiedervorlage)
  • autoPostalboolean | nullrequired
    Send dunning letters automatically by post (null = default)
  • notesstringrequired
  • titleDebtTitle | nullrequired
    • typeenumrequired
      Values: vollstreckungsbescheid, urteil, versaeumnisurteil, vergleich, kostenfestsetzungsbeschluss, notarielle_urkunde, sonstiger
    • courtstring
      max. 200 characters
    • fileNumberstring
      File reference (Aktenzeichen)
      max. 80 characters
    • datestring (date)
      Date (YYYY-MM-DD)
    • servedAtstring (date)
      Delivery
    • enforceableAtstring (date)
      Enforceable copy (vollstreckbare Ausfertigung)
    • notesstring
      max. 2000 characters
  • interestDebtInterestrequired
  • hasInstallmentPlanbooleanrequired
  • lastReminderSentAtstring (date-time) | nullrequired
    Timestamp (ISO 8601)
  • lastLetterSentAtstring (date-time) | nullrequired
    Timestamp (ISO 8601)
  • createdAtstring (date-time)required
    Timestamp (ISO 8601)
  • updatedAtstring (date-time)required
    Timestamp (ISO 8601)

Possible errors: 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"
  }
}'
Response 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"
}

Delete debt

DELETE/api/v1/debts/{id}

Permission: debts:write

Path parameters

  • idstringrequired
    Resource ID
    max. 128 characters

Response 204

Success, no content

Possible errors: 400, 401, 403, 404, 429, 500

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

Costs of a debt

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

Permission: debts:read

Path parameters

  • idstringrequired
    Resource ID
    max. 128 characters

Response 200

  • object"list"required
  • dataArray<DebtCost>required
    • idstringrequired
    • object"cost"required
    • debtIdstringrequired
    • amountCentsintegerrequired
      Amount in cents
      -100000000000–100000000000
    • datestring (date) | nullrequired
      Date (YYYY-MM-DD)
    • costTypestringrequired
    • descriptionstringrequired
    • invoiceNumberstringrequired
    • isPaidbooleanrequired
    • isChargeablebooleanrequired
      Recoverable (borne by the debtor)
    • interestBearingbooleanrequired
      Included in the interest calculation

Possible errors: 400, 401, 403, 404, 429, 500

curl 'https://www.debt-flow.io/api/v1/debts/ID/costs' \
  -H "Authorization: Bearer $DEBTFLOW_API_KEY"
Response 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
    }
  ]
}

Record costs

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

Dunning, court, lawyer's or enforcement costs. Increases the outstanding amount.

Permission: debts:write

Path parameters

  • idstringrequired
    Resource ID
    max. 128 characters

Headers

  • Idempotency-Keystring
    Unique key (8–255 characters). Repeated requests with the same key return the same response for 24 h.
    max. 255 characters

Body (JSON) · DebtCostCreate

  • amountCentsintegerrequired
    Amount in cents
    0–100000000000
  • costTypestringrequired
    e.g. dunning_fee, court_fee, lawyer_fee, bailiff_fee, other
    max. 60 characters
  • descriptionstringrequired
    max. 500 characters
  • datestring (date)
    Date (YYYY-MM-DD)
  • invoiceNumberstring
    max. 60 characters
  • isPaidboolean
  • isChargeableboolean
  • interestBearingboolean

Response 201 · DebtCost

  • idstringrequired
  • object"cost"required
  • debtIdstringrequired
  • amountCentsintegerrequired
    Amount in cents
    -100000000000–100000000000
  • datestring (date) | nullrequired
    Date (YYYY-MM-DD)
  • costTypestringrequired
  • descriptionstringrequired
  • invoiceNumberstringrequired
  • isPaidbooleanrequired
  • isChargeablebooleanrequired
    Recoverable (borne by the debtor)
  • interestBearingbooleanrequired
    Included in the interest calculation

Possible errors: 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
}'
Response 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
}

Remove costs

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

Permission: debts:write

Path parameters

  • idstringrequired
    max. 128 characters
  • costIdstringrequired
    max. 128 characters

Response 204

Success, no content

Possible errors: 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"

History of a debt

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

Log of all actions (phase changes, payments, letters …), newest first.

Permission: debts:read

Path parameters

  • idstringrequired
    Resource ID
    max. 128 characters

Response 200

  • object"list"required
  • dataArray<DebtHistoryEntry>required
    • idstringrequired
    • actionstringrequired
    • detailsstringrequired
    • performedBystring | nullrequired
    • createdAtstring (date-time)required
      Timestamp (ISO 8601)

Possible errors: 400, 401, 403, 404, 429, 500

curl 'https://www.debt-flow.io/api/v1/debts/ID/history' \
  -H "Authorization: Bearer $DEBTFLOW_API_KEY"
Response 200
{
  "object": "list",
  "data": [
    {
      "id": "string",
      "action": "string",
      "details": "string",
      "performedBy": "string",
      "createdAt": "2026-11-01T09:30:00.000Z"
    }
  ]
}

Mark as paid

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

Sets the phase to completed (the previous phase is remembered). Event debt.paid.

Permission: debts:write

Path parameters

  • idstringrequired
    Resource ID
    max. 128 characters

Headers

  • Idempotency-Keystring
    Unique key (8–255 characters). Repeated requests with the same key return the same response for 24 h.
    max. 255 characters

Response 200 · Debt

  • idstringrequired
  • object"debt"required
  • contactIdstringrequired
  • contactNamestringrequired
  • clientIdstring | nullrequired
  • descriptionstringrequired
  • referencestringrequired
  • source"manual" | "invoice"required
    invoice = handed over to dunning from an invoice
  • invoiceIdstring | nullrequired
    Invoice the debt originates from – payments are reconciled
  • invoiceNumberstring | nullrequired
  • currency"EUR"required
  • principalCentsintegerrequired
    Principal amount
    -100000000000–100000000000
  • costsCentsintegerrequired
    Total costs
    -100000000000–100000000000
  • paidCentsintegerrequired
    Total payments including instalments
    -100000000000–100000000000
  • openCentsintegerrequired
    Outstanding: principal + costs − payments (0 if paid)
    -100000000000–100000000000
  • status"open" | "paid"required
  • overduebooleanrequired
  • dueDatestring (date) | nullrequired
    Date (YYYY-MM-DD)
  • paidAtstring (date-time) | nullrequired
    Timestamp (ISO 8601)
  • phaseenumrequired
    Values: new, reminder1, reminder2, reminder3, waiting, paymentplan, court, titled, enforcement, completed
  • courtStatus"pending" | "objection" | "hearing" | "judgment" | "appeal" | nullrequired
  • enforcementStatusenum | nullrequired
    Values: monitoring, asset_disclosure, bank_attachment, property_attachment, wage_attachment, vehicle_attachment, completed
  • isTitledbooleanrequired
    Enforceable title (Vollstreckungstitel) exists (flag; details in `title`)
  • inCourtbooleanrequired
    Court proceedings pending (flag)
  • reminderLevelintegerrequired
    0–3
  • followUpDatestring (date) | nullrequired
    Follow-up (Wiedervorlage)
  • autoPostalboolean | nullrequired
    Send dunning letters automatically by post (null = default)
  • notesstringrequired
  • titleDebtTitle | nullrequired
    • typeenumrequired
      Values: vollstreckungsbescheid, urteil, versaeumnisurteil, vergleich, kostenfestsetzungsbeschluss, notarielle_urkunde, sonstiger
    • courtstring
      max. 200 characters
    • fileNumberstring
      File reference (Aktenzeichen)
      max. 80 characters
    • datestring (date)
      Date (YYYY-MM-DD)
    • servedAtstring (date)
      Delivery
    • enforceableAtstring (date)
      Enforceable copy (vollstreckbare Ausfertigung)
    • notesstring
      max. 2000 characters
  • interestDebtInterestrequired
  • hasInstallmentPlanbooleanrequired
  • lastReminderSentAtstring (date-time) | nullrequired
    Timestamp (ISO 8601)
  • lastLetterSentAtstring (date-time) | nullrequired
    Timestamp (ISO 8601)
  • createdAtstring (date-time)required
    Timestamp (ISO 8601)
  • updatedAtstring (date-time)required
    Timestamp (ISO 8601)

Possible errors: 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"
Response 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"
}

Remove paid mark

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

Restores the phase that applied before it was marked as paid.

Permission: debts:write

Path parameters

  • idstringrequired
    Resource ID
    max. 128 characters

Headers

  • Idempotency-Keystring
    Unique key (8–255 characters). Repeated requests with the same key return the same response for 24 h.
    max. 255 characters

Response 200 · Debt

  • idstringrequired
  • object"debt"required
  • contactIdstringrequired
  • contactNamestringrequired
  • clientIdstring | nullrequired
  • descriptionstringrequired
  • referencestringrequired
  • source"manual" | "invoice"required
    invoice = handed over to dunning from an invoice
  • invoiceIdstring | nullrequired
    Invoice the debt originates from – payments are reconciled
  • invoiceNumberstring | nullrequired
  • currency"EUR"required
  • principalCentsintegerrequired
    Principal amount
    -100000000000–100000000000
  • costsCentsintegerrequired
    Total costs
    -100000000000–100000000000
  • paidCentsintegerrequired
    Total payments including instalments
    -100000000000–100000000000
  • openCentsintegerrequired
    Outstanding: principal + costs − payments (0 if paid)
    -100000000000–100000000000
  • status"open" | "paid"required
  • overduebooleanrequired
  • dueDatestring (date) | nullrequired
    Date (YYYY-MM-DD)
  • paidAtstring (date-time) | nullrequired
    Timestamp (ISO 8601)
  • phaseenumrequired
    Values: new, reminder1, reminder2, reminder3, waiting, paymentplan, court, titled, enforcement, completed
  • courtStatus"pending" | "objection" | "hearing" | "judgment" | "appeal" | nullrequired
  • enforcementStatusenum | nullrequired
    Values: monitoring, asset_disclosure, bank_attachment, property_attachment, wage_attachment, vehicle_attachment, completed
  • isTitledbooleanrequired
    Enforceable title (Vollstreckungstitel) exists (flag; details in `title`)
  • inCourtbooleanrequired
    Court proceedings pending (flag)
  • reminderLevelintegerrequired
    0–3
  • followUpDatestring (date) | nullrequired
    Follow-up (Wiedervorlage)
  • autoPostalboolean | nullrequired
    Send dunning letters automatically by post (null = default)
  • notesstringrequired
  • titleDebtTitle | nullrequired
    • typeenumrequired
      Values: vollstreckungsbescheid, urteil, versaeumnisurteil, vergleich, kostenfestsetzungsbeschluss, notarielle_urkunde, sonstiger
    • courtstring
      max. 200 characters
    • fileNumberstring
      File reference (Aktenzeichen)
      max. 80 characters
    • datestring (date)
      Date (YYYY-MM-DD)
    • servedAtstring (date)
      Delivery
    • enforceableAtstring (date)
      Enforceable copy (vollstreckbare Ausfertigung)
    • notesstring
      max. 2000 characters
  • interestDebtInterestrequired
  • hasInstallmentPlanbooleanrequired
  • lastReminderSentAtstring (date-time) | nullrequired
    Timestamp (ISO 8601)
  • lastLetterSentAtstring (date-time) | nullrequired
    Timestamp (ISO 8601)
  • createdAtstring (date-time)required
    Timestamp (ISO 8601)
  • updatedAtstring (date-time)required
    Timestamp (ISO 8601)

Possible errors: 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"
Response 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"
}

Communication log

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

Permission: debts:read

Path parameters

  • idstringrequired
    Resource ID
    max. 128 characters

Response 200

  • object"list"required
  • dataArray<DebtMessage>required
    • idstringrequired
    • object"debt_message"required
    • debtIdstringrequired
    • typestringrequired
      note, email, phone, letter …
    • textstringrequired
    • sentToEmailstring | nullrequired
    • sentBystringrequired
    • createdAtstring (date-time)required
      Timestamp (ISO 8601)

Possible errors: 400, 401, 403, 404, 429, 500

curl 'https://www.debt-flow.io/api/v1/debts/ID/messages' \
  -H "Authorization: Bearer $DEBTFLOW_API_KEY"
Response 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"
    }
  ]
}

Log communication

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

Record a note, phone call, email or similar. Nothing is sent.

Permission: debts:write

Path parameters

  • idstringrequired
    Resource ID
    max. 128 characters

Headers

  • Idempotency-Keystring
    Unique key (8–255 characters). Repeated requests with the same key return the same response for 24 h.
    max. 255 characters

Body (JSON) · DebtMessageCreate

  • typeenumrequired
    Values: note, email, phone, sms, letter, meeting, other
  • textstringrequired
    max. 10000 characters
  • sentToEmailstring (email)
    max. 254 characters

Response 201 · DebtMessage

  • idstringrequired
  • object"debt_message"required
  • debtIdstringrequired
  • typestringrequired
    note, email, phone, letter …
  • textstringrequired
  • sentToEmailstring | nullrequired
  • sentBystringrequired
  • createdAtstring (date-time)required
    Timestamp (ISO 8601)

Possible errors: 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]"
}'
Response 201
{
  "id": "string",
  "object": "debt_message",
  "debtId": "string",
  "type": "string",
  "text": "string",
  "sentToEmail": "string",
  "sentBy": "string",
  "createdAt": "2026-11-01T09:30:00.000Z"
}

Change phase

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

Phases: new → reminder1/2/3 → waiting → paymentplan → court (courtStatus) → titled → enforcement (enforcementStatus) → completed. Event debt.phase_changed with the previous phase in data.previous.

Permission: debts:write

Path parameters

  • idstringrequired
    Resource ID
    max. 128 characters

Headers

  • Idempotency-Keystring
    Unique key (8–255 characters). Repeated requests with the same key return the same response for 24 h.
    max. 255 characters

Body (JSON) · DebtPhaseChange

  • phaseenumrequired
    Values: new, reminder1, reminder2, reminder3, waiting, paymentplan, court, titled, enforcement, completed
  • courtStatus"pending" | "objection" | "hearing" | "judgment" | "appeal"
    only if phase=court
  • enforcementStatusenum
    only if phase=enforcement
    Values: monitoring, asset_disclosure, bank_attachment, property_attachment, wage_attachment, vehicle_attachment, completed

Response 200 · Debt

  • idstringrequired
  • object"debt"required
  • contactIdstringrequired
  • contactNamestringrequired
  • clientIdstring | nullrequired
  • descriptionstringrequired
  • referencestringrequired
  • source"manual" | "invoice"required
    invoice = handed over to dunning from an invoice
  • invoiceIdstring | nullrequired
    Invoice the debt originates from – payments are reconciled
  • invoiceNumberstring | nullrequired
  • currency"EUR"required
  • principalCentsintegerrequired
    Principal amount
    -100000000000–100000000000
  • costsCentsintegerrequired
    Total costs
    -100000000000–100000000000
  • paidCentsintegerrequired
    Total payments including instalments
    -100000000000–100000000000
  • openCentsintegerrequired
    Outstanding: principal + costs − payments (0 if paid)
    -100000000000–100000000000
  • status"open" | "paid"required
  • overduebooleanrequired
  • dueDatestring (date) | nullrequired
    Date (YYYY-MM-DD)
  • paidAtstring (date-time) | nullrequired
    Timestamp (ISO 8601)
  • phaseenumrequired
    Values: new, reminder1, reminder2, reminder3, waiting, paymentplan, court, titled, enforcement, completed
  • courtStatus"pending" | "objection" | "hearing" | "judgment" | "appeal" | nullrequired
  • enforcementStatusenum | nullrequired
    Values: monitoring, asset_disclosure, bank_attachment, property_attachment, wage_attachment, vehicle_attachment, completed
  • isTitledbooleanrequired
    Enforceable title (Vollstreckungstitel) exists (flag; details in `title`)
  • inCourtbooleanrequired
    Court proceedings pending (flag)
  • reminderLevelintegerrequired
    0–3
  • followUpDatestring (date) | nullrequired
    Follow-up (Wiedervorlage)
  • autoPostalboolean | nullrequired
    Send dunning letters automatically by post (null = default)
  • notesstringrequired
  • titleDebtTitle | nullrequired
    • typeenumrequired
      Values: vollstreckungsbescheid, urteil, versaeumnisurteil, vergleich, kostenfestsetzungsbeschluss, notarielle_urkunde, sonstiger
    • courtstring
      max. 200 characters
    • fileNumberstring
      File reference (Aktenzeichen)
      max. 80 characters
    • datestring (date)
      Date (YYYY-MM-DD)
    • servedAtstring (date)
      Delivery
    • enforceableAtstring (date)
      Enforceable copy (vollstreckbare Ausfertigung)
    • notesstring
      max. 2000 characters
  • interestDebtInterestrequired
  • hasInstallmentPlanbooleanrequired
  • lastReminderSentAtstring (date-time) | nullrequired
    Timestamp (ISO 8601)
  • lastLetterSentAtstring (date-time) | nullrequired
    Timestamp (ISO 8601)
  • createdAtstring (date-time)required
    Timestamp (ISO 8601)
  • updatedAtstring (date-time)required
    Timestamp (ISO 8601)

Possible errors: 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"
}'
Response 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"
}

Statement of debt

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

Statement as at the reference date with default interest calculated to the day (base rate + 5/9 percentage points or a fixed rate), allocation order costs → interest → principal (§ 367 BGB).

Permission: debts:read

Path parameters

  • idstringrequired
    Resource ID
    max. 128 characters

Query parameters

  • untilstring (date)
    Reference date, default: today

Response 200 · DebtStatement

  • untilstring (date)required
    Date (YYYY-MM-DD)
  • rateLabelstringrequired
  • principalCentsintegerrequired
    Amount in cents
    -100000000000–100000000000
  • costsCentsintegerrequired
    Amount in cents
    -100000000000–100000000000
  • interestCentsintegerrequired
    Amount in cents
    -100000000000–100000000000
  • paymentsCentsintegerrequired
    Amount in cents
    -100000000000–100000000000
  • openobjectrequired
    • principalCentsintegerrequired
      Amount in cents
      -100000000000–100000000000
    • interestCentsintegerrequired
      Amount in cents
      -100000000000–100000000000
    • costsCentsintegerrequired
      Amount in cents
      -100000000000–100000000000
    • totalCentsintegerrequired
      Amount in cents
      -100000000000–100000000000
  • interestRowsArray<object>required
    • fromstring (date)required
      Date (YYYY-MM-DD)
    • tostring (date)required
      Date (YYYY-MM-DD)
    • daysintegerrequired
      -9007199254740991–9007199254740991
    • ratenumberrequired
    • basisCentsintegerrequired
      Amount in cents
      -100000000000–100000000000
    • amountCentsintegerrequired
      Amount in cents
      -100000000000–100000000000
    • on"principal" | "costs"required
  • paymentRowsArray<object>required
    • datestring (date)required
      Date (YYYY-MM-DD)
    • amountCentsintegerrequired
      Amount in cents
      -100000000000–100000000000
    • labelstring | nullrequired
    • toCostsCentsintegerrequired
      Amount in cents
      -100000000000–100000000000
    • toInterestCentsintegerrequired
      Amount in cents
      -100000000000–100000000000
    • toPrincipalCentsintegerrequired
      Amount in cents
      -100000000000–100000000000
    • surplusCentsintegerrequired
      Amount in cents
      -100000000000–100000000000
  • costsArray<object>required
    • datestring (date)required
      Date (YYYY-MM-DD)
    • amountCentsintegerrequired
      Amount in cents
      -100000000000–100000000000
    • labelstringrequired
    • interestBearingbooleanrequired
  • warningsArray<string>required

Possible errors: 400, 401, 403, 404, 429, 500

curl 'https://www.debt-flow.io/api/v1/debts/ID/statement' \
  -H "Authorization: Bearer $DEBTFLOW_API_KEY"
Response 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"
  ]
}

Calculate interest (interest calculator)

POST/api/v1/interest-calculations

Calculates a statement of debt from the values provided, without saving anything. The Bundesbank base interest rates are built in.

Permission: debts:read

Body (JSON) · InterestCalculation

  • principalCentsintegerrequired
    Amount in cents
    0–100000000000
  • interestDebtInterestrequired
  • untilstring (date)required
    Reference date (inclusive)
  • costsArray<object>
    • datestring (date)required
      Date (YYYY-MM-DD)
    • amountCentsintegerrequired
      Amount in cents
      0–100000000000
    • labelstring
      max. 200 characters · Default: "Kosten"
    • interestBearingboolean
      Default: false
  • paymentsArray<object>
    • datestring (date)required
      Date (YYYY-MM-DD)
    • amountCentsintegerrequired
      Amount in cents
      0–100000000000
    • labelstring
      max. 200 characters

Response 200 · DebtStatement

  • untilstring (date)required
    Date (YYYY-MM-DD)
  • rateLabelstringrequired
  • principalCentsintegerrequired
    Amount in cents
    -100000000000–100000000000
  • costsCentsintegerrequired
    Amount in cents
    -100000000000–100000000000
  • interestCentsintegerrequired
    Amount in cents
    -100000000000–100000000000
  • paymentsCentsintegerrequired
    Amount in cents
    -100000000000–100000000000
  • openobjectrequired
    • principalCentsintegerrequired
      Amount in cents
      -100000000000–100000000000
    • interestCentsintegerrequired
      Amount in cents
      -100000000000–100000000000
    • costsCentsintegerrequired
      Amount in cents
      -100000000000–100000000000
    • totalCentsintegerrequired
      Amount in cents
      -100000000000–100000000000
  • interestRowsArray<object>required
    • fromstring (date)required
      Date (YYYY-MM-DD)
    • tostring (date)required
      Date (YYYY-MM-DD)
    • daysintegerrequired
      -9007199254740991–9007199254740991
    • ratenumberrequired
    • basisCentsintegerrequired
      Amount in cents
      -100000000000–100000000000
    • amountCentsintegerrequired
      Amount in cents
      -100000000000–100000000000
    • on"principal" | "costs"required
  • paymentRowsArray<object>required
    • datestring (date)required
      Date (YYYY-MM-DD)
    • amountCentsintegerrequired
      Amount in cents
      -100000000000–100000000000
    • labelstring | nullrequired
    • toCostsCentsintegerrequired
      Amount in cents
      -100000000000–100000000000
    • toInterestCentsintegerrequired
      Amount in cents
      -100000000000–100000000000
    • toPrincipalCentsintegerrequired
      Amount in cents
      -100000000000–100000000000
    • surplusCentsintegerrequired
      Amount in cents
      -100000000000–100000000000
  • costsArray<object>required
    • datestring (date)required
      Date (YYYY-MM-DD)
    • amountCentsintegerrequired
      Amount in cents
      -100000000000–100000000000
    • labelstringrequired
    • interestBearingbooleanrequired
  • warningsArray<string>required

Possible errors: 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": []
}'
Response 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"
  ]
}

Debt overview (key figures)

GET/api/v1/reports/receivables

Key figures as on the dashboard home page: totals, overdue debts, instalments due in the next 7 days, latest payments, incoming payments of the last 6 months and distribution by phase.

Permission: debts:read

Response 200 · ReceivablesSummary

  • object"receivables_summary"required
  • statsobjectrequired
    • totalCentsintegerrequired
      Sum of all principal amounts
      -100000000000–100000000000
    • contactCountintegerrequired
      -9007199254740991–9007199254740991
    • openCentsintegerrequired
      Outstanding including costs less payments
      -100000000000–100000000000
    • overdueCentsintegerrequired
      Amount in cents
      -100000000000–100000000000
    • overdueCountintegerrequired
      -9007199254740991–9007199254740991
    • incomeThisMonthCentsintegerrequired
      Amount in cents
      -100000000000–100000000000
    • activeDebtsintegerrequired
      -9007199254740991–9007199254740991
  • overdueDebtsArray<object>required
    • debtIdstringrequired
    • contactIdstringrequired
    • contactNamestringrequired
    • descriptionstringrequired
    • openCentsintegerrequired
      Amount in cents
      -100000000000–100000000000
    • dueDatestring (date) | nullrequired
      Date (YYYY-MM-DD)
    • daysOverdueintegerrequired
      -9007199254740991–9007199254740991
  • upcomingInstallmentsArray<object>required
    • debtIdstringrequired
    • installmentPlanIdstringrequired
    • contactNamestringrequired
    • descriptionstringrequired
    • amountCentsintegerrequired
      Amount in cents
      -100000000000–100000000000
    • dueDatestring (date)required
      Date (YYYY-MM-DD)
  • recentPaymentsArray<object>required
    • idstringrequired
    • debtIdstringrequired
    • contactIdstringrequired
    • contactNamestringrequired
    • descriptionstringrequired
    • amountCentsintegerrequired
      Amount in cents
      -100000000000–100000000000
    • datestring (date) | nullrequired
      Date (YYYY-MM-DD)
    • type"single" | "installment"required
  • incomeByMonthArray<object>required
    • monthstringrequired
      YYYY-MM
    • amountCentsintegerrequired
      Amount in cents
      -100000000000–100000000000
  • phasesArray<object>required
    • phasestringrequired
    • countintegerrequired
      -9007199254740991–9007199254740991
    • openCentsintegerrequired
      Amount in cents
      -100000000000–100000000000
  • onboardingobjectrequired
    • hasSenderAddressbooleanrequired
    • hasContactsbooleanrequired
    • hasDebtsbooleanrequired
    • autoDunningbooleanrequired

Possible errors: 400, 401, 403, 429, 500

curl 'https://www.debt-flow.io/api/v1/reports/receivables' \
  -H "Authorization: Bearer $DEBTFLOW_API_KEY"
Response 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
  }
}