Overview

The API enables you to access the entire Novu platform using a RESTful API. This API provides a programmatic access to the platform's data and functionality.

Base URL
1https://api.novu.co/v1

Client libraries

Novu offers native SDK in several popular programming languages:

Get messages

Returns a list of messages, could paginate using the `page` query parameter

Endpoint

get/v1/messages

Query parameters

  • channelstring (optional)

    The channel for the messages you wish to list

  • subscriberIdstring (optional)

    The subscriberId for the subscriber you like to list messages for

  • pagenumber (optional)

    The page to fetch, defaults to 0

Responses

get/v1/messages
1import fetch from 'node-fetch';
2
3const response = await fetch('https://api.novu.co/v1/messages', {
4  method: 'GET',
5  
6});
7const data = await response.json();
8    
Response
1{
2    totalCount: 0,
3    data: ["data"],
4    pageSize: 0,
5    page: 0
6}

Delete message

Deletes a message entity from the Novu platform

Endpoint

delete/v1/messages/:messageId

Path parameters

  • messageIdstring

Responses

delete/v1/messages/:messageId
1import fetch from 'node-fetch';
2
3const response = await fetch('https://api.novu.co/v1/messages/:messageId', {
4  method: 'DELETE',
5  
6});
7const data = await response.json();
8    
Response
1{
2    acknowledged: true,
3    status: "status"
4}

Trigger event

Trigger event is the main (and the only) way to send notification to subscribers. The trigger identifier is used to match the particular template associated with it. Additional information can be passed according the the body interface below.

Endpoint

post/v1/events/trigger

Body parameters

  • namestring

    The trigger identifier of the template you wish to send. This identifier can be found on the template page.

  • payloadobject

    The payload object is used to pass additional custom information that could be used to render the template, or perform routing rules based on it. This data will also be available when fetching the notifications feed from the API to display certain parts of the UI.

  • overridesobject (optional)

    This could be used to override provider specific configurations

  • tooneOf

    The recipients list of people who will receive the notification

    Show parameters
  • transactionIdstring (optional)

    A unique identifier for this transaction, we will generated a UUID if not provided.

Responses

post/v1/events/trigger
1import { Novu } from '@novu/node';
2
3export const novu = new Novu('<REPLACE_WITH_API_KEY_FROM_ADMIN_PANEL>');
4
5await novu.trigger('<REPLACE_WITH_EVENT_NAME_FROM_ADMIN_PANEL>',
6  {
7    to: {
8      subscriberId: '<USER_IDENTIFIER>',
9      email: 'email@email.com',
10      firstName: 'John',
11      lastName: 'Doe',
12    },
13    payload: {
14      customVariables: 'Hello'
15    },
16    transactionId: 'transactionId',
17  }
18);
19
Response
1{
2    acknowledged: true,
3    status: "status",
4    transactionId: "transactionId"
5}

Broadcast event to all

Trigger a broadcast event to all existing subscribers, could be used to send announcements, etc. In the future could be used to trigger events to a subset of subscribers based on defined filters.

Endpoint

post/v1/events/trigger/broadcast

Body parameters

  • namestring

    The trigger identifier associated for the template you wish to send. This identifier can be found on the template page.

  • payloadobject

    The payload object is used to pass additional custom information that could be used to render the template, or perform routing rules based on it. This data will also be available when fetching the notifications feed from the API to display certain parts of the UI.

  • overridesobject (optional)

    This could be used to override provider specific configurations

  • transactionIdstring (optional)

    A unique identifier for this transaction, we will generated a UUID if not provided.

Responses

post/v1/events/trigger/broadcast
1import { Novu } from '@novu/node';
2
3export const novu = new Novu('<REPLACE_WITH_API_KEY_FROM_ADMIN_PANEL>');
4
5await novu.broadcast('<REPLACE_WITH_EVENT_NAME_FROM_ADMIN_PANEL>',
6  {
7    payload: {
8      customVariables: 'Hello'
9    },
10    transactionId: 'transactionId',
11  }
12);
13
Response
1{
2    acknowledged: true,
3    status: "status",
4    transactionId: "transactionId"
5}

Cancel triggered event

