Letters – API reference

Send letter by post

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

Chargeable: printing and dispatch via Briefdiener (subscription plan quota or your own Briefdiener account). Dunning levels use the standard text; custom requires content. Always send an Idempotency-Key so that retries do not trigger a second letter. Errors: 402 quota_exceeded/not_available, 422 missing_address.

Permission: letters: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) · LetterSend

kind"reminder1" | "reminder2" | "reminder3" | "custom"required
registeredboolean
subjectstring
max. 300 characters
contentstring
Required if kind=custom; otherwise default text of the dunning level
max. 20000 characters

Response 201 · Letter

idstringrequired
object"letter"required
debtIdstringrequired
contactIdstringrequired
contactNamestringrequired
kind"reminder1" | "reminder2" | "reminder3" | "custom"required
subjectstringrequired
status"sending" | "sent" | "failed"required
deliveryStatus"pending" | "delivered" | "failed" | "returned" | nullrequired
mode"own" | "central"required
own Briefdiener account or subscription plan quota
trigger"manual" | "auto"required
registeredbooleanrequired
Registered mail
trackingRefstring | nullrequired
trackingUrlstring | nullrequired
pageCountinteger | nullrequired
-9007199254740991–9007199254740991
priceEurostring | nullrequired
errorstring | nullrequired
createdAtstring (date-time)required
Timestamp (ISO 8601)
sentAtstring (date-time) | nullrequired
Timestamp (ISO 8601)

Possible errors: 400, 401, 402, 403, 404, 409, 422, 429, 500

curl -X POST 'https://www.debt-flow.io/api/v1/debts/ID/letters' \
  -H "Authorization: Bearer $DEBTFLOW_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
  "kind": "reminder1",
  "registered": false,
  "subject": "string",
  "content": "string"
}'

Response 201

{
  "id": "string",
  "object": "letter",
  "debtId": "string",
  "contactId": "string",
  "contactName": "string",
  "kind": "reminder1",
  "subject": "string",
  "status": "sending",
  "deliveryStatus": "pending",
  "mode": "own",
  "trigger": "manual",
  "registered": false,
  "trackingRef": "string",
  "trackingUrl": "string",
  "pageCount": 0,
  "priceEuro": "string",
  "error": "string",
  "createdAt": "2026-11-01T09:30:00.000Z",
  "sentAt": "2026-11-01T09:30:00.000Z"
}

Letter preview

POST/api/v1/debts/{id}/letters/preview

Returns the text, addresses, page count/price (if available) and reasons preventing dispatch – does not send anything.

Permission: letters:read

Path parameters

idstringrequired
Resource ID
max. 128 characters

Body (JSON) · LetterSend

kind"reminder1" | "reminder2" | "reminder3" | "custom"required
registeredboolean
subjectstring
max. 300 characters
contentstring
Required if kind=custom; otherwise default text of the dunning level
max. 20000 characters

Response 200 · LetterPreview

subjectstringrequired
salutationstringrequired
contentstringrequired
closingstringrequired
signatureNamestringrequired
senderobjectrequired
- namestringrequired
- companystring
- addressstringrequired
recipientobjectrequired
- namestringrequired
- companystring
- addressstringrequired
referencestringrequired
pageCountinteger | nullrequired
-9007199254740991–9007199254740991
priceEurostring | nullrequired
quotaobjectrequired
- mode"own" | "central" | "none"required
- usedintegerrequired
  -9007199254740991–9007199254740991
- limitinteger | nullrequired
  -9007199254740991–9007199254740991
- periodStartstring | nullrequired
- periodEndstring | nullrequired
problemsArray<string>required
Reasons why the letter cannot be sent as is

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

curl -X POST 'https://www.debt-flow.io/api/v1/debts/ID/letters/preview' \
  -H "Authorization: Bearer $DEBTFLOW_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
  "kind": "reminder1",
  "registered": false,
  "subject": "string",
  "content": "string"
}'

Response 200

{
  "subject": "string",
  "salutation": "string",
  "content": "string",
  "closing": "string",
  "signatureName": "string",
  "sender": {
    "name": "string",
    "company": "string",
    "address": "string"
  },
  "recipient": {
    "name": "string",
    "company": "string",
    "address": "string"
  },
  "reference": "string",
  "pageCount": 0,
  "priceEuro": "string",
  "quota": {
    "mode": "own",
    "used": 0,
    "limit": 0,
    "periodStart": "string",
    "periodEnd": "string"
  },
  "problems": [
    "string"
  ]
}

