Notification Preference Service - API Contract

GET /api/v1/notification-preferences/api/v1/notification-preferences

List all notification preference records across users

Public

Response Example

{
  "data": [
    {
      "id": "pref_01HPRF001",
      "user_id": "usr_mentor_7821",
      "scenario_type": "inactivity",
      "opted_out": false,
      "updated_at": "2026-03-10T11:00:00Z"
    },
    {
      "id": "pref_01HPRF002",
      "user_id": "usr_mentor_7821",
      "scenario_type": "certification_expiry",
      "opted_out": true,
      "updated_at": "2026-03-12T08:30:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 512
  }
}

GET /api/v1/notification-preferences/api/v1/notification-preferences/:id

Get a specific preference record by ID

Public

Response Example

{
  "id": "pref_01HPRF001",
  "user_id": "usr_mentor_7821",
  "scenario_type": "inactivity",
  "opted_out": false,
  "updated_at": "2026-03-10T11:00:00Z"
}

POST /api/v1/notification-preferences/api/v1/notification-preferences

Create a new notification preference record for a user

Public

Request Example

{
  "user_id": "usr_mentor_7821",
  "scenario_type": "milestone",
  "opted_out": false
}

Response Example

{
  "id": "pref_01HPRF099",
  "user_id": "usr_mentor_7821",
  "scenario_type": "milestone",
  "opted_out": false,
  "updated_at": "2026-03-26T09:40:00Z"
}

PUT /api/v1/notification-preferences/api/v1/notification-preferences/:id

Update a notification preference (opt in or out)

Public

Request Example

{
  "opted_out": true
}

Response Example

{
  "id": "pref_01HPRF001",
  "user_id": "usr_mentor_7821",
  "scenario_type": "inactivity",
  "opted_out": true,
  "updated_at": "2026-03-26T09:41:00Z"
}

DELETE /api/v1/notification-preferences/api/v1/notification-preferences/:id

Delete a notification preference record

Public

Response Example

{
  "success": true,
  "deleted_id": "pref_01HPRF001"
}

GET /api/v1/notification-preferences/api/v1/notification-preferences/users/:userId

Get all notification preferences for a specific user

Public

Response Example

{
  "user_id": "usr_mentor_7821",
  "preferences": [
    {
      "scenario_type": "inactivity",
      "opted_out": false,
      "updated_at": "2026-03-10T11:00:00Z"
    },
    {
      "scenario_type": "certification_expiry",
      "opted_out": true,
      "updated_at": "2026-03-12T08:30:00Z"
    },
    {
      "scenario_type": "milestone",
      "opted_out": false,
      "updated_at": "2026-03-15T10:00:00Z"
    }
  ]
}

GET /api/v1/notification-preferences/api/v1/notification-preferences/users/:userId/scenarios/:scenarioType/enabled

Check whether a specific scenario is enabled for a user

Public

Response Example

{
  "user_id": "usr_mentor_7821",
  "scenario_type": "inactivity",
  "is_enabled": true
}

PUT /api/v1/notification-preferences/api/v1/notification-preferences/users/:userId/scenarios/:scenarioType/opt-out

Set the opt-out status for a specific scenario for a user

Public

Request Example

{
  "opted_out": true
}

Response Example

{
  "user_id": "usr_mentor_7821",
  "scenario_type": "inactivity",
  "opted_out": true,
  "updated_at": "2026-03-26T09:45:00Z"
}

DELETE /api/v1/notification-preferences/api/v1/notification-preferences/users/:userId/reset

Reset all notification preferences for a user to defaults (all opted in)

Public

Response Example

{
  "user_id": "usr_mentor_7821",
  "reset": true,
  "preferences_deleted": 3,
  "reset_at": "2026-03-26T09:50:00Z"
}

Additional Metadata

{
  "contract_summary": {
    "total_contracts": 410,
    "total_endpoints": 2416,
    "api_styles_used": [
      "rest"
    ]
  },
  "generated_at": "2026-03-26T06:55:53.316Z"
}