Creditor AI – API reference

Creditor AI recommendations for a contact

GET/api/v1/contacts/{id}/recommendations

All saved recommendations for debts of this contact, newest first. Does not use AI quota.

Permission: ai:read

Path parameters

idstringrequired
Resource ID
max. 128 characters

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<Recommendation>required
- idstringrequired
- object"recommendation"required
- contactIdstringrequired
- debtIdstringrequired
- textstringrequired
  Recommendation (Markdown)
- modelstring | nullrequired
- createdAtstring (date-time)required
  Timestamp (ISO 8601)
hasMorebooleanrequired
nextCursorstring | nullrequired

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

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

Response 200

{
  "object": "list",
  "data": [
    {
      "id": "string",
      "object": "recommendation",
      "contactId": "string",
      "debtId": "string",
      "text": "string",
      "model": "string",
      "createdAt": "2026-11-01T09:30:00.000Z"
    }
  ],
  "hasMore": false,
  "nextCursor": "string"
}

Creditor AI recommendations for a debt

GET/api/v1/debts/{id}/recommendations

Saved recommendations, newest first. Does not use AI quota.

Permission: ai:read

Path parameters

idstringrequired
Resource ID
max. 128 characters

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<Recommendation>required
- idstringrequired
- object"recommendation"required
- contactIdstringrequired
- debtIdstringrequired
- textstringrequired
  Recommendation (Markdown)
- modelstring | nullrequired
- createdAtstring (date-time)required
  Timestamp (ISO 8601)
hasMorebooleanrequired
nextCursorstring | nullrequired

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

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

Response 200

{
  "object": "list",
  "data": [
    {
      "id": "string",
      "object": "recommendation",
      "contactId": "string",
      "debtId": "string",
      "text": "string",
      "model": "string",
      "createdAt": "2026-11-01T09:30:00.000Z"
    }
  ],
  "hasMore": false,
  "nextCursor": "string"
}

Generate creditor AI recommendation

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

Evaluates the debt, phase, costs, payments, instalment plans, communications and history and generates a recommended course of action (Markdown). No body required – the context is loaded from the stored data. Limited AI quota per account (shared with the dashboard) and globally per day: 429 ai_rate_limited or ai_quota_exhausted with retryAfter. 503 ai_unavailable if the AI is not set up. Not legal advice. Event recommendation.created. Blocked in the demo account.

Permission: ai: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 201 · Recommendation

idstringrequired
object"recommendation"required
contactIdstringrequired
debtIdstringrequired
textstringrequired
Recommendation (Markdown)
modelstring | nullrequired
createdAtstring (date-time)required
Timestamp (ISO 8601)

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

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

Response 201

{
  "id": "string",
  "object": "recommendation",
  "contactId": "string",
  "debtId": "string",
  "text": "string",
  "model": "string",
  "createdAt": "2026-11-01T09:30:00.000Z"
}