> ## Documentation Index
> Fetch the complete documentation index at: https://velt.dev/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Update Notifications

Use this API to update notifications.

# Endpoint

`POST https://api.velt.dev/v2/notifications/update`

# Headers

<ParamField header="x-velt-api-key" type="string" required>
  Your API key.
</ParamField>

<ParamField header="x-velt-auth-token" type="string" required>
  Your [Auth Token](/security/auth-tokens).
</ParamField>

# Body

#### Params

<ParamField body="data" type="object" required>
  <Expandable title="properties">
    <ParamField body="organizationId" type="string" required>
      Organization ID
    </ParamField>

    <ParamField body="documentId" type="string">
      Document ID (Optional)
    </ParamField>

    <ParamField body="locationId" type="string">
      Location ID
    </ParamField>

    <ParamField body="userId" type="string">
      User ID  (Optional)
    </ParamField>

    <ParamField body="verifyUserPermissions" type="boolean">
      When enabled, notifications are only updated for users who have access to the specified document.
      This ensures notification updates respect document access permissions configured via Access Control or Permission Provider.

      Default: `false`
    </ParamField>

    <ParamField body="notifications" type="object">
      Notifications object

      <Expandable title="properties">
        <ParamField body="id" type="string">
          Notification ID
        </ParamField>

        <ParamField body="actionUser" type="User">
          User who took the action
        </ParamField>

        <ParamField body="displayHeadlineMessageTemplate" type="string">
          Display Headline Message Template
        </ParamField>

        <ParamField body="displayHeadlineMessageTemplateData" type="object">
          Display Headline Message Template Data

          <Expandable title="properties">
            <ParamField body="actionUser" type="User">
              User who took the action
            </ParamField>

            <ParamField body="recipientUser" type="string">
              User who was directly affected by the action
            </ParamField>

            <ParamField body="yourCustomField" type="string">
              Any custom field with string value
            </ParamField>
          </Expandable>
        </ParamField>

        <ParamField body="displayBodyMessage" type="string">
          Display Body Message
        </ParamField>

        <ParamField body="notificationSourceData" type="object">
          Any custom object to be stored with the notification.
          When the user clicks on the notification, this data will be sent to in the callback.
        </ParamField>

        <ParamField body="readByUserIds" type="string[]">
          Array of user ids that you want to mark the notification as read.
        </ParamField>

        <ParamField body="persistReadForUsers" type="boolean">
          Use this with the `readByUserIds` param. If `true`, the read notifications will be not be removed from the "For You" tab.
        </ParamField>
      </Expandable>
    </ParamField>
  </Expandable>
</ParamField>

## **Example Requests**

#### 1. Update by organizationId and documentId

```JSON theme={null}
{
   "data": {
       "organizationId": "yourOrganizationId",
       "documentId": "yourDocumentId",
       "notifications": [
           {
               "id": "yourNotificationId",
               "displayBodyMessage": "This is body message (Secondary message)",
           }
       ]
   }
}
```

#### 2. Update by organizationId, documentId and locationId

```JSON theme={null}
{
   "data": {
       "organizationId": "yourOrganizationId",
       "documentId": "yourDocumentId",
       "locationId": "yourLocationId",
       "notifications": [
           {
               "id": "yourNotificationId",
               "displayBodyMessage": "This is body message (Secondary message)",
           }
       ]
   }
}
```

#### 3. Update by organizationId, documentId and userId

```JSON theme={null}
{
   "data": {
       "organizationId": "yourOrganizationId",
       "documentId": "yourDocumentId",
       "userId": "yourUserId",
       "notifications": [
           {
               "id": "yourNotificationId",
               "displayBodyMessage": "This is body message (Secondary message)",
           }
       ]
   }
}
```

#### 4. Update by organizationId and userId

```JSON theme={null}
{
   "data": {
       "organizationId": "yourOrganizationId",
       "userId": "yourUserId",
       "notifications": [
           {
               "id": "yourNotificationId",
               "displayBodyMessage": "This is body message (Secondary message)",
           }
       ]
   }
}
```

#### 5. Update by organizationId, documentId, locationId and userId

```JSON theme={null}
{
   "data": {
       "organizationId": "yourOrganizationId",
       "documentId": "yourDocumentId",
       "userId": "yourUserId",
       "locationId": "yourLocationId",
       "notifications": [
           {
               "id": "yourNotificationId",
               "displayBodyMessage": "This is body message (Secondary message)",
           }
       ]
   }
}
```

#### 6. Update with Permission Verification

```JSON theme={null}
{
  "data": {
    "organizationId": "yourOrganizationId",
    "documentId": "yourDocumentId",
    "verifyUserPermissions": true,
    "notifications": [
      {
        "id": "yourNotificationId",
        "displayBodyMessage": "This is updated body message (Secondary message)"
      }
    ]
  }
}
```

<Note>
  When `verifyUserPermissions` is enabled, the API checks document access for each user before updating their notifications. Updates are only applied to users with access to the document.
</Note>

# Response

#### Success Response

```JSON theme={null}
{
   "result": {
       "status": "success",
       "message": "Notification(s) updated successfully.",
       "data": {
           "5471488637912692": {
               "success": true,
               "message": "Notification updated."
           }
       }
   }
}
```

#### When some notifications are not found

```JSON theme={null}
{
   "result": {
       "status": "success",
       "message": "Notification(s) updated successfully.",
       "data": {
           "5471488637912692": {
               "success": false,
               "message": "Failed to update notification."
           },
           "5471488637912693": {
               "success": true,
               "message": "Notification updated."
           }
       }
   }
}
```

#### Failure Response

```JSON theme={null}
{
  "error": {
    "message": "ERROR_MESSAGE",
    "status": "INVALID_ARGUMENT"
  }
}
```

<ResponseExample>
  ```js theme={null}
  {
     "result": {
         "status": "success",
         "message": "Notification(s) updated successfully.",
         "data": {
             "5471488637912692": {
                 "success": true,
                 "message": "Notification updated."
             }
         }
     }
  }
  ```
</ResponseExample>