Comments

Free-text notes left on a workflow by the sender or by any recipient. Comments are visible to everyone on the workflow, and adding one writes a COMMENT_ADDED row into the workflow history, so a comment is part of the audit trail rather than a side channel.

Rejection reasons are stored separately and read through their own endpoint — see Rejection details below.

Endpoint summary

Method	Path	Summary
POST	/workflow/v1/{workflowId}/comments	Add a comment
GET	/workflow/v1/{workflowId}/comments	List all comments on the workflow
GET	/workflow/v1/{workflowId}/reject-details	Why the workflow was declined, and by whom

Who can call these: the workflow owner, or a recipient on the workflow. Anyone else gets USER_NOT_HAVE_ACCESS. There is no separate permission — being a participant is the check.

Adding a comment

POST /workflow/v1/887/comments
Content-Type: application/json

{
  "body": "Clause 4 needs the updated address before I sign.",
  "fieldId": 5521
}

Field	Required	Notes
body	Yes	1–3000 characters after trimming. Empty or whitespace-only is rejected with INVALID_REQUEST_BODY
fieldId	No	Anchors the comment to a specific field, for a comment thread beside that field
documentId	No	Accepted but not stored on this route — see the note below

Response (CommentResponse):

{
  "id": 91,
  "workflowId": 887,
  "documentId": null,
  "fieldId": 5521,
  "authorUserId": 42,
  "body": "Clause 4 needs the updated address before I sign.",
  "createdAt": "2026-08-14T09:12:44.000+00:00"
}

documentId always comes back null here

The request field is read but never persisted by this endpoint, so the saved comment has no document attached and the response reports null. Use fieldId if you need to anchor a comment to a place in the document. Do not build on the request field — it has no effect today.

Adding a comment also records a COMMENT_ADDED activity naming the author. That recording is best-effort: if it fails, the comment is still saved.

Listing comments

GET /workflow/v1/887/comments

Returns every comment on the workflow, oldest first, as an array of the object above. There is no pagination and no filter — a workflow's comment list is expected to be small.

Rejection details

When a recipient declines (POST /workflow/v1/{workflowId}/decline, see Sending & Signing), the reason is stored against that recipient rather than as a comment. Read it back with:

GET /workflow/v1/887/reject-details

[
  {
    "recipientId": 3310,
    "name": "Ayşe Yılmaz",
    "email": "ayse@example.com",
    "role": "SIGNER",
    "reason": "Wrong counterparty on page 2.",
    "rejectedAt": "2026-08-14T10:02:11.000+00:00"
  }
]

An array, because a Power Survey parent collects the declines of all of its child workflows. For an ordinary workflow it holds at most one entry.