Notification preferences

Base URL: $BUSINESS_API

The object

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

The object
{
  "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"
}

List utility communication preferences and consent policies

Logs

GET /notification-preferences

Returns the recorded communication preferences of the tenant's recipients: consent status, preferred locale, per-event and per-channel choices, quiet hours and time zone. The optional recipient_type and recipient_id query values narrow the list, and results use cursor pagination. Requires the notifications:read permission.

Parameters

limitinteger · query · optional

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

afterstring · query · optional

Opaque cursor returned by the previous page.

Returns

200 Utility-scoped, channel-neutral preferences

Show attributes
dataarray of NotificationPreference · optional
Show child 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

has_moreboolean · optional
next_cursorstring · optional

Permissions notifications:read · Roles: admin, customer_service, owner

curl -X GET "$BUSINESS_API/notification-preferences" \
  -H "Authorization: Bearer sk_test_..."
Response 200
{
  "data": [
    {
      "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"
    }
  ],
  "has_more": true,
  "next_cursor": "next cursor"
}

Update business notification preference

Logs

PATCH /notification-preferences

Record a recipient's consent, channel and event choices, locale, or quiet hours

Requires notifications:write. The change is written to the audit log.

Body application/json

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

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

Errors 400 · 403

Permissions notifications:write · Roles: admin, customer_service, owner

curl -X PATCH "$BUSINESS_API/notification-preferences" \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
  "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"
}'
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"
}