List letters

GET/api/v1/letters

Sent letters with dispatch and delivery status, newest first.

Permission: letters:read

Query parameters

debtIdstring
max. 128 characters
contactIdstring
max. 128 characters
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<Letter>required
- idstringrequired
- object"letter"required
- debtIdstringrequired
- contactIdstringrequired
- contactNamestringrequired
- kind"reminder1" | "reminder2" | "reminder3" | "custom"required
- subjectstringrequired
- status"sending" | "sent" | "failed"required
- deliveryStatus"pending" | "delivered" | "failed" | "returned" | nullrequired
- mode"own" | "central"required
  own Briefdiener account or subscription plan quota
- trigger"manual" | "auto"required
- registeredbooleanrequired
  Registered mail
- trackingRefstring | nullrequired
- trackingUrlstring | nullrequired
- pageCountinteger | nullrequired
  -9007199254740991–9007199254740991
- priceEurostring | nullrequired
- errorstring | nullrequired
- createdAtstring (date-time)required
  Timestamp (ISO 8601)
- sentAtstring (date-time) | nullrequired
  Timestamp (ISO 8601)
hasMorebooleanrequired
nextCursorstring | nullrequired

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

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

Response 200

{
  "object": "list",
  "data": [
    {
      "id": "string",
      "object": "letter",
      "debtId": "string",
      "contactId": "string",
      "contactName": "string",
      "kind": "reminder1",
      "subject": "string",
      "status": "sending",
      "deliveryStatus": "pending",
      "mode": "own",
      "trigger": "manual",
      "registered": false,
      "trackingRef": "string",
      "trackingUrl": "string",
      "pageCount": 0,
      "priceEuro": "string",
      "error": "string",
      "createdAt": "2026-11-01T09:30:00.000Z",
      "sentAt": "2026-11-01T09:30:00.000Z"
    }
  ],
  "hasMore": false,
  "nextCursor": "string"
}

Retrieve letter and delivery status

GET/api/v1/letters/{id}

Permission: letters:read

Path parameters

idstringrequired
Resource ID
max. 128 characters

Response 200 · Letter

idstringrequired
object"letter"required
debtIdstringrequired
contactIdstringrequired
contactNamestringrequired
kind"reminder1" | "reminder2" | "reminder3" | "custom"required
subjectstringrequired
status"sending" | "sent" | "failed"required
deliveryStatus"pending" | "delivered" | "failed" | "returned" | nullrequired
mode"own" | "central"required
own Briefdiener account or subscription plan quota
trigger"manual" | "auto"required
registeredbooleanrequired
Registered mail
trackingRefstring | nullrequired
trackingUrlstring | nullrequired
pageCountinteger | nullrequired
-9007199254740991–9007199254740991
priceEurostring | nullrequired
errorstring | nullrequired
createdAtstring (date-time)required
Timestamp (ISO 8601)
sentAtstring (date-time) | nullrequired
Timestamp (ISO 8601)

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

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

Response 200

{
  "id": "string",
  "object": "letter",
  "debtId": "string",
  "contactId": "string",
  "contactName": "string",
  "kind": "reminder1",
  "subject": "string",
  "status": "sending",
  "deliveryStatus": "pending",
  "mode": "own",
  "trigger": "manual",
  "registered": false,
  "trackingRef": "string",
  "trackingUrl": "string",
  "pageCount": 0,
  "priceEuro": "string",
  "error": "string",
  "createdAt": "2026-11-01T09:30:00.000Z",
  "sentAt": "2026-11-01T09:30:00.000Z"
}

Retrieve letter quota

GET/api/v1/letters/quota

central = quota of the subscription plan (used/limit per month), own = your own Briefdiener account, none = not available (reason).

Permission: letters:read

Response 200 · LetterQuota

mode"own" | "central" | "none"required
usedintegerrequired
-9007199254740991–9007199254740991
limitinteger | nullrequired
-9007199254740991–9007199254740991
periodStartstring | nullrequired
periodEndstring | nullrequired
reasonstring | nullrequired

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

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

Response 200

{
  "mode": "own",
  "used": 0,
  "limit": 0,
  "periodStart": "string",
  "periodEnd": "string",
  "reason": "string"
}