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 uid of the account that wrote the comment: your service UID for comments created with an API key, the signed-in user's uid for comments written in the portal.
`author`	string	Human-readable author, resolved when the comment was written: the writer's name with their email (for example `Jane Doe (jane@acme.com)`; the company name stands in when no person name is on file), or `bronID` for comments written by bron ID staff. Absent on comments created before this field was introduced.
`createdAt`	number	Unix timestamp of creation (milliseconds).
`createdTime`	string	Human-readable creation time.
`source`	string	`admin` for comments written by bron ID staff, `audit` for system-generated audit entries such as a manual IDV risk change. Absent on customer comments.

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",
        "author": "Acme Pty Ltd (jane@acme.com)",
        "createdAt": 1737254548899,
        "createdTime": "30/01/2026 14:00:00"
      },
      {
        "commentId": "cmt-def456",
        "message": "Additional documentation requested from applicant.",
        "createdBy": "Hq0n1JQTY2TASItxYXSRyND35qA5",
        "author": "bronID",
        "createdAt": 1737254600000,
        "createdTime": "30/01/2026 14:05:00",
        "source": "admin"
      }
    ]
  },
  "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"]
      }
    ]
  }
}