API Reference
Subscribers
- GETGet subscribers
- POSTCreate subscriber
- POSTBulk create subscribers
- GETGet subscriber
- PUTUpsert subscriber
- DELDelete subscriber
- PUTUpdate subscriber credentials
- DELDelete subscriber credentials by providerId
- PATCHUpdate subscriber online status
- GETGet subscriber preferences
- GETGet subscriber global preferences
- PATCHUpdate subscriber preference
- PATCHUpdate subscriber global preferences
- GETGet in-app notification feed for a particular subscriber
- GETGet the unseen in-app notifications count for subscribers feed
- POSTMark a subscriber feed message as seen
- POSTMarks all the subscriber messages as read, unread, seen or unseen. Optionally you can pass feed id (or array) to mark messages of a particular feed.
- POSTMark message action as seen
- GETHandle providers oauth redirect
- GETHandle chat oauth
Topics
Notification
Workflows
Workflow Overrides
Workflow groups
Integrations
Layouts
Execution Details
Organizations
Mark message action as seen
curl --request POST \
--url https://api.novu.co/v1/subscribers/{subscriberId}/messages/{messageId}/actions/{type} \
--header 'Authorization: <api-key>' \
--header 'Content-Type: application/json' \
--data '{
"status": "pending",
"payload": {}
}'{
"data": {
"_id": "<string>",
"_templateId": "<string>",
"_environmentId": "<string>",
"_messageTemplateId": "<string>",
"_organizationId": "<string>",
"_notificationId": "<string>",
"_subscriberId": "<string>",
"subscriber": {
"_id": "<string>",
"firstName": "<string>",
"lastName": "<string>",
"email": "<string>",
"phone": "<string>",
"avatar": "<string>",
"locale": "<string>",
"subscriberId": "<string>",
"channels": [
{
"providerId": "slack",
"integrationIdentifier": "<string>",
"credentials": {
"webhookUrl": "https://example.com/webhook",
"channel": "general",
"deviceTokens": [
"token1",
"token2",
"token3"
],
"alertUid": "12345-abcde",
"title": "Critical Alert",
"imageUrl": "https://example.com/image.png",
"state": "resolved",
"externalUrl": "https://example.com/details"
},
"_integrationId": "<string>"
}
],
"topics": [
"<string>"
],
"isOnline": true,
"lastOnlineAt": "<string>",
"_organizationId": "<string>",
"_environmentId": "<string>",
"deleted": true,
"createdAt": "<string>",
"updatedAt": "<string>",
"__v": 123,
"data": {},
"timezone": "<string>"
},
"template": {
"_id": "<string>",
"name": "<string>",
"description": "<string>",
"active": true,
"draft": true,
"preferenceSettings": {
"email": true,
"sms": true,
"in_app": true,
"chat": true,
"push": true
},
"critical": true,
"tags": [
"<string>"
],
"steps": [
{
"_id": "<string>",
"uuid": "<string>",
"name": "<string>",
"_templateId": "<string>",
"active": true,
"shouldStopOnFail": true,
"template": {},
"filters": [
{
"isNegated": true,
"type": "BOOLEAN",
"value": "AND",
"children": [
{
"field": "<string>",
"value": "<string>",
"operator": "LARGER",
"on": "subscriber"
}
]
}
],
"_parentId": "<string>",
"metadata": {
"amount": 123,
"unit": "seconds",
"digestKey": "<string>",
"type": "regular",
"backoff": true,
"backoffAmount": 123,
"backoffUnit": "seconds",
"updateMode": true
},
"replyCallback": {
"active": true,
"url": "<string>"
},
"variants": [
{
"_id": "<string>",
"uuid": "<string>",
"name": "<string>",
"_templateId": "<string>",
"active": true,
"shouldStopOnFail": true,
"template": {},
"filters": [
{
"isNegated": true,
"type": "BOOLEAN",
"value": "AND",
"children": [
{
"field": "<string>",
"value": "<string>",
"operator": "LARGER",
"on": "subscriber"
}
]
}
],
"_parentId": "<string>",
"metadata": {
"amount": 123,
"unit": "seconds",
"digestKey": "<string>",
"type": "regular",
"backoff": true,
"backoffAmount": 123,
"backoffUnit": "seconds",
"updateMode": true
},
"replyCallback": {
"active": true,
"url": "<string>"
}
}
]
}
],
"_organizationId": "<string>",
"_creatorId": "<string>",
"_environmentId": "<string>",
"triggers": [
{
"type": "event",
"identifier": "<string>",
"variables": [
{
"name": "<string>"
}
],
"subscriberVariables": [
{
"name": "<string>"
}
]
}
],
"_notificationGroupId": "<string>",
"_parentId": "<string>",
"deleted": true,
"deletedAt": "<string>",
"deletedBy": "<string>",
"notificationGroup": {
"_id": "<string>",
"name": "<string>",
"_environmentId": "<string>",
"_organizationId": "<string>",
"_parentId": "<string>"
},
"data": {},
"workflowIntegrationStatus": {}
},
"templateIdentifier": "<string>",
"createdAt": "<string>",
"lastSeenDate": "<string>",
"lastReadDate": "<string>",
"content": {
"type": "button",
"content": "<string>",
"url": "<string>",
"styles": {
"textAlign": "center"
}
},
"transactionId": "<string>",
"subject": "<string>",
"channel": "in_app",
"read": true,
"seen": true,
"email": "<string>",
"phone": "<string>",
"directWebhookUrl": "<string>",
"providerId": "<string>",
"deviceTokens": [
"<string>"
],
"title": "<string>",
"cta": {
"type": "redirect",
"data": {
"url": "<string>"
},
"action": {
"status": "pending",
"buttons": [
{
"type": "primary",
"content": "<string>",
"resultContent": "<string>"
}
],
"result": {
"payload": {},
"type": "primary"
}
}
},
"_feedId": "<string>",
"status": "sent",
"errorId": "<string>",
"errorText": "<string>",
"payload": {},
"overrides": {}
}
}Enter your API key in the Authorization field like the example shown below:
E.g ApiKey 18d2e625f05d80e
Authorizations
API key authentication. Allowed headers-- "Authorization: ApiKey <api_key>".
Body
Message action status
pending, done Message action payload
Response
Template ID associated with the message
Environment ID where the message is sent
Message template ID
Organization ID associated with the message
Notification ID associated with the message
Subscriber ID associated with the message
Creation date of the message
Content of the message, can be an email block or a string
Type of the email block
button, text Content of the email block
URL associated with the email block, if any
Transaction ID associated with the message
Channel type through which the message is sent
in_app, email, sms, chat, push Indicates if the message has been read
Indicates if the message has been seen
Call to action associated with the message
Data associated with the call to action
URL for the call to action
Type of call to action
redirect Action associated with the call to action
Status of the message action
pending, done List of buttons associated with the message action
Status of the message
sent, error, warning Unique identifier for the message
Subscriber details, if available
The identifier used to create this subscriber, which typically corresponds to the user ID in your system.
The unique identifier of the organization to which the subscriber belongs.
The unique identifier of the environment associated with this subscriber.
Indicates whether the subscriber has been deleted.
The timestamp indicating when the subscriber was created, in ISO 8601 format.
The timestamp indicating when the subscriber was last updated, in ISO 8601 format.
The internal ID generated by Novu for your subscriber. This ID does not match the subscriberId used in your queries. Refer to subscriberId for that identifier.
The first name of the subscriber.
The last name of the subscriber.
The email address of the subscriber.
The phone number of the subscriber.
The URL of the subscriber's avatar image.
The locale setting of the subscriber, indicating their preferred language or region.
An array of channel settings associated with the subscriber.
The provider identifier for the credentials
slack, discord, msteams, mattermost, ryver, zulip, grafana-on-call, getstream, rocket-chat, whatsapp-business, fcm, apns, expo, one-signal, pushpad, push-webhook, pusher-beams Credentials payload for the specified provider
Webhook URL used by chat app integrations. The webhook should be obtained from the chat app provider.
"https://example.com/webhook"
Channel specification for Mattermost chat notifications.
"general"
Contains an array of the subscriber device tokens for a given provider. Used on Push integrations.
["token1", "token2", "token3"]
Alert UID for Grafana on-call webhook payload.
"12345-abcde"
Title to be used with Grafana on-call webhook.
"Critical Alert"
Image URL property for Grafana on-call webhook.
"https://example.com/image.png"
State property for Grafana on-call webhook.
"resolved"
Link to upstream details property for Grafana on-call webhook.
"https://example.com/details"
The unique identifier of the integration associated with this channel.
The integration identifier
An array of topics that the subscriber is subscribed to.
Indicates whether the subscriber is currently online.
The timestamp indicating when the subscriber was last online, in ISO 8601 format.
The version of the subscriber document.
Additional custom data for the subscriber
Timezone of the subscriber
Workflow template associated with the message
Unique identifier for the notification step.
Universally unique identifier for the notification step.
Name of the notification step.
ID of the template associated with this notification step.
Indicates whether the notification step is active.
Determines if the process should stop on failure.
Message template used in this notification step.
Filters applied to this notification step.
BOOLEAN, TEXT, DATE, NUMBER, STATEMENT, LIST, MULTI_LIST, GROUP AND, OR ID of the parent notification step, if applicable.
Metadata associated with the workflow step. Can vary based on the type of step.
regular, backoff seconds, minutes, hours, days, weeks, months seconds, minutes, hours, days, weeks, months Unique identifier for the notification step.
Universally unique identifier for the notification step.
Name of the notification step.
ID of the template associated with this notification step.
Indicates whether the notification step is active.
Determines if the process should stop on failure.
Message template used in this notification step.
Filters applied to this notification step.
ID of the parent notification step, if applicable.
Metadata associated with the workflow step. Can vary based on the type of step.
Callback information for replies, including whether it is active and the callback URL.
event Name of the variable
Identifier for the message template
Last seen date of the message, if available
Last read date of the message, if available
Subject of the message, if applicable
Email address associated with the message, if applicable
Phone number associated with the message, if applicable
Direct webhook URL for the message, if applicable
Provider ID associated with the message, if applicable
Device tokens associated with the message, if applicable
Title of the message, if applicable
Feed ID associated with the message, if applicable
Error ID if the message has an error
Error text if the message has an error
The payload that was used to send the notification trigger
Provider specific overrides used when triggering the notification
curl --request POST \
--url https://api.novu.co/v1/subscribers/{subscriberId}/messages/{messageId}/actions/{type} \
--header 'Authorization: <api-key>' \
--header 'Content-Type: application/json' \
--data '{
"status": "pending",
"payload": {}
}'{
"data": {
"_id": "<string>",
"_templateId": "<string>",
"_environmentId": "<string>",
"_messageTemplateId": "<string>",
"_organizationId": "<string>",
"_notificationId": "<string>",
"_subscriberId": "<string>",
"subscriber": {
"_id": "<string>",
"firstName": "<string>",
"lastName": "<string>",
"email": "<string>",
"phone": "<string>",
"avatar": "<string>",
"locale": "<string>",
"subscriberId": "<string>",
"channels": [
{
"providerId": "slack",
"integrationIdentifier": "<string>",
"credentials": {
"webhookUrl": "https://example.com/webhook",
"channel": "general",
"deviceTokens": [
"token1",
"token2",
"token3"
],
"alertUid": "12345-abcde",
"title": "Critical Alert",
"imageUrl": "https://example.com/image.png",
"state": "resolved",
"externalUrl": "https://example.com/details"
},
"_integrationId": "<string>"
}
],
"topics": [
"<string>"
],
"isOnline": true,
"lastOnlineAt": "<string>",
"_organizationId": "<string>",
"_environmentId": "<string>",
"deleted": true,
"createdAt": "<string>",
"updatedAt": "<string>",
"__v": 123,
"data": {},
"timezone": "<string>"
},
"template": {
"_id": "<string>",
"name": "<string>",
"description": "<string>",
"active": true,
"draft": true,
"preferenceSettings": {
"email": true,
"sms": true,
"in_app": true,
"chat": true,
"push": true
},
"critical": true,
"tags": [
"<string>"
],
"steps": [
{
"_id": "<string>",
"uuid": "<string>",
"name": "<string>",
"_templateId": "<string>",
"active": true,
"shouldStopOnFail": true,
"template": {},
"filters": [
{
"isNegated": true,
"type": "BOOLEAN",
"value": "AND",
"children": [
{
"field": "<string>",
"value": "<string>",
"operator": "LARGER",
"on": "subscriber"
}
]
}
],
"_parentId": "<string>",
"metadata": {
"amount": 123,
"unit": "seconds",
"digestKey": "<string>",
"type": "regular",
"backoff": true,
"backoffAmount": 123,
"backoffUnit": "seconds",
"updateMode": true
},
"replyCallback": {
"active": true,
"url": "<string>"
},
"variants": [
{
"_id": "<string>",
"uuid": "<string>",
"name": "<string>",
"_templateId": "<string>",
"active": true,
"shouldStopOnFail": true,
"template": {},
"filters": [
{
"isNegated": true,
"type": "BOOLEAN",
"value": "AND",
"children": [
{
"field": "<string>",
"value": "<string>",
"operator": "LARGER",
"on": "subscriber"
}
]
}
],
"_parentId": "<string>",
"metadata": {
"amount": 123,
"unit": "seconds",
"digestKey": "<string>",
"type": "regular",
"backoff": true,
"backoffAmount": 123,
"backoffUnit": "seconds",
"updateMode": true
},
"replyCallback": {
"active": true,
"url": "<string>"
}
}
]
}
],
"_organizationId": "<string>",
"_creatorId": "<string>",
"_environmentId": "<string>",
"triggers": [
{
"type": "event",
"identifier": "<string>",
"variables": [
{
"name": "<string>"
}
],
"subscriberVariables": [
{
"name": "<string>"
}
]
}
],
"_notificationGroupId": "<string>",
"_parentId": "<string>",
"deleted": true,
"deletedAt": "<string>",
"deletedBy": "<string>",
"notificationGroup": {
"_id": "<string>",
"name": "<string>",
"_environmentId": "<string>",
"_organizationId": "<string>",
"_parentId": "<string>"
},
"data": {},
"workflowIntegrationStatus": {}
},
"templateIdentifier": "<string>",
"createdAt": "<string>",
"lastSeenDate": "<string>",
"lastReadDate": "<string>",
"content": {
"type": "button",
"content": "<string>",
"url": "<string>",
"styles": {
"textAlign": "center"
}
},
"transactionId": "<string>",
"subject": "<string>",
"channel": "in_app",
"read": true,
"seen": true,
"email": "<string>",
"phone": "<string>",
"directWebhookUrl": "<string>",
"providerId": "<string>",
"deviceTokens": [
"<string>"
],
"title": "<string>",
"cta": {
"type": "redirect",
"data": {
"url": "<string>"
},
"action": {
"status": "pending",
"buttons": [
{
"type": "primary",
"content": "<string>",
"resultContent": "<string>"
}
],
"result": {
"payload": {},
"type": "primary"
}
}
},
"_feedId": "<string>",
"status": "sent",
"errorId": "<string>",
"errorText": "<string>",
"payload": {},
"overrides": {}
}
}