Activities – API reference

Activity log

GET/api/v1/activities

History across all objects, newest first: automatic entries (source: history – phase changes, payments, letters, research …) and logged actions (source: activity). Filter by contact, debt, object type and date range.

Permission: activity:read

Query parameters

contactIdstring
max. 128 characters
debtIdstring
max. 128 characters
entityTypeenum
Values: contact, debt, invoice, offer, project, receipt, document, other
source"history" | "activity"
fromstring (date)
from date (inclusive)
tostring (date)
to date (inclusive)
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<Activity>required
- idstringrequired
- object"activity"required
- source"history" | "activity"required
  history = automatic history, activity = logged action
- entityTypeenumrequired
  Values: contact, debt, invoice, offer, project, receipt, document, other
- entityIdstringrequired
- contactIdstring | nullrequired
- debtIdstring | nullrequired
- actionstringrequired
- descriptionstringrequired
- performedBystring | nullrequired
- metadataobject | nullrequired
- 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/activities' \
  -H "Authorization: Bearer $DEBTFLOW_API_KEY"

Response 200

{
  "object": "list",
  "data": [
    {
      "id": "string",
      "object": "activity",
      "source": "history",
      "entityType": "contact",
      "entityId": "string",
      "contactId": "string",
      "debtId": "string",
      "action": "string",
      "description": "string",
      "performedBy": "string",
      "metadata": {},
      "createdAt": "2026-11-01T09:30:00.000Z"
    }
  ],
  "hasMore": false,
  "nextCursor": "string"
}

Log activity

POST/api/v1/activities

Custom entry in the activity log, e.g. from a CRM. Contacts and debts must exist.

Permission: activity: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) · ActivityCreate

entityTypeenumrequired
Values: contact, debt, invoice, offer, project, receipt, document, other
entityIdstringrequired
max. 128 characters
actionstringrequired
max. 100 characters
descriptionstring
max. 2000 characters · Default: ""
metadataobject

Response 201 · Activity

idstringrequired
object"activity"required
source"history" | "activity"required
history = automatic history, activity = logged action
entityTypeenumrequired
Values: contact, debt, invoice, offer, project, receipt, document, other
entityIdstringrequired
contactIdstring | nullrequired
debtIdstring | nullrequired
actionstringrequired
descriptionstringrequired
performedBystring | nullrequired
metadataobject | nullrequired
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/activities' \
  -H "Authorization: Bearer $DEBTFLOW_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
  "entityType": "contact",
  "entityId": "string",
  "action": "string",
  "description": "",
  "metadata": {}
}'

Response 201

{
  "id": "string",
  "object": "activity",
  "source": "history",
  "entityType": "contact",
  "entityId": "string",
  "contactId": "string",
  "debtId": "string",
  "action": "string",
  "description": "string",
  "performedBy": "string",
  "metadata": {},
  "createdAt": "2026-11-01T09:30:00.000Z"
}