> ## 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.

# Add Notifications

Use this API to add notifications.

# Endpoint

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

# 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="createOrganization" type="boolean">
      If set to true, a new organization will be created (if it doesn't exist) before the notification is created.
    </ParamField>

    <ParamField body="documentId" type="string" required>
      Document ID
    </ParamField>

    <ParamField body="createDocument" type="boolean">
      If set to true, a new document will be created before the notification is created.
    </ParamField>

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

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

      Default: `false`
    </ParamField>

    <ParamField body="notificationId" type="string">
      Notification ID. If not provided, Velt will generate a random ID.
      Use this if you want more control on the ID being set and prevent duplicate notifications.
      Only the special characters `_`, `-` are allowed.
    </ParamField>

    <ParamField body="isNotificationResolverUsed" type="boolean">
      Set to `true` to enable [Notification Resolver](/self-host-data/notifications) mode.
      When enabled, `displayHeadlineMessageTemplate` and `displayBodyMessage` are not required — notification content is resolved from your own infrastructure at read time.
    </ParamField>

    <ParamField body="displayHeadlineMessageTemplate" type="string">
      Display Headline Message Template. Required unless `isNotificationResolverUsed` is `true`.
    </ParamField>

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

      <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. Required unless `isNotificationResolverUsed` is `true`.
    </ParamField>

    <ParamField body="notifyUsers" type="User[]" required>
      Array of Notify Users
    </ParamField>

    <ParamField body="notifyAll" type="boolean">
      Default is true.
      If set to true, the notification will be sent to all users in the organization.
      If set to false, the notification will be sent to only the users specified in the `notifyUsers` array.
    </ParamField>

    <ParamField body="notificationSource" type="string">
      Source identifier for the notification. Set to `'custom'` for notifications that should be routed through the [Notification Resolver](/self-host-data/notifications). Other values include `'comment'`, `'huddle'`, and `'crdt'`.
    </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 in the callback.
    </ParamField>

    <ParamField body="isNotificationResolverUsed" type="boolean">
      Use this for self-hosting notification data. Set to `true` if you are using the notification resolver data provider in the SDK. When `true`, indicates that PII has been stripped from the notification record and the record is pending resolver re-hydration.
    </ParamField>

    <ParamField body="context" type="Context">
      Context for filtering notifications. Use this to enable context-based filtering of notifications.

      <Expandable title="properties">
        <ParamField body="access" type="object" required>
          Key-value pairs for filtering. Keys are custom field names, values are strings or numbers.

          <Expandable title="example">
            ```json theme={null}
            {
              "entityId": "numberOfVisitors",
              "dashboardId": "myDashboard"
            }
            ```
          </Expandable>
        </ParamField>
      </Expandable>
    </ParamField>
  </Expandable>
</ParamField>

## **Example Request**

```JSON theme={null}
{
  "data": {
    "organizationId": "yourOrganizationId",
    "documentId": "yourDocumentId",
    "actionUser": {
      "userId": "yourUserId",
      "name": "User Name",
      "email": "user@example.com"
    },
    "displayHeadlineMessageTemplate": "This is main template, you can pass variables using curly brackets like this: {actionUser}, {recipientUser}, {yourCustomVariableWithStringValue}",
    "displayHeadlineMessageTemplateData": {
      "actionUser": {
        "userId": "yourUserId",
        "name": "User Name",
        "email": "user@example.com"
      },
      "recipientUser": {
        "userId": "recipientUserId",
        "name": "Recipient Name",
        "email": "recipient@example.com"
      },
      "yourCustomField": "Variable will be replaced with this text"
    },
    "displayBodyMessage": "This is body message (Secondary message)",
    "notifyUsers": [
      {
        "email": "test@example.com",
        "userId": "testingUserId"
      },
      {
        "userId": "yourUserId",
        "name": "User Name",
        "email": "user@example.com"
      }
    ]
  }
}
```

## **Example Request with Permission Verification**

```JSON theme={null}
{
  "data": {
    "organizationId": "org1",
    "documentId": "document3",
    "actionUser": {
      "userId": "1.1"
    },
    "verifyUserPermissions": true,
    "displayHeadlineMessageTemplate": "This is main template, you can pass variables using curly brackets like this: {actionUser}, {recipientUser}",
    "displayHeadlineMessageTemplateData": {
      "actionUser": {
        "userId": "1.1"
      },
      "recipientUser": {
        "userId": "2.2"
      }
    },
    "displayBodyMessage": "This is body message (Secondary message)",
    "notifyUsers": [
      {
        "userId": "2.2"
      }
    ],
    "notifyAll": false
  }
}
```

<Note>
  When `verifyUserPermissions` is enabled, the API checks document access for each user before creating notifications. Only users with access to the document will receive notifications.
</Note>

## **Example Request with Context**

```JSON theme={null}
{
  "data": {
    "organizationId": "org1",
    "documentId": "document3",
    "actionUser": {
      "userId": "1.1",
      "name": "User One",
      "email": "user1@example.com"
    },
    "context": {
      "access": {
        "entityId": "numberOfVisitors",
        "dashboardId": "myDashboard"
      }
    },
    "displayHeadlineMessageTemplate": "New comment on {entityName}",
    "displayHeadlineMessageTemplateData": {
      "entityName": "Visitor Analytics"
    },
    "displayBodyMessage": "A new comment has been added to the visitor analytics dashboard",
    "notifyUsers": [
      {
        "userId": "2.2"
      }
    ],
    "notifyAll": false
  }
}
```

<Note>
  When context is provided, notifications will be filtered based on the specified context fields. Users will only receive notifications that match their context permissions.
</Note>

## **Example Request with Notification Resolver**

Use this when notification content (headline, body) is stored on your own infrastructure and resolved at read time via the [Notification Resolver](/self-host-data/notifications). Omit `displayHeadlineMessageTemplate` and `displayBodyMessage` and set `notificationSource` to `'custom'`.

```JSON theme={null}
{
  "data": {
    "organizationId": "yourOrganizationId",
    "documentId": "yourDocumentId",
    "actionUser": {
      "userId": "yourUserId",
      "name": "User Name",
      "email": "user@example.com"
    },
    "notificationId": "custom-notif-001",
    "isNotificationResolverUsed": true,
    "notificationSource": "custom",
    "notifyUsers": [
      {
        "userId": "recipientUserId",
        "email": "recipient@example.com"
      }
    ],
    "notifyAll": false
  }
}
```

<Note>
  When `isNotificationResolverUsed` is `true`, `displayHeadlineMessageTemplate` and `displayBodyMessage` are not required. Notification content is fetched from your configured data provider at read time.
</Note>

# Response

#### Success Response

```JSON theme={null}
{
  "result": {
    "status": "success",
    "message": "Notification added successfully.",
    "data": {
      "success": true,
      "message": "Notification added successfully."
    }
  }
}
```

#### Failure Response

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

<ResponseExample>
  ```js theme={null}
  {
    "result": {
      "status": "success",
      "message": "Notification added successfully.",
      "data": {
        "success": true,
        "message": "Notification added successfully."
      }
    }
  }
  ```
</ResponseExample>