Comments API

Add internal notes, external clarifications, and AI-generated comments to specific answers in questionnaire responses.

Comments & Answers

Each comment must be linked to either a text answer (answer_id) or file answer (file_answer_id). Comments support audit trails with edit and deletion tracking.

Comment Object

The comment object represents a note or clarification attached to an answer in a questionnaire response.

Attributes

Field	Type	Description
`id`	uuid	Unique identifier
`text`	string	Comment text content (encrypted at rest)
`comment_type`	string	Type of comment: `internal`, `external`, `ai_reviewer_side`
`profile_name`	string	Full name of the user who created the comment
`profile_email`	string	Email address of the user who created the comment
`is_edited`	boolean	Whether the comment has been edited after creation
`edited_at`	datetime	Timestamp of last edit (null if never edited)
`created_at`	datetime	Creation timestamp
`updated_at`	datetime	Last update timestamp

Data Security

Comment text is encrypted at rest using EncryptedTextField for GDPR and KYC compliance. Edit and deletion history is maintained for audit trails.

List Comments

Retrieve all comments for a specific answer with optional filtering by comment type.

GET /api/v1/comments/

Query Parameters

Parameter	Type	Required	Description
`answer_id`	uuid	One required*	Text answer ID to filter comments
`file_answer_id`	uuid	One required*	File answer ID to filter comments
`comment_type`	string	No	Filter by type: `internal`, `external`, `ai_reviewer_side`

* Either answer_id or file_answer_id must be provided

Response (200 OK)

{
  "count": 2,
  "comments": [
    {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "text": "Verified against incorporation certificate",
      "comment_type": "internal",
      "profile_name": "John Reviewer",
      "profile_email": "[email protected]",
      "is_edited": false,
      "edited_at": null,
      "created_at": "2026-01-19T10:30:00Z",
      "updated_at": "2026-01-19T10:30:00Z"
    },
    {
      "id": "456e7890-e89b-12d3-a456-426614174001",
      "text": "Please provide more details about ownership",
      "comment_type": "external",
      "profile_name": "Sarah Smith",
      "profile_email": "[email protected]",
      "is_edited": true,
      "edited_at": "2026-01-19T14:00:00Z",
      "created_at": "2026-01-19T13:45:00Z",
      "updated_at": "2026-01-19T14:00:00Z"
    }
  ]
}

Create Comment

Add a new comment to a text or file answer.

POST /api/v1/comments/

Headers

Header	Type	Required	Description
`Authorization`	string	Yes	Bearer token: `Bearer YOUR_API_KEY`
`Idempotency-Key`	string	Recommended	Unique key to prevent duplicate comment creation. Retrying with the same key returns the original comment.

Request Body

Field	Type	Required	Description
`answer_id`	uuid	One required*	Text answer ID
`file_answer_id`	uuid	One required*	File answer ID
`text`	string	Yes	Comment text content
`comment_type`	string	No	Default: `internal`. Must be one of: `internal`, `external`, `ai_reviewer_side`

* Either answer_id or file_answer_id must be provided

Response (201 Created)

{
  "id": "789e0123-e89b-12d3-a456-426614174002",
  "text": "Requires additional verification of ownership",
  "comment_type": "internal",
  "created_at": "2026-01-22T16:45:00Z"
}

Update Comment

Modify an existing comment. Updates automatically track edit history with is_edited and edited_at fields.

PATCH /api/v1/comments/{comment_id}/

Path Parameters

Parameter	Type	Description
`comment_id`	uuid	ID of the comment to update

Headers

Header	Type	Required	Description
`Authorization`	string	Yes	Bearer token: `Bearer YOUR_API_KEY`
`Idempotency-Key`	string	Recommended	Unique key to ensure update is applied once. Retrying with the same key returns the updated comment without reapplying changes.

Request Body

Field	Type	Required	Description
`text`	string	Yes	Updated comment text

Response (200 OK)

{
  "id": "789e0123-e89b-12d3-a456-426614174002",
  "text": "Updated: Ownership verified, documents match",
  "is_edited": true,
  "edited_at": "2026-01-22T17:00:00Z",
  "updated_at": "2026-01-22T17:00:00Z"
}

Delete Comment

Delete a comment. The comment is permanently removed from the system.

DELETE /api/v1/comments/{comment_id}/

Path Parameters

Parameter	Type	Description
`comment_id`	uuid	ID of the comment to delete

Response (204 No Content)

No response body is returned on successful deletion.

Permanent Deletion

This action permanently removes the comment from the database. Audit logs are maintained for compliance tracking, but the comment text cannot be recovered.

Comment Types

Different comment types control visibility and use cases within the platform.

Type	Description	Visibility	Use Case
`internal`	Internal review notes	Your team only	Reviewer notes, internal discussion, flagged issues
`external`	Clarification requests	Entity and your team	Questions for the responding entity, requests for additional information
`ai_reviewer_side`	AI-generated reviewer notes	Your team only	AI-suggested concerns, auto-flagged discrepancies