Notification APIs

Why This Exists

This document defines API responsibilities for the Notification Domain. It does not define final OpenAPI specifications.

Owner

The owner is the Chief Product Officer and Enterprise Architect.

Business Value

Notification APIs give domains, user interfaces, and future channel connectors a controlled way to request, schedule, deliver, and track communication.

API Groups

API group	Responsibilities	Example endpoints
Notification Request API	Accept and validate notification requests.	POST /notifications/requests, GET /notifications/requests/{requestId}
Notification API	Retrieve notifications and update recipient-visible state.	GET /notifications, GET /notifications/{notificationId}
Recipient API	Resolve and inspect recipient targets.	POST /notifications/recipients/resolve
Preference API	Manage user and organization preferences.	GET /notifications/preferences, PUT /notifications/preferences/{preferenceId}
Template API	Manage notification templates and versions.	GET /notifications/templates, POST /notifications/templates
Schedule API	Create, update, and cancel schedules.	POST /notifications/schedules, DELETE /notifications/schedules/{scheduleId}
Reminder API	Manage deadline-relative and recurring reminders.	POST /notifications/reminders, GET /notifications/reminders
Delivery API	Inspect delivery attempts and provider status.	GET /notifications/{notificationId}/deliveries
Read Status API	Mark notifications read, acknowledged, or dismissed.	POST /notifications/{notificationId}/read, POST /notifications/{notificationId}/acknowledge
Escalation API	Retrieve and manage escalation workflow records.	GET /notifications/escalations, POST /notifications/escalations/{escalationId}/resolve
Communication History API	Retrieve auditable communication history.	GET /notifications/history
Channel Connector API	Integrate channel providers.	POST /notifications/channels/{channelId}/callbacks

API Design Rules

• Source domains should request notifications through commands or events, not direct database writes.
• Delivery provider callbacks must update Delivery through Notification-owned APIs.
• Read and acknowledgement endpoints must be recipient-aware.
• Template rendering must use approved template versions.
• Future Outlook, Gmail, and calendar integrations must be modeled as channel connectors.

Example Request Flow

sequenceDiagram
    participant Opportunity
    participant NotificationAPI as Notification API
    participant Notification
    participant Channel as Channel Provider

    Opportunity->>NotificationAPI: POST /notifications/requests
    NotificationAPI->>Notification: Validate request and resolve recipient
    Notification->>Notification: Apply preferences and schedule
    Notification->>Channel: Send email/WhatsApp/in-app
    Channel-->>NotificationAPI: Delivery callback
    NotificationAPI->>Notification: Record delivery status