Notification Preference

Overview

The Notification Preferences API suite provides full control over how and why consumers receive communications from the platform. It manages a two-tier preference model: Internal Triggers (determining if an alert is generated based on business events) and External Delivery (determining how that alert is sent via Email, SMS, or Push).

By leveraging these endpoints, developers can ensure that automated messaging is both relevant to the user and compliant with their delivery choices.

Key Features

• Two-Tier Logic: Separate management for event triggers (Internal) and delivery channels (External).
• Granular Control: Opt-in or out of specific content categories (for example, Claims, Enrollment, Marketing).
• Identity Integration: All preferences are tied to a unique person_id from the Benefits Platform Identity System.
• Master Switches: Global toggles for Email, SMS, and Push notification channels.

Scopes & Permissions

Endpoint Summary

External Notification Preferences

GET /notifications/preferences | PUT /notifications/preferences

• Purpose: Manages delivery channels (Email, SMS, Push) and high-level category opt-ins.
• Key Fields: email_enabled, sms_enabled, push_enabled, and the categories array.

Internal Notification Preferences

GET /notifications/internal/preferences | PUT /notifications/internal/preferences

• Purpose: Manages the core event triggers that initiate a notification.
• Key Fields: category_id (for example, ENROLLMENT_SUCCESS) and the enabled boolean.

Core Concepts

The Hierarchy of Choice

The system follows a logical gatekeeping flow to prevent unwanted noise:

• The Internal Gate: Is the event trigger enabled? (for example, Is “Reimbursement Issued” turned on?)
• The External Gate: Is the delivery channel enabled? (for example, Does the user allow SMS?)
• The Category Gate: Has the user opted into this specific content type externally?

Feature Enablement

These endpoints may return a 405 Method Not Allowed if the Notification Preference module has not been enabled for the specific partner or administrator domain.

Error Handling

Idempotency & Safety

• Idempotency: Both update operations are PUTrequests, making them idempotent. Sending the same configuration multiple times results in the same final state.
• Traceability: All requests support the X-Request-Id header to allow for end-to-end audit logging of consumer preference changes.