Skip to main content
POST
/
v2
/
notifications
/
add
Add Notifications
curl --request POST \
  --url https://api.velt.dev/v2/notifications/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>",
    "createOrganization": true,
    "documentId": "<string>",
    "createDocument": true,
    "actionUser": {},
    "verifyUserPermissions": true,
    "notificationId": "<string>",
    "isNotificationResolverUsed": true,
    "displayHeadlineMessageTemplate": "<string>",
    "displayHeadlineMessageTemplateData": {
      "actionUser": {},
      "recipientUser": "<string>",
      "yourCustomField": "<string>"
    },
    "displayBodyMessage": "<string>",
    "notifyUsers": [
      {}
    ],
    "notifyAll": true,
    "notificationSource": "<string>",
    "notificationSourceData": {},
    "context": {
      "access": {}
    }
  }
}
'
{
  "result": {
    "status": "success",
    "message": "Notification added successfully.",
    "data": {
      "success": true,
      "message": "Notification added successfully."
    }
  }
}
Use this API to add notifications.

​
Endpoint

POST https://api.velt.dev/v2/notifications/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

​
Example Request

{
  "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

{
  "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
  }
}
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.

​
Example Request with Context

{
  "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
  }
}
When context is provided, notifications will be filtered based on the specified context fields. Users will only receive notifications that match their context permissions.

​
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. Omit displayHeadlineMessageTemplate and displayBodyMessage and set notificationSource to 'custom'. 
{
  "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
  }
}
When isNotificationResolverUsed is true, displayHeadlineMessageTemplate and displayBodyMessage are not required. Notification content is fetched from your configured data provider at read time.

​
Response

​
Success Response

{
  "result": {
    "status": "success",
    "message": "Notification added successfully.",
    "data": {
      "success": true,
      "message": "Notification added successfully."
    }
  }
}

​
Failure Response

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

{
  "result": {
    "status": "success",
    "message": "Notification added successfully.",
    "data": {
      "success": true,
      "message": "Notification added successfully."
    }
  }
}