Clients – API reference

List clients

GET/api/v1/clients

For collection agencies and law firms: principals on whose behalf debts are collected. Alphabetical.

Permission: clients:read

Query parameters

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<Client>required
- idstringrequired
- object"client"required
- namestringrequired
- legalFormstringrequired
- representedBystringrequired
- clientNumberstringrequired
- streetstringrequired
- zipCodestringrequired
- citystringrequired
- countrystringrequired
- emailstringrequired
- phonestringrequired
- ibanstringrequired
- bicstringrequired
- bankNamestringrequired
- vatDeductiblebooleanrequired
  Entitled to deduct input VAT
- notesstringrequired
- debtCountintegerrequired
  -9007199254740991–9007199254740991
- openDebtCountintegerrequired
  -9007199254740991–9007199254740991
- 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/clients' \
  -H "Authorization: Bearer $DEBTFLOW_API_KEY"

Response 200

{
  "object": "list",
  "data": [
    {
      "id": "string",
      "object": "client",
      "name": "string",
      "legalForm": "string",
      "representedBy": "string",
      "clientNumber": "string",
      "street": "string",
      "zipCode": "string",
      "city": "string",
      "country": "string",
      "email": "string",
      "phone": "string",
      "iban": "string",
      "bic": "string",
      "bankName": "string",
      "vatDeductible": false,
      "notes": "string",
      "debtCount": 0,
      "openDebtCount": 0,
      "createdAt": "2026-11-01T09:30:00.000Z",
      "updatedAt": "2026-11-01T09:30:00.000Z"
    }
  ],
  "hasMore": false,
  "nextCursor": "string"
}

Create client

POST/api/v1/clients

Permission: clients: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) · ClientCreate

namestringrequired
max. 200 characters
legalFormstring
max. 60 characters
representedBystring
max. 200 characters
clientNumberstring
max. 60 characters
streetstring
max. 160 characters
zipCodestring
max. 10 characters
citystring
max. 80 characters
countrystring
max. 60 characters
emailstring (email) | ""
phonestring
max. 40 characters
ibanstring
max. 42 characters
bicstring
max. 11 characters
bankNamestring
max. 80 characters
vatDeductibleboolean
notesstring
max. 5000 characters

Response 201 · Client

idstringrequired
object"client"required
namestringrequired
legalFormstringrequired
representedBystringrequired
clientNumberstringrequired
streetstringrequired
zipCodestringrequired
citystringrequired
countrystringrequired
emailstringrequired
phonestringrequired
ibanstringrequired
bicstringrequired
bankNamestringrequired
vatDeductiblebooleanrequired
Entitled to deduct input VAT
notesstringrequired
debtCountintegerrequired
-9007199254740991–9007199254740991
openDebtCountintegerrequired
-9007199254740991–9007199254740991
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/clients' \
  -H "Authorization: Bearer $DEBTFLOW_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
  "name": "string",
  "legalForm": "string",
  "representedBy": "string",
  "clientNumber": "string",
  "street": "string",
  "zipCode": "string",
  "city": "string",
  "country": "string",
  "email": "[email protected]",
  "phone": "string",
  "iban": "string",
  "bic": "string",
  "bankName": "string",
  "vatDeductible": false,
  "notes": "string"
}'

Response 201

{
  "id": "string",
  "object": "client",
  "name": "string",
  "legalForm": "string",
  "representedBy": "string",
  "clientNumber": "string",
  "street": "string",
  "zipCode": "string",
  "city": "string",
  "country": "string",
  "email": "string",
  "phone": "string",
  "iban": "string",
  "bic": "string",
  "bankName": "string",
  "vatDeductible": false,
  "notes": "string",
  "debtCount": 0,
  "openDebtCount": 0,
  "createdAt": "2026-11-01T09:30:00.000Z",
  "updatedAt": "2026-11-01T09:30:00.000Z"
}

Retrieve client

GET/api/v1/clients/{id}

The client's debts: GET /debts?clientId=….