Using a previously generated transactionId during the event trigger, will cancel any active or pending workflows. This is useful to cancel active digests, delays etc...

Endpoint

delete/v1/events/trigger/:transactionId

Path parameters

  • transactionIdstring

Responses

  • 200

delete/v1/events/trigger/:transactionId
1import fetch from 'node-fetch';
2
3const response = await fetch('https://api.novu.co/v1/events/trigger/:transactionId', {
4  method: 'DELETE',
5  
6});
7const data = await response.json();
8    

Get subscribers

Returns a list of subscribers, could paginated using the `page` query parameter

Endpoint

get/v1/subscribers

Query parameters

  • pagenumber (optional)

    The page to fetch, defaults to 0

Responses

get/v1/subscribers
1import { Novu } from '@novu/node';
2
3export const novu = new Novu('<REPLACE_WITH_API_KEY_FROM_ADMIN_PANEL>');
4
5await novu.subscribers.list(0);
6
Response
1{
2    page: 0,
3    totalCount: 0,
4    pageSize: 0,
5    data: ["data"]
6}

Create subscriber

Creates a subscriber entity, in the Novu platform. The subscriber will be later used to receive notifications, and access notification feeds. Communication credentials such as email, phone number, and 3 rd party credentials i.e slack tokens could be later associated to this entity.

Endpoint

post/v1/subscribers

Body parameters

  • subscriberIdstring

    The internal identifier you used to create this subscriber, usually correlates to the id the user in your systems

  • emailstring (optional)
  • firstNamestring (optional)
  • lastNamestring (optional)
  • phonestring (optional)
  • avatarstring (optional)

    An http url to the profile image of your subscriber

Responses

post/v1/subscribers
1import { Novu } from '@novu/node';
2
3export const novu = new Novu('<REPLACE_WITH_API_KEY_FROM_ADMIN_PANEL>');
4
5await novu.subscribers.identify(user.id, {
6  email: user.email,
7  firstName: user.firstName,
8  lastName: user.lastName,
9  phone: user.phone,
10  avatar: user.profile_avatar
11});
12
Response
1{
2    _id: "_id",
3    firstName: "firstName",
4    lastName: "lastName",
5    email: "email",
6    phone: "phone",
7    avatar: "avatar",
8    subscriberId: "subscriberId",
9    channels: ["channels"],
10    _organizationId: "_organizationId",
11    _environmentId: "_environmentId",
12    deleted: true,
13    createdAt: "createdAt",
14    updatedAt: "updatedAt",
15    __v: 0
16}

Get subscriber

Get subscriber by your internal id used to identify the subscriber

Endpoint

get/v1/subscribers/:subscriberId

Path parameters

  • subscriberIdstring

Responses

get/v1/subscribers/:subscriberId
1import fetch from 'node-fetch';
2
3const response = await fetch('https://api.novu.co/v1/subscribers/:subscriberId', {
4  method: 'GET',
5  
6});
7const data = await response.json();
8    
Response
1{
2    _id: "_id",
3    firstName: "firstName",
4    lastName: "lastName",
5    email: "email",
6    phone: "phone",
7    avatar: "avatar",
8    subscriberId: "subscriberId",
9    channels: ["channels"],
10    _organizationId: "_organizationId",
11    _environmentId: "_environmentId",
12    deleted: true,
13    createdAt: "createdAt",
14    updatedAt: "updatedAt",
15    __v: 0
16}

Update subscriber

Used to update the subscriber entity with new information

Endpoint

put/v1/subscribers/:subscriberId

Path parameters

  • subscriberIdstring

Body parameters

  • emailstring (optional)
  • firstNamestring (optional)
  • lastNamestring (optional)
  • phonestring (optional)
  • avatarstring (optional)

Responses

