Channel Operations and Reference Data

Overview

This flow shows how a SYSTEM admin loads notification reference data, inspects existing channels, and moves a channel through its lifecycle. The current docs describe email-channel management, but the same pattern applies to future channel categories.

Prerequisites

1. Authorization: Bearer <accessToken>
2. X-PORTAL-ACCESS-CODE: <system-portal-code>
3. institution business ID for channel creation
4. Turnstile token support if the gateway requires it

Shared Headers

X-PORTAL-ACCESS-CODE: <system-portal-code>
Authorization: Bearer <accessToken>
X-Turnstile-Token: <turnstile-token>
Content-Type: application/json

Step-by-Step Flow

1. Query channel types

API endpoint: POST /web/v1/notification-channel-types/query Load enabled types such as EMAIL before rendering the configuration form.

curl -X POST 'https://api.example.com/web/v1/notification-channel-types/query?page=0&size=20' \
  -H 'X-PORTAL-ACCESS-CODE: <system-portal-code>' \
  -H 'Authorization: Bearer <accessToken>' \
  -H 'X-Turnstile-Token: <turnstile-token>' \
  -H 'Content-Type: application/json' \
  -d '{"enabledOnly":true}'

{"code":"2000","message":"SUCCESS","data":{"content":[{"bizId":"ct_abc123","typeCode":"EMAIL","typeStatus":"ENABLED"}]}}

2. Query existing channels

API endpoint: POST /web/v1/notification-channels/query Use this before creation to surface reuse candidates and current channel state.

curl -X POST 'https://api.example.com/web/v1/notification-channels/query?page=0&size=20' \
  -H 'X-PORTAL-ACCESS-CODE: <system-portal-code>' \
  -H 'Authorization: Bearer <accessToken>' \
  -H 'X-Turnstile-Token: <turnstile-token>' \
  -H 'Content-Type: application/json' \
  -d '{"institutionBizId":"inst_abc123","channelCategory":"EMAIL","activeOnly":false}'

{"code":"2000","message":"SUCCESS","data":{"content":[{"bizId":"ch_abc123","channelName":"Main Email","channelCategory":"EMAIL","channelStatus":"ACTIVE"}]}}

3. Create a new channel

API endpoint: POST /web/v1/notification-channels/command/create New channels start in PENDING and should not be treated as live yet.

curl -X POST 'https://api.example.com/web/v1/notification-channels/command/create' \
  -H 'X-PORTAL-ACCESS-CODE: <system-portal-code>' \
  -H 'Authorization: Bearer <accessToken>' \
  -H 'X-Turnstile-Token: <turnstile-token>' \
  -H 'Content-Type: application/json' \
  -d '{"institutionBizId":"inst_abc123","channelName":"Primary SMTP","channelHost":"smtp.example.com","channelCategory":"EMAIL","emailConfig":{"smtpHost":"smtp.example.com","smtpPort":587,"senderEmail":"noreply@example.com","senderName":"Acme Corp","username":"noreply@example.com","password":"S3cret!","useSsl":true,"useStartTls":false}}'

{"code":"2000","message":"SUCCESS","data":{"bizId":"ch_abc123","channelName":"Primary SMTP","channelCategory":"EMAIL","channelStatus":"PENDING"}}

4. Update the channel

API endpoint: POST /web/v1/notification-channels/command/update Updates are partial and modify only the provided fields.

curl -X POST 'https://api.example.com/web/v1/notification-channels/command/update' \
  -H 'X-PORTAL-ACCESS-CODE: <system-portal-code>' \
  -H 'Authorization: Bearer <accessToken>' \
  -H 'X-Turnstile-Token: <turnstile-token>' \
  -H 'Content-Type: application/json' \
  -d '{"bizId":"ch_abc123","channelRemark":"Production channel","channelHost":"smtp-us.example.com"}'

{"code":"2000","message":"SUCCESS","data":{"bizId":"ch_abc123","channelHost":"smtp-us.example.com","channelStatus":"PENDING"}}

5. Activate or deactivate the channel

API endpoints: POST /web/v1/notification-channels/command/activate, POST /web/v1/notification-channels/command/deactivate

curl -X POST 'https://api.example.com/web/v1/notification-channels/command/activate' \
  -H 'X-PORTAL-ACCESS-CODE: <system-portal-code>' \
  -H 'Authorization: Bearer <accessToken>' \
  -H 'X-Turnstile-Token: <turnstile-token>' \
  -H 'Content-Type: application/json' \
  -d '{"bizId":"ch_abc123"}'

{"code":"2000","message":"SUCCESS","data":{"bizId":"ch_abc123","channelStatus":"ACTIVE"}}

Channel Status Lifecycle

1. PENDING after creation
2. ACTIVE after successful activation
3. INACTIVE when intentionally disabled
4. ERROR when configuration becomes unusable

Decision Points

1. create a new channel only if query results show no reusable active channel
2. keep a channel in PENDING if credential review or testing is still ongoing
3. deactivate instead of deleting when the change should be reversible
4. use the channel-type query to hide unsupported forms from the UI

Error Handling

1. 4030 usually means Turnstile validation failed at the gateway
2. 4040 on update or activate usually means the bizId is stale
3. validation errors usually come from incomplete SMTP config
4. passwords are always masked in responses, so do not expect them back

Next Steps

1. Notifications Guide
2. Account Guide
3. Workspace Guide