Account – API reference

Retrieve company and invoicing master data

GET/api/v1/company-profile

Sender, tax number/VAT ID, small business (Kleinunternehmer) status, bank details, logo and invoice footer. missing lists missing required details.

Permission: profile:read

Response 200 · CompanyProfile

companyNamestringrequired
Company or name of the business owner (shown as sender)
ownerNamestringrequired
Owner (for sole proprietorships)
legalFormstringrequired
managingDirectorsstringrequired
Managing directors/board (required for corporations)
addressobjectrequired
- streetstringrequired
- zipCodestringrequired
- citystringrequired
- countryCodestringrequired
phonestringrequired
emailstringrequired
websitestringrequired
taxNumberstringrequired
Tax number from the tax office
vatIdstringrequired
VAT identification number
smallBusinessbooleanrequired
Small business under § 19 UStG (no VAT shown)
commercialRegisterobjectrequired
- courtstringrequired
- numberstringrequired
bankobjectrequired
- accountHolderstringrequired
- ibanstringrequired
- bicstringrequired
- bankNamestringrequired
logoCompanyLogo | nullrequired
- contentType"image/png" | "image/jpeg"required
- sizeintegerrequired
  -9007199254740991–9007199254740991
- updatedAtstringrequired
invoiceFooterstringrequired
Custom footer on invoices
paymentTermsDaysintegerrequired
Default payment term in days
-9007199254740991–9007199254740991
completebooleanrequired
Mandatory invoice details (§ 14 UStG) complete
missingArray<string>required
Missing details (plain text)

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

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

Response 200

{
  "companyName": "string",
  "ownerName": "string",
  "legalForm": "string",
  "managingDirectors": "string",
  "address": {
    "street": "string",
    "zipCode": "string",
    "city": "string",
    "countryCode": "string"
  },
  "phone": "string",
  "email": "string",
  "website": "string",
  "taxNumber": "string",
  "vatId": "string",
  "smallBusiness": false,
  "commercialRegister": {
    "court": "string",
    "number": "string"
  },
  "bank": {
    "accountHolder": "string",
    "iban": "string",
    "bic": "string",
    "bankName": "string"
  },
  "logo": {
    "contentType": "image/png",
    "size": 0,
    "updatedAt": "string"
  },
  "invoiceFooter": "string",
  "paymentTermsDays": 0,
  "complete": false,
  "missing": [
    "string"
  ]
}

Update company and invoicing master data

PATCH/api/v1/company-profile

Only the fields you pass are changed. An empty string deletes a value. Changes are logged; documents that have already been finalised keep their details.

Permission: profile:write

Body (JSON) · CompanyProfileUpdate

companyNamestring
max. 160 characters
ownerNamestring
max. 120 characters
legalFormenum | ""
managingDirectorsstring
max. 300 characters
addressobject
- streetstring
  max. 160 characters
- zipCodestring
  max. 10 characters
- citystring
  max. 80 characters
- countryCodestring
phonestring
max. 40 characters
emailstring (email) | ""
websitestring
max. 200 characters
taxNumberstring
max. 20 characters
vatIdstring
smallBusinessboolean
commercialRegisterobject
- courtstring
  max. 120 characters
- numberstring
  max. 60 characters
bankobject
- accountHolderstring
  max. 120 characters
- ibanstring
- bicstring
- bankNamestring
  max. 80 characters
invoiceFooterstring
max. 1000 characters
paymentTermsDaysinteger
0–365

Response 200 · CompanyProfile

companyNamestringrequired
Company or name of the business owner (shown as sender)
ownerNamestringrequired
Owner (for sole proprietorships)
legalFormstringrequired
managingDirectorsstringrequired
Managing directors/board (required for corporations)
addressobjectrequired
- streetstringrequired
- zipCodestringrequired
- citystringrequired
- countryCodestringrequired
phonestringrequired
emailstringrequired
websitestringrequired
taxNumberstringrequired
Tax number from the tax office
vatIdstringrequired
VAT identification number
smallBusinessbooleanrequired
Small business under § 19 UStG (no VAT shown)
commercialRegisterobjectrequired
- courtstringrequired
- numberstringrequired
bankobjectrequired
- accountHolderstringrequired
- ibanstringrequired
- bicstringrequired
- bankNamestringrequired
logoCompanyLogo | nullrequired
- contentType"image/png" | "image/jpeg"required
- sizeintegerrequired
  -9007199254740991–9007199254740991
- updatedAtstringrequired
invoiceFooterstringrequired
Custom footer on invoices
paymentTermsDaysintegerrequired
Default payment term in days
-9007199254740991–9007199254740991
completebooleanrequired
Mandatory invoice details (§ 14 UStG) complete
missingArray<string>required
Missing details (plain text)

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

