Documents – API reference

List documents

GET/api/v1/documents

Query parameters

contactIdstring
max. 128 characters
debtIdstring
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<Document>required
- idstringrequired
- object"document"required
- contactIdstring | nullrequired
- debtIdstring | nullrequired
- fileNamestringrequired
- typestringrequired
- descriptionstringrequired
- contentTypestring | nullrequired
- sizeinteger | nullrequired
  -9007199254740991–9007199254740991
- downloadPathstringrequired
  GET path for downloading (with Authorization header)
- 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/documents' \
  -H "Authorization: Bearer $DEBTFLOW_API_KEY"

Response 200

{
  "object": "list",
  "data": [
    {
      "id": "string",
      "object": "document",
      "contactId": "string",
      "debtId": "string",
      "fileName": "string",
      "type": "string",
      "description": "string",
      "contentType": "string",
      "size": 0,
      "downloadPath": "string",
      "createdAt": "2026-11-01T09:30:00.000Z"
    }
  ],
  "hasMore": false,
  "nextCursor": "string"
}

Upload document

POST/api/v1/documents

multipart/form-data with field file (PDF, JPG, PNG, WebP, DOC, DOCX; max. 10 MB) and optionally contactId, debtId, type, description.

Permission: documents:write

Body (multipart/form-data)

filestring (binary)required
application/pdf, image/jpeg, image/png, image/webp, application/msword, application/vnd.openxmlformats-officedocument.wordprocessingml.document, max. 10240 KB
contactIdstring
max. 128 characters
debtIdstring
max. 128 characters
typeenum
Values: invoice, contract, payment_reminder, reminder, final_reminder, enforcement_order, court_order, bailiff_notice, correspondence, other · Default: "other"
descriptionstring
max. 500 characters

Response 201 · Document

idstringrequired
object"document"required
contactIdstring | nullrequired
debtIdstring | nullrequired
fileNamestringrequired
typestringrequired
descriptionstringrequired
contentTypestring | nullrequired
sizeinteger | nullrequired
-9007199254740991–9007199254740991
downloadPathstringrequired
GET path for downloading (with Authorization header)
createdAtstring (date-time)required
Timestamp (ISO 8601)

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

curl

curl -X POST 'https://www.debt-flow.io/api/v1/documents' \
  -H "Authorization: Bearer $DEBTFLOW_API_KEY" \
  -F 'file=@file' \
  -F 'contactId=…' \
  -F 'debtId=…' \
  -F 'type=…' \
  -F 'description=…'

Response 201

{
  "id": "string",
  "object": "document",
  "contactId": "string",
  "debtId": "string",
  "fileName": "string",
  "type": "string",
  "description": "string",
  "contentType": "string",
  "size": 0,
  "downloadPath": "string",
  "createdAt": "2026-11-01T09:30:00.000Z"
}

Retrieve document

GET/api/v1/documents/{id}

Metadata; the file itself is available at downloadPath.

Permission: documents:read

Path parameters

idstringrequired
Resource ID
max. 128 characters

Response 200 · Document

idstringrequired
object"document"required
contactIdstring | nullrequired
debtIdstring | nullrequired
fileNamestringrequired
typestringrequired
descriptionstringrequired
contentTypestring | nullrequired
sizeinteger | nullrequired
-9007199254740991–9007199254740991
downloadPathstringrequired
GET path for downloading (with Authorization header)
createdAtstring (date-time)required
Timestamp (ISO 8601)

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

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

Response 200

{
  "id": "string",
  "object": "document",
  "contactId": "string",
  "debtId": "string",
  "fileName": "string",
  "type": "string",
  "description": "string",
  "contentType": "string",
  "size": 0,
  "downloadPath": "string",
  "createdAt": "2026-11-01T09:30:00.000Z"
}

Rename or categorise document

PATCH/api/v1/documents/{id}

Permission: documents:write

Path parameters

idstringrequired
Resource ID
max. 128 characters

Body (JSON) · DocumentUpdate

typeenum
Values: invoice, contract, payment_reminder, reminder, final_reminder, enforcement_order, court_order, bailiff_notice, correspondence, other
descriptionstring
max. 500 characters
fileNamestring
max. 200 characters

Response 200 · Document

idstringrequired
object"document"required
contactIdstring | nullrequired
debtIdstring | nullrequired
fileNamestringrequired
typestringrequired
descriptionstringrequired
contentTypestring | nullrequired
sizeinteger | nullrequired
-9007199254740991–9007199254740991
downloadPathstringrequired
GET path for downloading (with Authorization header)
createdAtstring (date-time)required
Timestamp (ISO 8601)

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

curl -X PATCH 'https://www.debt-flow.io/api/v1/documents/ID' \
  -H "Authorization: Bearer $DEBTFLOW_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
  "type": "invoice",
  "description": "string",
  "fileName": "string"
}'

Response 200

{
  "id": "string",
  "object": "document",
  "contactId": "string",
  "debtId": "string",
  "fileName": "string",
  "type": "string",
  "description": "string",
  "contentType": "string",
  "size": 0,
  "downloadPath": "string",
  "createdAt": "2026-11-01T09:30:00.000Z"
}

Delete document

DELETE/api/v1/documents/{id}

Permission: documents: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/documents/ID' \
  -H "Authorization: Bearer $DEBTFLOW_API_KEY"

Download file

GET/api/v1/documents/{id}/file

Returns the file (including older files uploaded in the dashboard or in the app) from DebtFlow storage.

Permission: documents:read

Path parameters

idstringrequired
Resource ID
max. 128 characters

Response 200

File (application/octet-stream).

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

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