Add Comment Annotations

curl --request POST \
  --url https://api.velt.dev/v2/commentannotations/add \
  --header 'Content-Type: application/json' \
  --header 'x-velt-api-key: <x-velt-api-key>' \
  --header 'x-velt-auth-token: <x-velt-auth-token>' \
  --data '{
  "data": {
    "organizationId": "<string>",
    "documentId": "<string>",
    "commentAnnotations": [
      {
        "annotationId": "<string>",
        "location": {
          "id": "<string>",
          "locationName": "<string>"
        },
        "targetElement": {
          "elementId": "<string>",
          "targetText": "<string>",
          "occurrence": 123,
          "selectAllContent": true
        },
        "commentData": [
          {
            "commentId": 123,
            "commentText": "<string>",
            "commentHtml": "<string>",
            "context": {},
            "isCommentResolverUsed": true,
            "isCommentTextAvailable": true,
            "triggerNotification": true,
            "from": {},
            "createdAt": 123,
            "lastUpdated": 123,
            "taggedUserContacts": [
              {
                "userId": "<string>",
                "contact": {
                  "userId": "<string>",
                  "name": "<string>",
                  "email": "<string>"
                }
              }
            ]
          }
        ],
        "status": {
          "id": "<string>",
          "name": "<string>",
          "type": "<string>",
          "color": "<string>",
          "lightColor": "<string>",
          "svg": "<string>",
          "iconUrl": "<string>"
        },
        "assignedTo": {},
        "context": {},
        "createdAt": 123,
        "lastUpdated": 123,
        "priority": {
          "id": "<string>",
          "color": "<string>",
          "name": "<string>",
          "lightColor": "<string>"
        }
      }
    ]
  }
}'

{
   "result": {
       "status": "success",
       "message": "Comment Annotation(s) added successfully.",
       "data": {
           "-O0mpUziLcBwzREvZKs6": {
               "success": true,
               "annotationId": "-O0mpUziLcBwzREvZKs6",
               "commentIds": [
                   126535
               ],
               "message": "Added Successfully"
           }
       }
   }
}

POST

commentannotations

add

Add Comment Annotations

curl --request POST \
  --url https://api.velt.dev/v2/commentannotations/add \
  --header 'Content-Type: application/json' \
  --header 'x-velt-api-key: <x-velt-api-key>' \
  --header 'x-velt-auth-token: <x-velt-auth-token>' \
  --data '{
  "data": {
    "organizationId": "<string>",
    "documentId": "<string>",
    "commentAnnotations": [
      {
        "annotationId": "<string>",
        "location": {
          "id": "<string>",
          "locationName": "<string>"
        },
        "targetElement": {
          "elementId": "<string>",
          "targetText": "<string>",
          "occurrence": 123,
          "selectAllContent": true
        },
        "commentData": [
          {
            "commentId": 123,
            "commentText": "<string>",
            "commentHtml": "<string>",
            "context": {},
            "isCommentResolverUsed": true,
            "isCommentTextAvailable": true,
            "triggerNotification": true,
            "from": {},
            "createdAt": 123,
            "lastUpdated": 123,
            "taggedUserContacts": [
              {
                "userId": "<string>",
                "contact": {
                  "userId": "<string>",
                  "name": "<string>",
                  "email": "<string>"
                }
              }
            ]
          }
        ],
        "status": {
          "id": "<string>",
          "name": "<string>",
          "type": "<string>",
          "color": "<string>",
          "lightColor": "<string>",
          "svg": "<string>",
          "iconUrl": "<string>"
        },
        "assignedTo": {},
        "context": {},
        "createdAt": 123,
        "lastUpdated": 123,
        "priority": {
          "id": "<string>",
          "color": "<string>",
          "name": "<string>",
          "lightColor": "<string>"
        }
      }
    ]
  }
}'

{
   "result": {
       "status": "success",
       "message": "Comment Annotation(s) added successfully.",
       "data": {
           "-O0mpUziLcBwzREvZKs6": {
               "success": true,
               "annotationId": "-O0mpUziLcBwzREvZKs6",
               "commentIds": [
                   126535
               ],
               "message": "Added Successfully"
           }
       }
   }
}

Use this API to add comment annotations to a document within an organization.

You can add comments on an elemement, text or page.
You can provide HTML or text content.
Additional filters can be applied using location IDs.

Endpoint

POST https://api.velt.dev/v2/commentannotations/add

Headers

x-velt-api-key

string

required

Your API key.

x-velt-auth-token

string

required

Your Auth Token.

Body

Params

data

object

required

Show properties

organizationId

string

required

Organization ID

documentId

string

required

Document ID

commentAnnotations

object[]

required

Show properties

annotationId

string

Custom Annotation ID. If not provided, Velt will generate a unique ID for the annotation.

location

object

Show properties

string

required

Location ID

locationName

string

Location Name

targetElement

object

Target Element

Show properties

elementId

string

Element DOM Id

targetText

string

Target Text. Provide this if you want to add comment annotation on the provided text content.

occurrence

number

Occurrence. Provide this if you want to add comment annotation on a text content.

selectAllContent

boolean

Select All Content. Provide this if you want to select and add comment annotation on the entire text content of the target elementId.

commentData

object[]

required

Array of Comment Data

Show properties

commentId

number

Custom Comment ID. If not provided, Velt will generate a unique ID for the comment.

commentText

string

Comment content in plain text string. To tag users, wrap their userId in double curly braces like {{userId}}. The frontend will replace this with the user’s name.

