Comments

Comments allow you to attach notes and messages to a verification. Use these endpoints to create, list, and delete comments associated with a specific verification trace.

Overview

Comments are useful for:

Internal notes — record observations or decisions made during the verification process
Audit trail — maintain a history of communications and actions taken
Collaboration — share context between team members reviewing a verification

All comment endpoints require a valid trace identifier, which uniquely identifies the parent verification:

POST /v5/verifications/:trace/comments - Create a new comment
GET /v5/verifications/:trace/comments - List all comments for a verification
DELETE /v5/verifications/:trace/comments/:commentId - Delete a comment

POST/v5/verifications/:trace/comments

Create a comment

Create a new comment on a verification.

Path parameters

Name
trace
Type
string
Description
The unique identifier for the verification.

Required attributes

Name
message
Type
string (1–2000 characters)
Description
The comment message. Whitespace is trimmed before validation.

Response fields

Field	Type	Description
`commentId`	string	Unique identifier for the created comment.

Error responses

Status Code	Error Type	Description
422	`validation_error`	Invalid request parameters (e.g. message too short or too long).

Request

POST

/v5/verifications/:trace/comments

curl -X POST "https://api.bronid.com/v5/verifications/{trace}/comments" \
  -H "Authorization: Basic {credentials}" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "Verification documents received and under review."
  }'

Response

{
  "timestamp": "2026-01-30T04:00:00.000Z",
  "serviceUid": "5qA5Hq0n1JQTY2TASItxYXSRyND3",
  "trace": "abc123-verification-trace",
  "path": "/v5/verifications/:trace/comments",
  "pathParams": {
    "trace": "abc123-verification-trace"
  },
  "statusCode": 200,
  "message": "Comment created successfully.",
  "help": null,
  "status": "success",
  "data": {
    "commentId": "cmt-abc123"
  },
  "error": null
}

GET/v5/verifications/:trace/comments

List comments

Retrieve all comments associated with a verification.

Path parameters

Name
trace
Type
string
Description
The unique identifier for the verification.

Response fields

The response contains a data.comments array. Each comment includes:

Field	Type	Description
`commentId`	string	Unique comment identifier.
`message`	string	The comment message.
`createdBy`	string	The service UID of the user who created the comment.
`createdAt`	number	Unix timestamp of creation (milliseconds).
`createdTime`	string	Human-readable creation time.

Request

GET

/v5/verifications/:trace/comments

curl -X GET "https://api.bronid.com/v5/verifications/{trace}/comments" \
  -H "Authorization: Basic {credentials}"

Response

{
  "timestamp": "2026-01-30T04:00:00.000Z",
  "serviceUid": "5qA5Hq0n1JQTY2TASItxYXSRyND3",
  "trace": "abc123-verification-trace",
  "path": "/v5/verifications/:trace/comments",
  "pathParams": {
    "trace": "abc123-verification-trace"
  },
  "statusCode": 200,
  "message": "Comments listed successfully.",
  "help": null,
  "status": "success",
  "data": {
    "comments": [
      {
        "commentId": "cmt-abc123",
        "message": "Verification documents received and under review.",
        "createdBy": "5qA5Hq0n1JQTY2TASItxYXSRyND3",
        "createdAt": 1737254548899,
        "createdTime": "30/01/2026 14:00:00"
      },
      {
        "commentId": "cmt-def456",
        "message": "Additional documentation requested from applicant.",
        "createdBy": "5qA5Hq0n1JQTY2TASItxYXSRyND3",
        "createdAt": 1737254600000,
        "createdTime": "30/01/2026 14:05:00"
      }
    ]
  },
  "error": null
}

DELETE/v5/verifications/:trace/comments/:commentId

Delete a comment

Delete a specific comment from a verification. You can only delete comments that were created by your service.

Path parameters

Name
trace
Type
string
Description
The unique identifier for the verification.
Name
commentId
Type
string
Description
The unique identifier for the comment to delete.

Error responses

Status Code	Error Type	Description
403	`forbidden`	Not authorized to delete this comment (created by a different service).
404	`not_found`	Comment not found.

Request

DELETE

/v5/verifications/:trace/comments/:commentId

curl -X DELETE "https://api.bronid.com/v5/verifications/{trace}/comments/{commentId}" \
  -H "Authorization: Basic {credentials}"

Response

{
  "timestamp": "2026-01-30T04:05:00.000Z",
  "serviceUid": "5qA5Hq0n1JQTY2TASItxYXSRyND3",
  "trace": "abc123-verification-trace",
  "path": "/v5/verifications/:trace/comments/:commentId",
  "pathParams": {
    "trace": "abc123-verification-trace",
    "commentId": "cmt-abc123"
  },
  "statusCode": 200,
  "message": "Comment deleted successfully.",
  "help": null,
  "status": "success",
  "data": null,
  "error": null
}

Error response (403)

{
  "timestamp": "2026-01-30T04:05:00.000Z",
  "serviceUid": "5qA5Hq0n1JQTY2TASItxYXSRyND3",
  "trace": "abc123-verification-trace",
  "path": "/v5/verifications/:trace/comments/:commentId",
  "pathParams": {
    "trace": "abc123-verification-trace",
    "commentId": "cmt-abc123"
  },
  "statusCode": 403,
  "message": "Forbidden",
  "help": null,
  "status": "error",
  "data": null,
  "error": {
    "type": "forbidden",
    "details": [
      {
        "message": "Not authorized to delete comment: cmt-abc123",
        "code": "forbidden",
        "path": ["commentId"]
      }
    ]
  }
}

Error response (404)

{
  "timestamp": "2026-01-30T04:05:00.000Z",
  "serviceUid": "5qA5Hq0n1JQTY2TASItxYXSRyND3",
  "trace": "abc123-verification-trace",
  "path": "/v5/verifications/:trace/comments/:commentId",
  "pathParams": {
    "trace": "abc123-verification-trace",
    "commentId": "cmt-invalid"
  },
  "statusCode": 404,
  "message": "Not found",
  "help": null,
  "status": "error",
  "data": null,
  "error": {
    "type": "not_found",
    "details": [
      {
        "message": "Comment not found: cmt-invalid",
        "code": "not_found",
        "path": ["commentId"]
      }
    ]
  }
}