put/v1/subscribers/:subscriberId
1import fetch from 'node-fetch';
2
3const response = await fetch('https://api.novu.co/v1/subscribers/:subscriberId', {
4  method: 'PUT',
5  headers: {
6    'Content-Type': 'application/json',
7    'Authorization': 'ApiKey REPLACE_WITH_API_KEY',
8  },
9  body: JSON.stringify({
10    email: "email",
11    firstName: "firstName",
12    lastName: "lastName",
13    phone: "phone",
14    avatar: "avatar"
15  }),
16});
17const data = await response.json();
18    
Response
1{
2    _id: "_id",
3    firstName: "firstName",
4    lastName: "lastName",
5    email: "email",
6    phone: "phone",
7    avatar: "avatar",
8    subscriberId: "subscriberId",
9    channels: ["channels"],
10    _organizationId: "_organizationId",
11    _environmentId: "_environmentId",
12    deleted: true,
13    createdAt: "createdAt",
14    updatedAt: "updatedAt",
15    __v: 0
16}

Delete subscriber

Deletes a subscriber entity from the Novu platform

Endpoint

delete/v1/subscribers/:subscriberId

Path parameters

  • subscriberIdstring

Responses

delete/v1/subscribers/:subscriberId
1import fetch from 'node-fetch';
2
3const response = await fetch('https://api.novu.co/v1/subscribers/:subscriberId', {
4  method: 'DELETE',
5  
6});
7const data = await response.json();
8    
Response
1{
2    acknowledged: true,
3    status: "status"
4}

Update subscriber credentials

Subscriber credentials associated to the delivery methods such as slack and push tokens.

Endpoint

put/v1/subscribers/:subscriberId/credentials

Path parameters

  • subscriberIdstring

Body parameters

  • providerIdstring

    The provider identifier for the credentials

  • credentialsallOf

    Credentials payload for the specified provider

    Show parameters

Responses

put/v1/subscribers/:subscriberId/credentials
1import fetch from 'node-fetch';
2
3const response = await fetch('https://api.novu.co/v1/subscribers/:subscriberId/credentials', {
4  method: 'PUT',
5  headers: {
6    'Content-Type': 'application/json',
7    'Authorization': 'ApiKey REPLACE_WITH_API_KEY',
8  },
9  body: JSON.stringify({
10    providerId: "providerId",
11    credentials: "credentials"
12  }),
13});
14const data = await response.json();
15    
Response
1{
2    _id: "_id",
3    firstName: "firstName",
4    lastName: "lastName",
5    email: "email",
6    phone: "phone",
7    avatar: "avatar",
8    subscriberId: "subscriberId",
9    channels: ["channels"],
10    _organizationId: "_organizationId",
11    _environmentId: "_environmentId",
12    deleted: true,
13    createdAt: "createdAt",
14    updatedAt: "updatedAt",
15    __v: 0
16}

Get subscriber preferences

Endpoint

get/v1/subscribers/:subscriberId/preferences

Path parameters

  • subscriberIdstring

Responses

  • 200

get/v1/subscribers/:subscriberId/preferences
1import fetch from 'node-fetch';
2
3const response = await fetch('https://api.novu.co/v1/subscribers/:subscriberId/preferences', {
4  method: 'GET',
5  
6});
7const data = await response.json();
8    
Response
1{
2    template: template,
3    preference: preference
4}

Update subscriber preference

Endpoint

patch/v1/subscribers/:subscriberId/preferences/:templateId

Path parameters

  • subscriberIdstring
  • templateIdstring

Body parameters

  • channelallOf (optional)

    Channel with prefrence

    Show parameters
  • enabledboolean (optional)

Responses

patch/v1/subscribers/:subscriberId/preferences/:templateId
1import fetch from 'node-fetch';
2
3const response = await fetch('https://api.novu.co/v1/subscribers/:subscriberId/preferences/:templateId', {
4  method: 'PATCH',
5  headers: {
6    'Content-Type': 'application/json',
7    'Authorization': 'ApiKey REPLACE_WITH_API_KEY',
8  },
9  body: JSON.stringify({
10    channel: "channel",
11    enabled: true
12  }),
13});
14const data = await response.json();
15    
Response
1{
2    template: template,
3    preference: preference
4}

Get a notification feed for a particular subscriber

Endpoint

get/v1/subscribers/:subscriberId/notifications/feed

Path parameters

  • subscriberIdstring

Query parameters

  • pagenumber (optional)
  • feedIdentifierstring
  • seenboolean (optional)

Responses

  • 200