commentHtml

string

Comment content in HTML string. To tag users, wrap their userId in double curly braces like {{userId}}. The frontend will replace this with the user’s name.

context

object

Custom key/value metadata object. This is used to store any additional information about the comment.

isCommentResolverUsed

boolean

Use this for self-hosting comments data. Set this as true if you are comments resolver data provider in the SDK.

isCommentTextAvailable

boolean

Use this for self-hosting comments data. Set this as true if this comment will have text content. Sometimes, comments might only have attachments and in that case, set this as false.

triggerNotification

boolean

When enabled, adding comments via the REST API will trigger in-app notifications, email notifications to relevant users and also trigger webhooks matching the SDK’s native notification behavior. Default: false.

from

User

required

User object from whom the comment is added

createdAt

number

Created At timestamp (in milliseconds since epoch).

lastUpdated

number

Last Updated timestamp (in milliseconds since epoch).

taggedUserContacts

object[]

Array of tagged user contacts. Use this field to provide information about users tagged in the comment. Each userId wrapped in {{userId}} in commentText or commentHtml should have a corresponding entry here so the frontend can replace it with the user’s name.

Show properties

userId

string

required

User ID of the tagged user. This should match the userId used in {{userId}} syntax within commentText or commentHtml.

contact

object

required

Contact information for the tagged user

Show properties

userId

string

required

User ID of the tagged user

name

string

Name of the tagged user

string

Email of the tagged user

status

Status

Show properties

string

required

Status ID

name

string

required

Status Name

type

string

required

Type. Must be one of: default, ongoing, or terminal.

color

string

required

Text and comment pin color

lightColor

string

required

Background color on the status indicator

svg

string

Raw SVG of the icon. Either svg or iconUrl is required.

iconUrl

string

Icon URL. Either svg or iconUrl is required.

assignedTo

User

User object to whom the comment is assigned

context

object

Custom key/value metadata object

createdAt

number

Created At timestamp (in milliseconds since epoch).

lastUpdated

number

Last Updated timestamp (in milliseconds since epoch).

priority

object

Priority

Show properties

string

required

Priority ID

color

string

required

Priority Color

name

string

required

Priority Name

lightColor

string

required

Priority Light Color

Example Requests

Add comment annotation by organizationId, documentId and location

{
  "data": {
    "organizationId": "yourOrganizationId",
    "documentId": "yourDocumentId",
    "commentAnnotations": [
      {
        "location": {
          "id": "yourLocationId",
          "locationName": "yourLocationName"
        },
        "targetElement": {
          "elementId": "yourElementId",
          "targetText": "Your Target Text",
          "occurrence": 1,
          "selectAllContent": false
        },
        "commentData": [
          {
            "commentText": "Sample Comment",
            "commentHtml": "<div>Sample Comment</div>",
            "from": {
              "userId": "yourUserId",
              "name": "yourUserName",
              "email": "yourUserEmail",
            }
          }
        ]
      }
    ]
  }
}

Add comment annotation with user tagging

{
  "data": {
    "organizationId": "acme-corp",
    "documentId": "design-mockup-v2",
    "commentAnnotations": [
      {
        "commentData": [
          {
            "triggerNotification": true,
            "commentText": "Hey {{user_sarah_chen}}, can you review this color scheme? I think we should use a darker shade for better contrast.",
            "commentHtml": "<p>Hey {{user_sarah_chen}}, can you review this color scheme? I think we should use a darker shade for better contrast.</p>",
            "from": {
              "userId": "user_john_smith",
              "name": "John Smith",
              "email": "john.smith@acme-corp.com"
            },
            "taggedUserContacts": [
              {
                "userId": "user_sarah_chen",
                "contact": {
                  "userId": "user_sarah_chen",
                  "name": "Sarah Chen",
                  "email": "sarah.chen@acme-corp.com"
                }
              }
            ]
          }
        ]
      }
    ]
  }
}

In this example, {{user_sarah_chen}} in the commentText will be replaced with “Sarah Chen” on the frontend, displaying as “Hey Sarah Chen, can you review this color scheme? I think we should use a darker shade for better contrast.”

Response

Success Response

{
   "result": {
       "status": "success",
       "message": "Comment Annotation(s) added successfully.",
       "data": {
           "-O0mpUziLcBwzREvZKs6": {
               "success": true,
               "annotationId": "-O0mpUziLcBwzREvZKs6",
               "commentIds": [
                   126535
               ],
               "message": "Added Successfully"
           }
       }
   }
}

Failure Response

{
  "error": {
    "message": "ERROR_MESSAGE",
    "status": "INVALID_ARGUMENT"
  }
}

{
   "result": {
       "status": "success",
       "message": "Comment Annotation(s) added successfully.",
       "data": {
           "-O0mpUziLcBwzREvZKs6": {
               "success": true,
               "annotationId": "-O0mpUziLcBwzREvZKs6",
               "commentIds": [
                   126535
               ],
               "message": "Added Successfully"
           }
       }
   }
}

Delete Users from Groups Get Comment Annotations

⌘I

REST APIs

SDK

​Endpoint

​Headers

​Body

​Params

​Example Requests

​Add comment annotation by organizationId, documentId and location

​Add comment annotation with user tagging

​Response

​Success Response

​Failure Response

Endpoint

Headers

Body

Params

Example Requests

Add comment annotation by organizationId, documentId and location

Add comment annotation with user tagging

Response

Success Response

Failure Response