Notification preferences

Base URL: $CONSUMER_API

List communication preferences and consent

Logs

GET /notification-preferences

Pages the caller's notification preferences: consent status, preferred locale, per-event and per-channel switches, and quiet hours. Without a tenant (X-Tenant-ID or the utility_id query parameter) it lists the caller's preferences across all tenants; with one, it lists that tenant's preferences when the caller has an account or relationship there, and returns 403 otherwise.

Parameters

limitinteger · query · optional

Maximum resources to return (default 20, maximum 100).

afterstring · query · optional

Opaque cursor returned by the previous page.

Returns

200 Preferences for consumer accounts the principal may manage

curl -X GET "$CONSUMER_API/notification-preferences" \
  -H "Authorization: Bearer sk_test_..."
Response 200

Preferences for consumer accounts the principal may manage

Update communication preferences and consent

Logs

PATCH /notification-preferences

Creates or updates the caller's notification preference for one tenant (from utility_id in the body or X-Tenant-ID) or, without a tenant, the caller's general preference. consent_status is required (granted, withdrawn or required_notice_only); preferred_locale must be pt-MZ or en-US; quiet_hours_start and quiet_hours_end must be HH:MM and set together, and timezone needs quiet hours. Events and channels are merged into the stored settings, and an ambiguous or inaccessible tenant returns 400 or 403.

Body application/json

consent_statusstring · required

one of granted, withdrawn, required_notice_only

preferred_localestring · optional

one of pt-MZ, en-US

eventsobject · optional

Per-event delivery choices

channelsobject · optional

Per-channel delivery choices for email, push, and in_app

quiet_hours_startstring · optional
quiet_hours_endstring · optional
timezonestring · optional

IANA time zone required when quiet hours are set

Returns

200 Updated preference

Show attributes
idstring · required
recipient_typestring · required
recipient_idstring · required
consent_statusstring · required

one of granted, withdrawn, required_notice_only

preferred_localestring · optional

one of pt-MZ, en-US

eventsobject · optional
channelsobject · optional
quiet_hours_startstring · optional
quiet_hours_endstring · optional
timezonestring · optional

IANA time zone for the recipient's quiet hours

curl -X PATCH "$CONSUMER_API/notification-preferences" \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
  "consent_status": "granted",
  "preferred_locale": "pt-MZ",
  "events": {
    "key": true
  },
  "channels": {
    "key": true
  },
  "quiet_hours_start": "quiet hours start",
  "quiet_hours_end": "quiet hours end",
  "timezone": "Africa/Maputo"
}'
Response 200
{
  "id": "not_25JciZ96OjFmw7Nk8jrG0JbC4zp",
  "recipient_type": "recipient type",
  "recipient_id": "rec_2Fj2I5VC2F9MUXfa4XBWM39egPf",
  "consent_status": "granted",
  "preferred_locale": "pt-MZ",
  "events": {
    "key": true
  },
  "channels": {
    "key": true
  },
  "quiet_hours_start": "quiet hours start",
  "quiet_hours_end": "quiet hours end",
  "timezone": "Africa/Maputo"
}