Skip to main content

Administration

Subscriber records, workflow definitions, provider credentials, promotion between environments, and delivery status — the operator-facing surface.

Subscriber Management​

Create Subscriber​

POST /api/v1/notifications/manage/create-subscriber
{
  "subscriberId": "user-1",
  "firstName": "Jane",
  "lastName": "Doe",
  "email": "jane@example.com",
  "phone": "+1234567890",
  "locale": "en-US"
}

Get / Update / Delete Subscriber​

Get and delete use empty request bodies (user derived from auth headers):

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

Update subscriber profile data:

POST /api/v1/notifications/update-subscriber-data
{
  "data": {
    "email": "jane.updated@example.com",
    "locale": "en-GB"
  }
}

List Subscribers​

POST /api/v1/notifications/manage/list-subscribers
{
  "page": 1,
  "pageSize": 50
}

Workflow Management​

Workflows are managed as opaque Novu JSON objects. The API passes workflow definitions through without interpretation.

Create 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: Returns the created workflow object from Novu.

Update / Get / List / Delete Workflow​

POST /api/v1/notifications/manage/update-workflow
POST /api/v1/notifications/manage/get-workflow
POST /api/v1/notifications/manage/list-workflows
POST /api/v1/notifications/manage/delete-workflow

All return opaque Novu workflow JSON.

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
}
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

Activity & Delivery Status​

Get Delivery Status​

Returns the raw Novu activity data for a notification.

POST /api/v1/notifications/manage/get-delivery-status
{
  "transactionId": "txn_abc123"
}

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

Get Notification Activity​

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: Returns {"entries": [...], "hasMore": true} with raw Novu activity entries.