Creditor application comments

Retailer integrations can read and post comments using:

/v1/applications/{applicationId}/creditors/{creditorId}/comments

Authenticate with the retailer integration's token. When selecting a retailer, use the same X-CreditApp-Retailer-ID header for the users list and comment requests.

Read the conversation

Send a GET to the comments endpoint. The response is an array ordered oldest first, containing creditor replies, retailer comments, and system messages shown as only visible to you in the retailer portal. An empty conversation returns []. Reading through this API does not mark messages as read.

Each item contains commentId, applicationId, creditorId, sender, comment, createdAt, userId, userName, type, and status. sender is CREDITOR, RETAILER, or SYSTEM. userId identifies a retailer or retailer group author; userName contains a creditor-provided name when available. Resolve retailer names through GET /v1/users?skip=0&limit=100 (paginate for additional users).

System cards may carry structured content in comment. Funding remittance cards have type FUNDING_REMITTANCE and empty comment text; internal storage paths are not returned. Internal creditor notes are not part of this conversation.

Reading requires the VIEW_APPLICATION permission and access to the application's retailer.

Add a comment

1. Fetch GET /v1/users?skip=0&limit=100 and select the user making the comment.
2. POST to the comments endpoint with that user's userId:

{
  "userId": "b82b65d0-6f7e-4a94-9f21-d0bfb9ed0bac",
  "comment": "The requested documents have been uploaded."
}

A 204 response means the comment is queued for delivery to the creditor. The integration is recorded as the actor; the selected user is recorded as the author. The author must be an active user of the application's retailer, or a user in its retailer group with access to that retailer. Posting requires ENQUEUE_RETAILER_CHAT. Blank comments, ineligible authors, archived applications, and applications not submitted to that creditor are rejected.

Receive notifications

Set the integration callback URL creditorApplicationCommentAdded to your HTTPS webhook endpoint. Notifications fire for new creditor, retailer, and system comments, including comments posted by your own integration.

{
  "retailerId": "5a152b11-2b27-4a1b-925b-5e26513074ef",
  "applicationId": "1fb753c0-f8df-4b2b-a095-2fe2162771bb",
  "creditorId": "6d6b524d-a608-4a51-bf02-b1ee9f3b0e54",
  "commentId": "b9889af6-e3a9-489f-bcb1-c44d36ebfb6d",
  "sender": "CREDITOR",
  "createdAt": "2026-09-15T12:00:00.000Z"
}

Verify the signature using Webhook Authentication. Deduplicate notifications by commentId, then fetch the conversation. Updates are eventually consistent: retry GET if the notified comment has not appeared yet. Historical replays do not send notifications.