get/v1/subscribers/:subscriberId/notifications/feed
1import fetch from 'node-fetch';
2
3const response = await fetch('https://api.novu.co/v1/subscribers/:subscriberId/notifications/feed', {
4  method: 'GET',
5  
6});
7const data = await response.json();
8    
Response
1{
2    _id: "_id",
3    _templateId: "_templateId",
4    _environmentId: "_environmentId",
5    _messageTemplateId: "_messageTemplateId",
6    _organizationId: "_organizationId",
7    _notificationId: "_notificationId",
8    _subscriberId: "_subscriberId",
9    subscriber: subscriber,
10    template: template,
11    templateIdentifier: "templateIdentifier",
12    createdAt: "createdAt",
13    content: "content",
14    transactionId: "transactionId",
15    channel: "channel",
16    seen: true,
17    email: "email",
18    phone: "phone",
19    directWebhookUrl: "directWebhookUrl",
20    providerId: "providerId",
21    deviceTokens: ["deviceTokens"],
22    title: "title",
23    lastSeenDate: "lastSeenDate",
24    cta: cta,
25    _feedId: "_feedId",
26    status: "status",
27    errorId: "errorId",
28    errorText: "errorText",
29    payload: payload,
30    overrides: overrides,
31    subject: "subject"
32}

Get the unseen notification count for subscribers feed

Endpoint

get/v1/subscribers/:subscriberId/notifications/unseen

Path parameters

  • subscriberIdstring

Query parameters

  • seenboolean

Responses

get/v1/subscribers/:subscriberId/notifications/unseen
1import fetch from 'node-fetch';
2
3const response = await fetch('https://api.novu.co/v1/subscribers/:subscriberId/notifications/unseen', {
4  method: 'GET',
5  
6});
7const data = await response.json();
8    
Response
1{
2    count: 0
3}

Mark a subscriber feed message as seen

Endpoint

post/v1/subscribers/:subscriberId/messages/:messageId/seen

Path parameters

  • messageIdstring
  • subscriberIdstring

Responses

post/v1/subscribers/:subscriberId/messages/:messageId/seen
1import fetch from 'node-fetch';
2
3const response = await fetch('https://api.novu.co/v1/subscribers/:subscriberId/messages/:messageId/seen', {
4  method: 'POST',
5  
6});
7const data = await response.json();
8    
Response
1{
2    _id: "_id",
3    _templateId: "_templateId",
4    _environmentId: "_environmentId",
5    _messageTemplateId: "_messageTemplateId",
6    _organizationId: "_organizationId",
7    _notificationId: "_notificationId",
8    _subscriberId: "_subscriberId",
9    subscriber: subscriber,
10    template: template,
11    templateIdentifier: "templateIdentifier",
12    createdAt: "createdAt",
13    content: "content",
14    transactionId: "transactionId",
15    channel: "channel",
16    seen: true,
17    email: "email",
18    phone: "phone",
19    directWebhookUrl: "directWebhookUrl",
20    providerId: "providerId",
21    deviceTokens: ["deviceTokens"],
22    title: "title",
23    lastSeenDate: "lastSeenDate",
24    cta: cta,
25    _feedId: "_feedId",
26    status: "status",
27    errorId: "errorId",
28    errorText: "errorText",
29    payload: payload,
30    overrides: overrides,
31    subject: "subject"
32}

Mark message action as seen

Endpoint

post/v1/subscribers/:subscriberId/messages/:messageId/actions/:type

Path parameters

  • messageIdstring
  • typestring
  • subscriberIdstring

Responses

