Update Comment Annotations

Update V2 comment annotations via REST: patch status, priority, assignee, context, or suggestion payload by annotation, location, or user ID.

POST /v2/commentannotations/update

Update Comment Annotations

cURL

curl --request POST \
  --url https://api.velt.dev/v2/commentannotations/update \
  --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>",
    "locationIds": [
      "<string>"
    ],
    "userIds": [
      "<string>"
    ],
    "annotationIds": [
      "<string>"
    ],
    "updatedData": [
      {
        "location": {
          "id": "<string>",
          "locationName": "<string>"
        },
        "targetElement": {
          "elementId": "<string>",
          "targetText": "<string>",
          "occurrence": 123,
          "selectAllContent": true
        },
        "from": {},
        "status": {
          "id": "<string>",
          "name": "<string>",
          "type": "<string>",
          "color": "<string>",
          "lightColor": "<string>",
          "svg": "<string>",
          "iconUrl": "<string>"
        },
        "statusUpdatedByUserId": {},
        "resolvedByUserId": {},
        "assignedTo": {},
        "context": {},
        "priority": {
          "id": "<string>",
          "name": "<string>",
          "color": "<string>",
          "lightColor": "<string>"
        },
        "suggestion": {
          "status": "<string>",
          "targetId": "<string>",
          "targetType": "<string>",
          "oldValue": "<any>",
          "newValue": "<any>",
          "summary": {},
          "driftDetected": true
        }
      }
    ],
    "updateUsers": [
      {
        "oldUser": {
          "userId": "<string>",
          "name": "<string>",
          "email": "<string>"
        },
        "newUser": {
          "userId": "<string>",
          "name": "<string>",
          "email": "<string>"
        }
      }
    ]
  }
}
'

{
    "result": {
        "status": "success",
        "message": "Annotations updated successfully.",
        "data": {
            "yourAnnotationId1": {
                "success": true,
                "id": "yourAnnotationId1",
                "message": "Annotations updated successfully"
            }
        }
    }
}

Use this API to update comment annotations in a document within an organization. Additional filters can be applied using location IDs, annotation IDs, or user IDs.

Endpoint

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

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

locationIds · string[]

Array of Location IDs

userIds · string[]

Array of User IDs. These are the users who created the comment annotation.

annotationIds · string[]

Array of Annotation IDs

updatedData · object[]

Show properties

location · object

Show properties

id · 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.

from · User

User object from whom the Comment Annotation is added

status · Status

Status

Show properties

id · string · required

Status ID

name · string · required

Status Name

type · string · required

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

color · string

Text and comment pin color

lightColor · string

Background color on the status indicator

svg · string

Raw SVG of the icon.

iconUrl · string

Icon URL.

statusUpdatedByUserId · string | null

User ID of whoever made this status change.

Pass null to clear it. Omit the field to leave the stored value unchanged.

resolvedByUserId · string | null

User ID of whoever resolved the comment annotation. This is what resolvedBy filtering on Get Comment Annotations matches against.

Pass null to clear it. Omit the field to leave the stored value unchanged.

Setting a status whose type is not terminal clears this field and resolvedByUser automatically, even if you pass a value here. A comment annotation that is no longer resolved cannot keep a resolver. statusUpdatedByUserId is not cleared, so you still have a record of who reopened it.

assignedTo · User

User object to whom the comment is assigned

context · object

Custom key/value metadata object

priority · object

Priority

Show properties

id · string · required

Priority ID

name · string · required

Priority Name

color · string

Priority Color

lightColor · string

Priority Light Color

suggestion · object

Proposed-change payload for type: "suggestion" annotations. Any fields you send replace the persisted suggestion object. Include the existing fields when you only want to change one value (for example, status); otherwise omitted fields are cleared.

The schema is open: additional custom fields are stored as-is. Unlike create, status is honored here and can be set to pending, accepted, or rejected.

Show properties

status · string

Suggestion lifecycle status. One of: pending, accepted, or rejected.

targetId · string

Stable ID of the thing being changed.

targetType · string

Kind of target the suggestion applies to.

oldValue · any

The value at the time the suggestion was created.

newValue · any

The proposed new value.

summary · string | null

Optional human-readable summary of the change.

driftDetected · boolean

Set to true when the live target value differs from oldValue.

updateUsers · object[]

Show properties

oldUser · User · required

Show properties

userId · string · required

Old user’s ID

name · string

Old user’s name

email · string

Old user’s email

newUser · User · required

Show properties

userId · string · required

New user’s ID

name · string

New user’s name

email · string

New user’s email

Example Requests

1. Update all comment annotations by organizationId and documentId

{
  "data": {
    "organizationId": "yourOrganizationId",
    "documentId": "yourDocumentId",
    "annotationIds": [
      "yourAnnotationId1",
      "yourAnnotationId2"
    ],
    "updatedData" : {
      "status": {
        "id": "inprogress",
        "name": "In Progress",
        "type": "ongoing"
      }
    }
  }
}

