> ## 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/v1/notifications/add`

# Headers

**x-velt-api-key** `string` *required*

Your API key.

**x-velt-auth-token** `string` *required*

Your [Auth Token](https://velt.dev/docs/security/auth-tokens.md).

# Body

#### Params

**data** `object` *required*

**properties**

**organizationId** `string` *required*

Organization ID

**documentId** `string` *required*

Document ID

**actionUser** `User` *required*

User who took the action

**notificationId** `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.

**displayHeadlineMessageTemplate** `string` *required*

Display Headline Message Template

**displayHeadlineMessageTemplateData** `object`

Display Headline Message Template Data (Optional)

**properties**

**actionUser** `User`

User who took the action

**recipientUser** `string`

User who was directly affected by the action

**yourCustomField** `string`

Any custom field with string value

**displayBodyMessage** `string` *required*

Display Body Message

**notifyUsers** `User[]` *required*

Array of Notify Users

**notifyAll** `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.

**notificationSourceData** `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.

**createDocument** `boolean`

If set to true, a new document will be created before the notification is created.

**createOrganization** `boolean`

If set to true, a new organization will be created (if it doesn't exist) before the notification is created.

## **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"
      }
    ]
  }
}
```

# 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"
  }
}
```

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


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.