Permission: clients:read

Path parameters

idstringrequired
Resource ID
max. 128 characters

Response 200 · Client

idstringrequired
object"client"required
namestringrequired
legalFormstringrequired
representedBystringrequired
clientNumberstringrequired
streetstringrequired
zipCodestringrequired
citystringrequired
countrystringrequired
emailstringrequired
phonestringrequired
ibanstringrequired
bicstringrequired
bankNamestringrequired
vatDeductiblebooleanrequired
Entitled to deduct input VAT
notesstringrequired
debtCountintegerrequired
-9007199254740991–9007199254740991
openDebtCountintegerrequired
-9007199254740991–9007199254740991
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/clients/ID' \
  -H "Authorization: Bearer $DEBTFLOW_API_KEY"

Response 200

{
  "id": "string",
  "object": "client",
  "name": "string",
  "legalForm": "string",
  "representedBy": "string",
  "clientNumber": "string",
  "street": "string",
  "zipCode": "string",
  "city": "string",
  "country": "string",
  "email": "string",
  "phone": "string",
  "iban": "string",
  "bic": "string",
  "bankName": "string",
  "vatDeductible": false,
  "notes": "string",
  "debtCount": 0,
  "openDebtCount": 0,
  "createdAt": "2026-11-01T09:30:00.000Z",
  "updatedAt": "2026-11-01T09:30:00.000Z"
}

Update client

PATCH/api/v1/clients/{id}

Permission: clients:write

Path parameters

idstringrequired
Resource ID
max. 128 characters

Body (JSON) · ClientUpdate

namestring
max. 200 characters
legalFormstring
max. 60 characters
representedBystring
max. 200 characters
clientNumberstring
max. 60 characters
streetstring
max. 160 characters
zipCodestring
max. 10 characters
citystring
max. 80 characters
countrystring
max. 60 characters
emailstring (email) | ""
phonestring
max. 40 characters
ibanstring
max. 42 characters
bicstring
max. 11 characters
bankNamestring
max. 80 characters
vatDeductibleboolean
notesstring
max. 5000 characters

Response 200 · Client

idstringrequired
object"client"required
namestringrequired
legalFormstringrequired
representedBystringrequired
clientNumberstringrequired
streetstringrequired
zipCodestringrequired
citystringrequired
countrystringrequired
emailstringrequired
phonestringrequired
ibanstringrequired
bicstringrequired
bankNamestringrequired
vatDeductiblebooleanrequired
Entitled to deduct input VAT
notesstringrequired
debtCountintegerrequired
-9007199254740991–9007199254740991
openDebtCountintegerrequired
-9007199254740991–9007199254740991
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/clients/ID' \
  -H "Authorization: Bearer $DEBTFLOW_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
  "name": "string",
  "legalForm": "string",
  "representedBy": "string",
  "clientNumber": "string",
  "street": "string",
  "zipCode": "string",
  "city": "string",
  "country": "string",
  "email": "[email protected]",
  "phone": "string",
  "iban": "string",
  "bic": "string",
  "bankName": "string",
  "vatDeductible": false,
  "notes": "string"
}'

Response 200

{
  "id": "string",
  "object": "client",
  "name": "string",
  "legalForm": "string",
  "representedBy": "string",
  "clientNumber": "string",
  "street": "string",
  "zipCode": "string",
  "city": "string",
  "country": "string",
  "email": "string",
  "phone": "string",
  "iban": "string",
  "bic": "string",
  "bankName": "string",
  "vatDeductible": false,
  "notes": "string",
  "debtCount": 0,
  "openDebtCount": 0,
  "createdAt": "2026-11-01T09:30:00.000Z",
  "updatedAt": "2026-11-01T09:30:00.000Z"
}

Delete client

DELETE/api/v1/clients/{id}

Only possible if no debts are assigned (otherwise 409 in_use).

Permission: clients:write

Path parameters

idstringrequired
Resource ID
max. 128 characters

Response 204

Success, no content

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

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