2. Update comment annotations by organizationId, documentId and locationIds

{
  "data": {
    "organizationId": "yourOrganizationId",
    "documentId": "yourDocumentId",
    "locationIds": [
      "locationx"
    ],
    "annotationIds": [
      "yourAnnotationId1",
      "yourAnnotationId2"
    ],
    "updatedData" : {
      "status": {
        "id": "inprogress",
        "name": "In Progress",
        "type": "ongoing"
      }
    }
  }
}

3. Update annotations by organizationId, documentId, locationIds and userIds

{
  "data": {
    "organizationId": "yourOrganizationId",
    "documentId": "yourDocumentId",
    "locationIds": [
      "locationx"
    ],
    "userIds": [
      "yourUserId"
    ],
    "annotationIds": [
      "yourAnnotationId1",
      "yourAnnotationId2"
    ],
    "updatedData" : {
      "status": {
        "id": "inprogress",
        "name": "In Progress",
        "type": "ongoing"
      }
    }
  }
}

4. Update comment annotations by organizationId, documentId and userIds

{
  "data": {
    "organizationId": "yourOrganizationId",
    "documentId": "yourDocumentId",
    "userIds": [
      "yourUserId"
    ],
    "annotationIds": [
      "yourAnnotationId1",
      "yourAnnotationId2"
    ],
    "updatedData" : {
      "status": {
        "id": "inprogress",
        "name": "In Progress",
        "type": "ongoing"
      }
    }
  }
}

5. Update comment annotations by organizationId, documentId and annotationIds

{
  "data": {
    "organizationId": "yourOrganizationId",
    "documentId": "yourDocumentId",
    "annotationIds": [
      "yourAnnotationId1",
      "yourAnnotationId2"
    ],
    "updatedData" : {
      "status": {
        "id": "inprogress",
        "name": "In Progress",
        "type": "ongoing"
      }
    }
  }
}

6. Update comment annotations by organizationId, documentId, locationIds and annotationIds

{
  "data": {
    "organizationId": "yourOrganizationId",
    "documentId": "yourDocumentId",
    "locationIds": [
      "locationx"
    ],
    "annotationIds": [
      "yourAnnotationId1",
      "yourAnnotationId2"
    ],
    "updatedData" : {
      "status": {
        "id": "inprogress",
        "name": "In Progress",
        "type": "ongoing"
      }
    }
  }
}

7. Update Users in existing comment annotations

{
  "data": {
    "organizationId": "yourOrganizationId",
    "documentId": "yourDocumentId",
    "annotationIds": [
      "yourAnnotationId1",
      "yourAnnotationId2"
    ],
    "updateUsers" : [
      {
        "oldUser": {
          "userId": "oldUserId",
        },
        "newUser": {
          "userId": "newUserId",
          "name": "newUserName",
          "email": "newUserEmail"
        }
      }
    ]
  }
}

8. Update comment annotations with access context

{
  "data": {
    "organizationId": "yourOrganizationId",
    "documentId": "yourDocumentId",
    "annotationIds": [
      "yourAnnotationId1"
    ],
    "updatedData": {
      "context": {
        "access": {
          "entityId": "numberOfAccounts",
          "dashboardId": "salesDashboard"
        }
      }
    }
  }
}

9. Resolve a comment annotation and record who resolved it

Recording the resolver is what makes the annotation match a resolvedBy filter later.

{
  "data": {
    "organizationId": "yourOrganizationId",
    "documentId": "yourDocumentId",
    "annotationIds": [
      "yourAnnotationId1"
    ],
    "updatedData": {
      "status": {
        "id": "RESOLVED",
        "name": "Resolved",
        "type": "terminal"
      },
      "resolvedByUserId": "yourUserId",
      "statusUpdatedByUserId": "yourUserId"
    }
  }
}

10. Reopen a comment annotation

Moving to a non-terminal status clears resolvedByUserId and resolvedByUser for you, so there is no need to null them yourself. Send statusUpdatedByUserId to record who reopened it.

{
  "data": {
    "organizationId": "yourOrganizationId",
    "documentId": "yourDocumentId",
    "annotationIds": [
      "yourAnnotationId1"
    ],
    "updatedData": {
      "status": {
        "id": "OPEN",
        "name": "Open",
        "type": "default"
      },
      "statusUpdatedByUserId": "yourUserId"
    }
  }
}

Response

Success Response

{
    "result": {
        "status": "success",
        "message": "Annotations updated successfully.",
        "data": {
            "yourAnnotationId1": {
                "success": true,
                "id": "yourAnnotationId1",
                "message": "Annotations updated successfully"
            }
        }
    }
}

Failure Response

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

{
    "result": {
        "status": "success",
        "message": "Annotations updated successfully.",
        "data": {
            "yourAnnotationId1": {
                "success": true,
                "id": "yourAnnotationId1",
                "message": "Annotations updated successfully"
            }
        }
    }
}