curl -X PATCH 'https://www.debt-flow.io/api/v1/company-profile' \
  -H "Authorization: Bearer $DEBTFLOW_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
  "companyName": "string",
  "ownerName": "string",
  "legalForm": "Einzelunternehmen",
  "managingDirectors": "string",
  "address": {
    "street": "string",
    "zipCode": "string",
    "city": "string",
    "countryCode": "string"
  },
  "phone": "string",
  "email": "[email protected]",
  "website": "string",
  "taxNumber": "string",
  "vatId": "string",
  "smallBusiness": false,
  "commercialRegister": {
    "court": "string",
    "number": "string"
  },
  "bank": {
    "accountHolder": "string",
    "iban": "string",
    "bic": "string",
    "bankName": "string"
  },
  "invoiceFooter": "string",
  "paymentTermsDays": 0
}'

Response 200

{
  "companyName": "string",
  "ownerName": "string",
  "legalForm": "string",
  "managingDirectors": "string",
  "address": {
    "street": "string",
    "zipCode": "string",
    "city": "string",
    "countryCode": "string"
  },
  "phone": "string",
  "email": "string",
  "website": "string",
  "taxNumber": "string",
  "vatId": "string",
  "smallBusiness": false,
  "commercialRegister": {
    "court": "string",
    "number": "string"
  },
  "bank": {
    "accountHolder": "string",
    "iban": "string",
    "bic": "string",
    "bankName": "string"
  },
  "logo": {
    "contentType": "image/png",
    "size": 0,
    "updatedAt": "string"
  },
  "invoiceFooter": "string",
  "paymentTermsDays": 0,
  "complete": false,
  "missing": [
    "string"
  ]
}

Letterhead preview as PDF

GET/api/v1/company-profile/letterhead-preview

Generates a sample PDF (DIN 5008) with the sender, logo and footer from the master data.

Permission: profile:read

Response 200

File (application/pdf).

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

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

Download logo

GET/api/v1/company-profile/logo

Permission: profile:read

Response 200

