Administration

Subscriber records, workflow definitions, provider credentials, and delivery status — the operator-facing surface. Everything here is under /api/v1/notifications/manage/ and needs a secret key (sk_*) or an admin JWT.

Subscriber Management

A subscriber is the notification system's record of a person: their contact details, their channel registrations, and their preferences. It is created for you the first time a user registers a push device, so most integrations never call create-subscriber directly.

Create a Subscriber

Use this to seed a subscriber ahead of their first login — for an email-only recipient, or when importing existing users.

POST /api/v1/notifications/manage/create-subscriber

{
  "subscriberId": "user-1",
  "firstName": "Jane",
  "lastName": "Doe",
  "email": "jane@example.com",
  "phone": "+1234567890",
  "locale": "en-US"
}

Response:

{
  "subscriberId": "user-1",
  "novuSubscriberId": "6512f0a1c3d4e5f60718293a"
}

subscriberId is your own user ID — the same value you pass as userId when sending. novuSubscriberId is the provider's internal ID; you rarely need it.

Read the Caller's Subscriber

get-subscriber and delete-subscriber act on the authenticated caller and take an empty request body. There is no way to address another user's record through them.

POST /api/v1/notifications/manage/get-subscriber

{}

Response:

{
  "subscriberId": "user-1",
  "data": {
    "firstName": "Jane",
    "lastName": "Doe",
    "email": "jane@example.com",
    "locale": "en-US",
    "timezone": "Europe/London"
  },
  "channels": [
    {"channel": "CHANNEL_PUSH", "registered": true, "credentialCount": 2},
    {"channel": "CHANNEL_IN_APP", "registered": true, "credentialCount": 1}
  ],
  "globalPreferences": {
    "enabled": true,
    "channels": {"inApp": true, "push": true, "email": false}
  },
  "workflowPreferences": [
    {
      "workflowId": "weekly-summary",
      "workflowName": "Weekly Summary",
      "critical": false,
      "channels": {"inApp": true, "push": false}
    }
  ],
  "createdAt": "2026-01-14T09:12:00Z",
  "updatedAt": "2026-08-02T17:40:11Z"
}

This is the one call that returns profile, channel registrations and preferences together — useful for rendering a whole settings screen without three round trips.

Update Profile Data

POST /api/v1/notifications/manage/update-subscriber-data

{
  "data": {
    "email": "jane.updated@example.com",
    "locale": "en-GB",
    "customData": {"plan": "pro"}
  }
}

Response:

{
  "data": {
    "firstName": "Jane",
    "lastName": "Doe",
    "email": "jane.updated@example.com",
    "locale": "en-GB",
    "customData": {"plan": "pro"}
  },
  "updatedAt": "2026-08-14T11:02:44Z"
}

customData is free-form JSON available to workflow templates, so it is the place to put anything you want to render into a message.

Delete the Caller's Subscriber

Permanently removes the caller's subscriber profile and everything attached to it — device tokens, preferences, inbox history. It does not delete the user elsewhere on the platform.

POST /api/v1/notifications/manage/delete-subscriber

{}

Response:

{
  "acknowledged": true,
  "status": "done"
}

Deleting a subscriber that does not exist is an idempotent success, not a 404: you get acknowledged: true with status: "not_found". status is otherwise Novu's own acknowledgement string, defaulting to "done" — branch on acknowledged, not on the text.

List Subscribers

POST /api/v1/notifications/manage/list-subscribers

{
  "page": 1,
  "pageSize": 50
}

Response:

{
  "subscribers": [
    {
      "subscriberId": "user-1",
      "email": "jane@example.com",
      "firstName": "Jane",
      "lastName": "Doe",
      "isOnline": false,
      "lastOnlineAt": "2026-08-13T21:05:00Z"
    }
  ],
  "totalCount": 1,
  "hasMore": false
}

Workflows

Workflows are managed as opaque Novu JSON objects — the API passes definitions through without interpreting them, so the shape of workflow is Novu's, not ours.

Create a Workflow

POST /api/v1/notifications/manage/create-workflow

{
  "workflow": {
    "name": "Welcome Notification",
    "description": "Sent when a user completes onboarding",
    "__source": "editor",
    "steps": [
      {
        "name": "In-App Step",
        "type": "in_app",
        "controlValues": {
          "body": "Welcome to your health coaching journey!"
        }
      }
    ]
  }
}

Response: {"workflow": {...}} — the created definition as Novu stored it, including the workflowId you will trigger with.

Update a Workflow

POST /api/v1/notifications/manage/update-workflow

{
  "workflowId": "welcome-notification",
  "workflow": {
    "name": "Welcome Notification",
    "steps": [
      {
        "name": "In-App Step",
        "type": "in_app",
        "controlValues": {"body": "Welcome aboard!"}
      }
    ]
  }
}

The workflow object replaces the stored definition — send the whole thing, not a patch.

Get, List and Delete Workflows

get-workflow and delete-workflow accept either workflowId or triggerIdentifier:

POST /api/v1/notifications/manage/get-workflow

{
  "triggerIdentifier": "welcome-notification"
}

Response: {"workflow": {...}}.

POST /api/v1/notifications/manage/list-workflows

{
  "page": 1,
  "pageSize": 50
}

Response:

{
  "workflows": [{"...": "opaque Novu workflow JSON"}],
  "totalCount": 12,
  "hasMore": false
}

This is the call to make before any send — it is how you discover valid workflowId values.

POST /api/v1/notifications/manage/delete-workflow

{
  "workflowId": "welcome-notification"
}

Response:

{
  "workflowId": "welcome-notification"
}

Deleting a workflow does not cancel notifications already in flight — cancel those by transaction ID with manage/cancel.

Provider Configuration

Configure external delivery providers (FCM, APNS, SendGrid, etc.).

POST /api/v1/notifications/manage/configure-provider

{
  "provider": "PROVIDER_TYPE_FCM",
  "credentials": {
    "serviceAccount": "{...}"
  },
  "active": true
}

Response:

{
  "integrationId": "6512f0a1c3d4e5f60718293b",
  "active": true
}

Upsert Behavior

configure-provider uses upsert semantics: if an active integration already exists for the specified provider type, it updates the existing integration in place (preserving its ID and subscriber linkages). If no active integration exists, a new one is created.

This prevents duplicate integrations and ensures existing device registrations continue to work after credential updates. If multiple active integrations exist for the same provider type, the call returns 409 Conflict — resolve the duplicates manually via the Novu dashboard.

POST /api/v1/notifications/manage/get-providers

{}

Response:

{
  "providers": [
    {
      "provider": "PROVIDER_TYPE_FCM",
      "integrationId": "6512f0a1c3d4e5f60718293b",
      "active": true
    }
  ]
}

Delivery Status

One Notification

Returns the raw Novu activity record for a single transaction — per-channel attempts, provider responses, and timestamps. This is the first place to look when someone says a notification never arrived.

POST /api/v1/notifications/manage/get-delivery-status

{
  "transactionId": "txn_abc123"
}

Response: {"activity": {...}} with raw Novu data.

Activity Log

Query delivery history with channel and time filtering.

POST /api/v1/notifications/manage/get-notification-activity

{
  "page": 1,
  "pageSize": 50,
  "channels": ["in_app", "push"],
  "from": "2026-03-01T00:00:00Z",
  "to": "2026-03-23T23:59:59Z"
}

Response:

{
  "entries": [{"...": "raw Novu activity entry"}],
  "hasMore": true
}

channels filters on provider channel names (in_app, push, email, sms, chat) — lowercase, not the CHANNEL_* enum used elsewhere. pageSize caps at 100.