Sign in

v4

OpenAPI 3.0.0MIT2026-07-311554531.6 MB
Subscribers

Create a subscriber

Create a subscriber with the subscriber attributes. subscriberId is a required field, rest other fields are optional, if the subscriber already exists, it will be updated

post/v2/subscribers

Query parameters

failIfExistsboolean

If true, the request will fail if a subscriber with the same subscriberId already exists

Request body

firstNamestring nullable

First name of the subscriber

lastNamestring nullable

Last name of the subscriber

emailstring nullable

Email address of the subscriber

phonestring nullable

Phone number of the subscriber

avatarstring nullable

Avatar URL or identifier

localestring nullable

Locale of the subscriber

timezonestring nullable

Timezone of the subscriber

dataobject nullable

Additional custom data associated with the subscriber

subscriberIdstring required

Unique identifier of the subscriber

Example request

{
  "firstName": "John",
  "lastName": "Doe",
  "email": "john.doe@example.com",
  "phone": "+1234567890",
  "avatar": "https://example.com/avatar.jpg",
  "locale": "en-US",
  "timezone": "America/New_York"
}

Response

Created

_idstring

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.

firstNamestring nullable

The first name of the subscriber.

lastNamestring nullable

The last name of the subscriber.

emailstring nullable

The email address of the subscriber.

phonestring nullable

The phone number of the subscriber.

avatarstring nullable

The URL of the subscriber's avatar image.

localestring nullable

The locale setting of the subscriber, indicating their preferred language or region.

topicsstring[]

An array of topics that the subscriber is subscribed to.

isOnlineboolean nullable

Indicates whether the subscriber is currently online.

lastOnlineAtstring nullable

The timestamp indicating when the subscriber was last online, in ISO 8601 format.

__vnumber

The version of the subscriber document.

dataobject nullable

Additional custom data for the subscriber

timezonestring nullable

Timezone of the subscriber

subscriberIdstring required

The identifier used to create this subscriber, which typically corresponds to the user ID in your system.

_organizationIdstring required

The unique identifier of the organization to which the subscriber belongs.

_environmentIdstring required

The unique identifier of the environment associated with this subscriber.

deletedboolean required

Indicates whether the subscriber has been deleted.

createdAtstring required

The timestamp indicating when the subscriber was created, in ISO 8601 format.

updatedAtstring required

The timestamp indicating when the subscriber was last updated, in ISO 8601 format.

Example response

{
  "channels": [
    {
      "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"
      }
    }
  ]
}