post/v1/subscribers/:subscriberId/messages/:messageId/actions/:type
1import fetch from 'node-fetch';
2
3const response = await fetch('https://api.novu.co/v1/subscribers/:subscriberId/messages/:messageId/actions/:type', {
4  method: 'POST',
5  
6});
7const data = await response.json();
8    
Response
1{
2    _id: "_id",
3    _templateId: "_templateId",
4    _environmentId: "_environmentId",
5    _messageTemplateId: "_messageTemplateId",
6    _organizationId: "_organizationId",
7    _notificationId: "_notificationId",
8    _subscriberId: "_subscriberId",
9    subscriber: subscriber,
10    template: template,
11    templateIdentifier: "templateIdentifier",
12    createdAt: "createdAt",
13    content: "content",
14    transactionId: "transactionId",
15    channel: "channel",
16    seen: true,
17    email: "email",
18    phone: "phone",
19    directWebhookUrl: "directWebhookUrl",
20    providerId: "providerId",
21    deviceTokens: ["deviceTokens"],
22    title: "title",
23    lastSeenDate: "lastSeenDate",
24    cta: cta,
25    _feedId: "_feedId",
26    status: "status",
27    errorId: "errorId",
28    errorText: "errorText",
29    payload: payload,
30    overrides: overrides,
31    subject: "subject"
32}

Get activity feed

Endpoint

get/v1/activity

Query parameters

  • channelsarray
  • templatesarray
  • emailsarray
  • searchstring
  • pagenumber (optional)

Responses

get/v1/activity
1import fetch from 'node-fetch';
2
3const response = await fetch('https://api.novu.co/v1/activity', {
4  method: 'GET',
5  
6});
7const data = await response.json();
8    
Response
1{
2    totalCount: 0,
3    data: ["data"],
4    pageSize: 0,
5    page: 0
6}

Get activity statistics

Endpoint

get/v1/activity/stats

Responses

get/v1/activity/stats
1import fetch from 'node-fetch';
2
3const response = await fetch('https://api.novu.co/v1/activity/stats', {
4  method: 'GET',
5  
6});
7const data = await response.json();
8    
Response
1{
2    weeklySent: 0,
3    monthlySent: 0,
4    yearlySent: 0
5}

Get activity graph statistics

Endpoint

get/v1/activity/graph/stats

Query parameters

  • daysnumber (optional)

Responses

  • 200

get/v1/activity/graph/stats
1import fetch from 'node-fetch';
2
3const response = await fetch('https://api.novu.co/v1/activity/graph/stats', {
4  method: 'GET',
5  
6});
7const data = await response.json();
8    
Response
1{
2    _id: "_id",
3    count: 0
4}

Get integrations

Endpoint

get/v1/integrations

Responses

  • 200

get/v1/integrations
1import fetch from 'node-fetch';
2
3const response = await fetch('https://api.novu.co/v1/integrations', {
4  method: 'GET',
5  
6});
7const data = await response.json();
8    
Response
1{
2    _id: "_id",
3    _environmentId: "_environmentId",
4    _organizationId: "_organizationId",
5    providerId: "providerId",
6    channel: "channel",
7    credentials: credentials,
8    active: true,
9    deleted: true,
10    deletedAt: "deletedAt",
11    deletedBy: "deletedBy"
12}

Create integration

Endpoint

post/v1/integrations

Body parameters

  • providerIdstring
  • channelstring
  • credentialsobject
    Show child parameters
  • activeboolean

Responses

post/v1/integrations
1import fetch from 'node-fetch';
2
3const response = await fetch('https://api.novu.co/v1/integrations', {
4  method: 'POST',
5  headers: {
6    'Content-Type': 'application/json',
7    'Authorization': 'ApiKey REPLACE_WITH_API_KEY',
8  },
9  body: JSON.stringify({
10    providerId: "providerId",
11    channel: "channel",
12    credentials: credentials,
13    active: true
14  }),
15});
16const data = await response.json();
17    
Response
1{
2    _id: "_id",
3    _environmentId: "_environmentId",
4    _organizationId: "_organizationId",
5    providerId: "providerId",
6    channel: "channel",
7    credentials: credentials,
8    active: true,
9    deleted: true,
10    deletedAt: "deletedAt",
11    deletedBy: "deletedBy"
12}

Get active integrations

Endpoint

get/v1/integrations/active

Responses

  • 200

get/v1/integrations/active
1import fetch from 'node-fetch';
2
3const response = await fetch('https://api.novu.co/v1/integrations/active', {
4  method: 'GET',
5  
6});
7const data = await response.json();
8    
Response
1{
2    _id: "_id",
3    _environmentId: "_environmentId",
4    _organizationId: "_organizationId",
5    providerId: "providerId",
6    channel: "channel",
7    credentials: credentials,
8    active: true