File (image/*).

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

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

Upload or replace logo

PUT/api/v1/company-profile/logo

PNG or JPEG, max. 1 MB. Recommended: PNG with a transparent background, at least 600 px wide.

Permission: profile:write

Body (multipart/form-data)

filestring (binary)required
image/png, image/jpeg, max. 1024 KB

Response 200 · CompanyProfile

companyNamestringrequired
Company or name of the business owner (shown as sender)
ownerNamestringrequired
Owner (for sole proprietorships)
legalFormstringrequired
managingDirectorsstringrequired
Managing directors/board (required for corporations)
addressobjectrequired
- streetstringrequired
- zipCodestringrequired
- citystringrequired
- countryCodestringrequired
phonestringrequired
emailstringrequired
websitestringrequired
taxNumberstringrequired
Tax number from the tax office
vatIdstringrequired
VAT identification number
smallBusinessbooleanrequired
Small business under § 19 UStG (no VAT shown)
commercialRegisterobjectrequired
- courtstringrequired
- numberstringrequired
bankobjectrequired
- accountHolderstringrequired
- ibanstringrequired
- bicstringrequired
- bankNamestringrequired
logoCompanyLogo | nullrequired
- contentType"image/png" | "image/jpeg"required
- sizeintegerrequired
  -9007199254740991–9007199254740991
- updatedAtstringrequired
invoiceFooterstringrequired
Custom footer on invoices
paymentTermsDaysintegerrequired
Default payment term in days
-9007199254740991–9007199254740991
completebooleanrequired
Mandatory invoice details (§ 14 UStG) complete
missingArray<string>required
Missing details (plain text)

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

curl

curl -X PUT 'https://www.debt-flow.io/api/v1/company-profile/logo' \
  -H "Authorization: Bearer $DEBTFLOW_API_KEY" \
  -F 'file=@file'

Response 200

{
  "companyName": "string",
  "ownerName": "string",
  "legalForm": "string",
  "managingDirectors": "string",
  "address": {
    "street": "string",
    "zipCode": "string",
    "city": "string",
    "countryCode": "string"
  },
  "phone": "string",
  "email": "string",
  "website": "string",
  "taxNumber": "string",
  "vatId": "string",
  "smallBusiness": false,
  "commercialRegister": {
    "court": "string",
    "number": "string"
  },
  "bank": {
    "accountHolder": "string",
    "iban": "string",
    "bic": "string",
    "bankName": "string"
  },
  "logo": {
    "contentType": "image/png",
    "size": 0,
    "updatedAt": "string"
  },
  "invoiceFooter": "string",
  "paymentTermsDays": 0,
  "complete": false,
  "missing": [
    "string"
  ]
}

Remove logo

DELETE/api/v1/company-profile/logo

Permission: profile:write

Response 200 · CompanyProfile

companyNamestringrequired
Company or name of the business owner (shown as sender)
ownerNamestringrequired
Owner (for sole proprietorships)
legalFormstringrequired
managingDirectorsstringrequired
Managing directors/board (required for corporations)
addressobjectrequired
- streetstringrequired
- zipCodestringrequired
- citystringrequired
- countryCodestringrequired
phonestringrequired
emailstringrequired
websitestringrequired
taxNumberstringrequired
Tax number from the tax office
vatIdstringrequired
VAT identification number
smallBusinessbooleanrequired
Small business under § 19 UStG (no VAT shown)
commercialRegisterobjectrequired
- courtstringrequired
- numberstringrequired
bankobjectrequired
- accountHolderstringrequired
- ibanstringrequired
- bicstringrequired
- bankNamestringrequired
logoCompanyLogo | nullrequired
- contentType"image/png" | "image/jpeg"required
- sizeintegerrequired
  -9007199254740991–9007199254740991
- updatedAtstringrequired
invoiceFooterstringrequired
Custom footer on invoices
paymentTermsDaysintegerrequired
Default payment term in days
-9007199254740991–9007199254740991
completebooleanrequired
Mandatory invoice details (§ 14 UStG) complete
missingArray<string>required
Missing details (plain text)

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

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

Response 200

{
  "companyName": "string",
  "ownerName": "string",
  "legalForm": "string",
  "managingDirectors": "string",
  "address": {
    "street": "string",
    "zipCode": "string",
    "city": "string",
    "countryCode": "string"
  },
  "phone": "string",
  "email": "string",
  "website": "string",
  "taxNumber": "string",
  "vatId": "string",
  "smallBusiness": false,
  "commercialRegister": {
    "court": "string",
    "number": "string"
  },
  "bank": {
    "accountHolder": "string",
    "iban": "string",
    "bic": "string",
    "bankName": "string"
  },
  "logo": {
    "contentType": "image/png",
    "size": 0,
    "updatedAt": "string"
  },
  "invoiceFooter": "string",
  "paymentTermsDays": 0,
  "complete": false,
  "missing": [
    "string"
  ]
}

Retrieve signed-in user

GET/api/v1/me

Returns the account and the type of authentication, including the granted scopes. Useful for checking an API key.

Any valid API key or OAuth token.

Response 200 · Me

idstringrequired
User ID
emailstring | nullrequired
firstNamestringrequired
lastNamestringrequired
companystringrequired
approvedbooleanrequired
Account approved
authobjectrequired
- kind"session" | "api_key" | "oauth"required
  Sign-in method
- scopesArray<string>required
  Granted permissions
- apiKeyIdstring
- clientIdstring

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

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

Response 200

{
  "id": "string",
  "email": "string",
  "firstName": "string",
  "lastName": "string",
  "company": "string",
  "approved": false,
  "auth": {
    "kind": "session",
    "scopes": [
      "string"
    ],
    "apiKeyId": "string",
    "clientId": "string"
  }
}

List notifications

GET/api/v1/notifications

Permission: profile:read

Query parameters

unread"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<Notification>required
- idstringrequired
- object"notification"required
- typestringrequired
- titlestringrequired
- bodystringrequired
- linkstring | nullrequired
- readbooleanrequired
- createdAtstring (date-time)required
  Timestamp (ISO 8601)
hasMorebooleanrequired
nextCursorstring | nullrequired

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

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

Response 200

{
  "object": "list",
  "data": [
    {
      "id": "string",
      "object": "notification",
      "type": "string",
      "title": "string",
      "body": "string",
      "link": "string",
      "read": false,
      "createdAt": "2026-11-01T09:30:00.000Z"
    }
  ],
  "hasMore": false,
  "nextCursor": "string"
}

Mark notification as read

POST/api/v1/notifications/{id}/read

Permission: profile: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 · Notification

idstringrequired
object"notification"required
typestringrequired
titlestringrequired
bodystringrequired
linkstring | nullrequired
readbooleanrequired
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/notifications/ID/read' \
  -H "Authorization: Bearer $DEBTFLOW_API_KEY"

Response 200

{
  "id": "string",
  "object": "notification",
  "type": "string",
  "title": "string",
  "body": "string",
  "link": "string",
  "read": false,
  "createdAt": "2026-11-01T09:30:00.000Z"
}

Mark all notifications as read

POST/api/v1/notifications/read-all

Permission: profile: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

Response 200

updatedintegerrequired
-9007199254740991–9007199254740991

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

curl -X POST 'https://www.debt-flow.io/api/v1/notifications/read-all' \
  -H "Authorization: Bearer $DEBTFLOW_API_KEY"

Response 200

{
  "updated": 0
}

Alerts: overdue debts and upcoming instalments

GET/api/v1/notifications/summary

Permission: debts:read, payments:read

Response 200 · NotificationSummary

unreadCountintegerrequired
-9007199254740991–9007199254740991
overdueobjectrequired
- countintegerrequired
  -9007199254740991–9007199254740991
- principalCentsintegerrequired
  Amount in cents
  -100000000000–100000000000
upcomingInstallmentsArray<object>required
- installmentPlanIdstringrequired
- debtIdstringrequired
- descriptionstringrequired
- amountCentsintegerrequired
  Amount in cents
  -100000000000–100000000000
- dueDatestring (date)required
  Date (YYYY-MM-DD)

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

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

Response 200

{
  "unreadCount": 0,
  "overdue": {
    "count": 0,
    "principalCents": 0
  },
  "upcomingInstallments": [
    {
      "installmentPlanId": "string",
      "debtId": "string",
      "description": "string",
      "amountCents": 0,
      "dueDate": "2026-11-01"
    }
  ]
}

Retrieve settings

GET/api/v1/settings

Name, organisation type (collection agency/law firm) and dunning automation. Company and bank details: /company-profile.

Permission: profile:read

Response 200 · AccountSettings

firstNamestringrequired
lastNamestringrequired
phonestringrequired
organizationobjectrequired
- type"self" | "inkasso" | "kanzlei"required
- registerNumberstringrequired
- registerCourtstringrequired
automationobjectrequired
- autoDunningbooleanrequired
  Automatic dunning run
- dunningIntervalDaysintegerrequired
  7–60
- autoPostalDefaultbooleanrequired
  Also send dunning letters by post by default
- weeklyReportbooleanrequired
- installmentRemindersbooleanrequired
- paymentReceiptsbooleanrequired
  Payment confirmation to debtor
briefdienerConnectedbooleanrequired

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

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

Response 200

{
  "firstName": "string",
  "lastName": "string",
  "phone": "string",
  "organization": {
    "type": "self",
    "registerNumber": "string",
    "registerCourt": "string"
  },
  "automation": {
    "autoDunning": false,
    "dunningIntervalDays": 7,
    "autoPostalDefault": false,
    "weeklyReport": false,
    "installmentReminders": false,
    "paymentReceipts": false
  },
  "briefdienerConnected": false
}

Update settings

PATCH/api/v1/settings

E.g. {"automation":{"autoDunning":true,"dunningIntervalDays":14}} enables the automatic dunning run.

Permission: profile:write

Body (JSON) · AccountSettingsUpdate

firstNamestring
max. 80 characters
lastNamestring
max. 80 characters
phonestring
max. 40 characters
organizationobject
- type"self" | "inkasso" | "kanzlei"required
- registerNumberstring
  max. 80 characters
- registerCourtstring
  max. 120 characters
automationobject
- autoDunningboolean
  Automatic dunning run
- dunningIntervalDaysinteger
  7–60
- autoPostalDefaultboolean
  Also send dunning letters by post by default
- weeklyReportboolean
- installmentRemindersboolean
- paymentReceiptsboolean
  Payment confirmation to debtor

Response 200 · AccountSettings

firstNamestringrequired
lastNamestringrequired
phonestringrequired
organizationobjectrequired
- type"self" | "inkasso" | "kanzlei"required
- registerNumberstringrequired
- registerCourtstringrequired
automationobjectrequired
- autoDunningbooleanrequired
  Automatic dunning run
- dunningIntervalDaysintegerrequired
  7–60
- autoPostalDefaultbooleanrequired
  Also send dunning letters by post by default
- weeklyReportbooleanrequired
- installmentRemindersbooleanrequired
- paymentReceiptsbooleanrequired
  Payment confirmation to debtor
briefdienerConnectedbooleanrequired

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

curl -X PATCH 'https://www.debt-flow.io/api/v1/settings' \
  -H "Authorization: Bearer $DEBTFLOW_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
  "firstName": "string",
  "lastName": "string",
  "phone": "string",
  "organization": {
    "type": "self",
    "registerNumber": "string",
    "registerCourt": "string"
  },
  "automation": {
    "autoDunning": false,
    "dunningIntervalDays": 7,
    "autoPostalDefault": false,
    "weeklyReport": false,
    "installmentReminders": false,
    "paymentReceipts": false
  }
}'

Response 200

{
  "firstName": "string",
  "lastName": "string",
  "phone": "string",
  "organization": {
    "type": "self",
    "registerNumber": "string",
    "registerCourt": "string"
  },
  "automation": {
    "autoDunning": false,
    "dunningIntervalDays": 7,
    "autoPostalDefault": false,
    "weeklyReport": false,
    "installmentReminders": false,
    "paymentReceipts": false
  },
  "briefdienerConnected": false
}