API for developers

Not yet in the API

Some research features of the debt view are currently only available in the dashboard: population register enquiries (Melderegisteranfragen), address research, financial situation and recommendations from the creditor AI, and the activity log. They will follow in a later version; new endpoints are listed in the changelog.

Base URL

https://www.debt-flow.io/api/v1

Every response carries the header DebtFlow-Version: 2026-11-01. It states the date of the last breaking change; additions (new fields, new endpoints) do not change it. Your code should therefore ignore unknown fields.

First request in three steps

In the dashboard, go to Settings → Developers, create an API key and select the required permissions. The key starts with df_live_ and is shown only once.
Store the key in the environment variable DEBTFLOW_API_KEY – never in source code or in the browser.
Call GET /me. The response shows your account and the permissions of the key.

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

Response 200

{
  "id": "Xk2pQ9…",
  "email": "[email protected]",
  "firstName": "Erika",
  "lastName": "Muster",
  "company": "Muster GmbH",
  "approved": true,
  "auth": {
    "kind": "api_key",
    "scopes": [
      "contacts:read",
      "invoices:write"
    ],
    "apiKeyId": "ak_…"
  }
}

Conventions

Topic	Format	Example
Fields	camelCase	`issueDate`
Amounts	whole cents (integer), currency EUR	`12550`
Calendar dates	YYYY-MM-DD	`2026-11-30`
Timestamps	ISO 8601 with time zone	`2026-11-04T09:30:00.000Z`
Countries	ISO 3166-1 alpha-2	`DE`
Enumerations	snake_case	`partially_paid`
IDs	opaque strings, some with a prefix	`evt_…`
Lists	cursor pagination	limit, cursor

Amounts in cents avoid rounding errors: €125.50 is sent as 12550. DebtFlow calculates tax amounts itself from the line items, tax rate and tax treatment.

OpenAPI description

The complete description in OpenAPI 3.1 format is available at /api/v1/openapi.json. You can import it into Postman, Insomnia or code generators, and it also contains all webhook events. The API reference on this website is generated from the same file. Texts in the OpenAPI file are in German; the reference on this website shows them in English.

Topics

Authentication – API keys for your own scripts and OAuth 2.0 with PKCE for apps that connect other DebtFlow accounts.
Permissions – All scopes of API v1: read and write access per area – what an API key or an app is allowed to do.
Errors – Uniform error format, HTTP status codes and all error codes of the DebtFlow API.
Pagination – Lists with cursor pagination: limit, cursor, hasMore and nextCursor, with examples.
Idempotency – Safely retry POST requests with the Idempotency-Key header.
Rate limits – How many requests per minute are allowed, the X-RateLimit-* headers and how to handle 429.
Webhooks – Receive events in real time, verify the DebtFlow-Signature header, retries and the event catalogue.
API reference – All endpoints of the DebtFlow API v1 with parameters, responses and examples – generated from the OpenAPI description.
Changelog – Versions and changes of the DebtFlow API.
Zapier, Make and n8n – Connect DebtFlow to Zapier, Make and n8n without writing code.

DebtFlow API

Base URL

First request in three steps

Conventions

OpenAPI description

Topics