API routes (Click a route to expand it, click here to expand/collapse all)
9. Notification service
DELETE/mgmt/deliveries/{id} ⎘Authentication required
Cancels a not-yet-sent channel delivery
Parameter Location Type Requirements Optional Default value Description
id URI-Path string No Unique identifier of the delivery record to cancel
Response HTTP Type Description
Success 200 array Acknowledgement from the notification service
NsApiNotFoundException 404 The requested resource was not found in the notification service.
NsApiRequestException 502 The notification service is unavailable or rejected the request unexpectedly.
MissingRequiredParameterException 400 The request is missing a required input parameter. See details for involved parameter.
InvalidParameterException 400 The request has an invalid argument. See details for involved parameter and invalidation.
AuthenticationFailedException 401 Authentication failed. Re-authenticate and retry. See error details for details.
UnauthorizedException 403 Authorization for requested method rejected. See error details for details.
Authentication required:
Yes
Authentication scheme:
JWTAuth
Required flags:
('notify:write') ⎘
GET/mgmt/contacts/{contactId}/notifications/history ⎘Authentication required
Returns the full in-app notification history for a single contact
Parameter Location Type Requirements Optional Default value Description
contactId URI-Path string No External contact identifier, assigned by KATE
Response HTTP Type Description
Success 200 array ns-api list envelope of the contact's notification feed items
NsApiRequestException 502 The notification service is unavailable or rejected the request unexpectedly.
MissingRequiredParameterException 400 The request is missing a required input parameter. See details for involved parameter.
InvalidParameterException 400 The request has an invalid argument. See details for involved parameter and invalidation.
AuthenticationFailedException 401 Authentication failed. Re-authenticate and retry. See error details for details.
UnauthorizedException 403 Authorization for requested method rejected. See error details for details.
Authentication required:
Yes
Authentication scheme:
JWTAuth
Required flags:
('notify:read') ⎘
GET/mgmt/customers ⎘Authentication required
Lists customers synced into the notification service
Parameter Location Type Requirements Optional Default value Description
status URI-Query string
enum: [ "active", "inactive" ]
 Yes null Filter by active or inactive
Response HTTP Type Description
Success 200 array ns-api list envelope of customers
NsApiRequestException 502 The notification service is unavailable or rejected the request unexpectedly.
MissingRequiredParameterException 400 The request is missing a required input parameter. See details for involved parameter.
InvalidParameterException 400 The request has an invalid argument. See details for involved parameter and invalidation.
AuthenticationFailedException 401 Authentication failed. Re-authenticate and retry. See error details for details.
UnauthorizedException 403 Authorization for requested method rejected. See error details for details.
Authentication required:
Yes
Authentication scheme:
JWTAuth
Required flags:
('notify:read') ⎘
GET/mgmt/customers/{customerId} ⎘Authentication required
Returns a single customer from the notification service
Parameter Location Type Requirements Optional Default value Description
customerId URI-Path string
pattern: ^[a-z][a-z0-9\-]{2,13}[a-z0-9]$
 No External customer identifier, assigned by KATE
Response HTTP Type Description
Success 200 array The customer
NsApiNotFoundException 404 The requested resource was not found in the notification service.
NsApiRequestException 502 The notification service is unavailable or rejected the request unexpectedly.
MissingRequiredParameterException 400 The request is missing a required input parameter. See details for involved parameter.
InvalidParameterException 400 The request has an invalid argument. See details for involved parameter and invalidation.
AuthenticationFailedException 401 Authentication failed. Re-authenticate and retry. See error details for details.
UnauthorizedException 403 Authorization for requested method rejected. See error details for details.
Authentication required:
Yes
Authentication scheme:
JWTAuth
Required flags:
('notify:read') ⎘
GET/mgmt/customers/{customerId}/contacts ⎘Authentication required
Lists contacts for a customer in the notification service
Parameter Location Type Requirements Optional Default value Description
customerId URI-Path string No External customer identifier
status URI-Query string
enum: [ "active", "inactive" ]
 Yes null Filter by active or inactive
Response HTTP Type Description
Success 200 array ns-api list envelope of contacts
NsApiRequestException 502 The notification service is unavailable or rejected the request unexpectedly.
MissingRequiredParameterException 400 The request is missing a required input parameter. See details for involved parameter.
InvalidParameterException 400 The request has an invalid argument. See details for involved parameter and invalidation.
AuthenticationFailedException 401 Authentication failed. Re-authenticate and retry. See error details for details.
UnauthorizedException 403 Authorization for requested method rejected. See error details for details.
Authentication required:
Yes
Authentication scheme:
JWTAuth
Required flags:
('notify:read') ⎘
GET/mgmt/customers/{customerId}/contacts/{userId} ⎘Authentication required
Returns a single contact from the notification service
Parameter Location Type Requirements Optional Default value Description
customerId URI-Path string No External customer identifier
userId URI-Path string No External contact identifier, assigned by KATE
Response HTTP Type Description
Success 200 array The contact
NsApiNotFoundException 404 The requested resource was not found in the notification service.
NsApiRequestException 502 The notification service is unavailable or rejected the request unexpectedly.
MissingRequiredParameterException 400 The request is missing a required input parameter. See details for involved parameter.
InvalidParameterException 400 The request has an invalid argument. See details for involved parameter and invalidation.
AuthenticationFailedException 401 Authentication failed. Re-authenticate and retry. See error details for details.
UnauthorizedException 403 Authorization for requested method rejected. See error details for details.
Authentication required:
Yes
Authentication scheme:
JWTAuth
Required flags:
('notify:read') ⎘
GET/mgmt/customers/{customerId}/departments ⎘Authentication required
Lists departments for a customer in the notification service
Parameter Location Type Requirements Optional Default value Description
customerId URI-Path string
pattern: ^[a-z][a-z0-9\-]{2,13}[a-z0-9]$
 No External customer identifier
status URI-Query string
enum: [ "active", "inactive" ]
 Yes null Filter by active or inactive
Response HTTP Type Description
Success 200 array ns-api list envelope of departments
NsApiRequestException 502 The notification service is unavailable or rejected the request unexpectedly.
MissingRequiredParameterException 400 The request is missing a required input parameter. See details for involved parameter.
InvalidParameterException 400 The request has an invalid argument. See details for involved parameter and invalidation.
AuthenticationFailedException 401 Authentication failed. Re-authenticate and retry. See error details for details.
UnauthorizedException 403 Authorization for requested method rejected. See error details for details.
Authentication required:
Yes
Authentication scheme:
JWTAuth
Required flags:
('notify:read') ⎘
GET/mgmt/customers/{customerId}/departments/{departmentId} ⎘Authentication required
Returns a single department from the notification service
Parameter Location Type Requirements Optional Default value Description
customerId URI-Path string
pattern: ^[a-z][a-z0-9\-]{2,13}[a-z0-9]$
 No External customer identifier
departmentId URI-Path string No External department identifier, globally unique across all customers
Response HTTP Type Description
Success 200 array The department
NsApiNotFoundException 404 The requested resource was not found in the notification service.
NsApiRequestException 502 The notification service is unavailable or rejected the request unexpectedly.
MissingRequiredParameterException 400 The request is missing a required input parameter. See details for involved parameter.
InvalidParameterException 400 The request has an invalid argument. See details for involved parameter and invalidation.
AuthenticationFailedException 401 Authentication failed. Re-authenticate and retry. See error details for details.
UnauthorizedException 403 Authorization for requested method rejected. See error details for details.
Authentication required:
Yes
Authentication scheme:
JWTAuth
Required flags:
('notify:read') ⎘
GET/mgmt/customers/{customerId}/departments/{departmentId}/contacts ⎘Authentication required
Lists contacts for a specific department in the notification service
Parameter Location Type Requirements Optional Default value Description
customerId URI-Path string No External customer identifier
departmentId URI-Path string No External department identifier
status URI-Query string
enum: [ "active", "inactive" ]
 Yes null Filter by active or inactive
Response HTTP Type Description
Success 200 array ns-api list envelope of contacts
NsApiRequestException 502 The notification service is unavailable or rejected the request unexpectedly.
MissingRequiredParameterException 400 The request is missing a required input parameter. See details for involved parameter.
InvalidParameterException 400 The request has an invalid argument. See details for involved parameter and invalidation.
AuthenticationFailedException 401 Authentication failed. Re-authenticate and retry. See error details for details.
UnauthorizedException 403 Authorization for requested method rejected. See error details for details.
Authentication required:
Yes
Authentication scheme:
JWTAuth
Required flags:
('notify:read') ⎘
GET/mgmt/deliveries/{id} ⎘Authentication required
Returns a single channel delivery record
Parameter Location Type Requirements Optional Default value Description
id URI-Path string No Unique identifier of the delivery record
Response HTTP Type Description
Success 200 array The delivery record
NsApiNotFoundException 404 The requested resource was not found in the notification service.
NsApiRequestException 502 The notification service is unavailable or rejected the request unexpectedly.
MissingRequiredParameterException 400 The request is missing a required input parameter. See details for involved parameter.
InvalidParameterException 400 The request has an invalid argument. See details for involved parameter and invalidation.
AuthenticationFailedException 401 Authentication failed. Re-authenticate and retry. See error details for details.
UnauthorizedException 403 Authorization for requested method rejected. See error details for details.
Authentication required:
Yes
Authentication scheme:
JWTAuth
Required flags:
('notify:read') ⎘
GET/mgmt/notifications ⎘Authentication required
Lists notification requests, optionally filtered
Parameter Location Type Requirements Optional Default value Description
customerIds URI-Query string[] Yes null Filter by recipient customer — matches requests targeting ANY of these customers
notificationType URI-Query string Yes null Filter by notification type name
requestStatus URI-Query string
enum: [ "received", "processing", "completed", "partial", "failed" ]
 Yes null Filter by request status
createdFrom URI-Query string
format: date
 Yes null Inclusive window start date (YYYY-MM-DD); ns-api defaults to 90 days ago
createdTo URI-Query string
format: date
 Yes null Inclusive window end date (YYYY-MM-DD); ns-api defaults to today
offset URI-Query int
min: 0
 Yes null Number of records to skip (page offset)
limit URI-Query int
min: 1
max: 100
 Yes null Max results per page
Response HTTP Type Description
Success 200 array ns-api list envelope of notification requests
NsApiRequestException 502 The notification service is unavailable or rejected the request unexpectedly.
MissingRequiredParameterException 400 The request is missing a required input parameter. See details for involved parameter.
InvalidParameterException 400 The request has an invalid argument. See details for involved parameter and invalidation.
AuthenticationFailedException 401 Authentication failed. Re-authenticate and retry. See error details for details.
UnauthorizedException 403 Authorization for requested method rejected. See error details for details.
Authentication required:
Yes
Authentication scheme:
JWTAuth
Required flags:
('notify:read') ⎘
GET/mgmt/notifications/{id} ⎘Authentication required
Returns a single notification request
Parameter Location Type Requirements Optional Default value Description
id URI-Path string No Unique identifier of the notification request
Response HTTP Type Description
Success 200 array The notification request, including delivery summary and failure reasons
NsApiNotFoundException 404 The requested resource was not found in the notification service.
NsApiRequestException 502 The notification service is unavailable or rejected the request unexpectedly.
MissingRequiredParameterException 400 The request is missing a required input parameter. See details for involved parameter.
InvalidParameterException 400 The request has an invalid argument. See details for involved parameter and invalidation.
AuthenticationFailedException 401 Authentication failed. Re-authenticate and retry. See error details for details.
UnauthorizedException 403 Authorization for requested method rejected. See error details for details.
Authentication required:
Yes
Authentication scheme:
JWTAuth
Required flags:
('notify:read') ⎘
GET/mgmt/notifications/{id}/deliveries ⎘Authentication required
Lists the individual channel deliveries for a notification request
Parameter Location Type Requirements Optional Default value Description
id URI-Path string No Unique identifier of the notification request
channel URI-Query string
enum: [ "email", "in_app" ]
 Yes null Filter by channel
deliveryStatus URI-Query string
enum: [ "queued", "delivered", "read", "cancelled", "failed", "backlog" ]
 Yes null Filter by delivery status
limit URI-Query int
min: 1
max: 100
 Yes null Max results per page
cursor URI-Query string Yes null Pagination cursor from a previous response
Response HTTP Type Description
Success 200 array ns-api list envelope of delivery records
NsApiNotFoundException 404 The requested resource was not found in the notification service.
NsApiRequestException 502 The notification service is unavailable or rejected the request unexpectedly.
MissingRequiredParameterException 400 The request is missing a required input parameter. See details for involved parameter.
InvalidParameterException 400 The request has an invalid argument. See details for involved parameter and invalidation.
AuthenticationFailedException 401 Authentication failed. Re-authenticate and retry. See error details for details.
UnauthorizedException 403 Authorization for requested method rejected. See error details for details.
Authentication required:
Yes
Authentication scheme:
JWTAuth
Required flags:
('notify:read') ⎘
PATCH/mgmt/deliveries/{id}/read ⎘Authentication required
Marks a delivery as read on behalf of its recipient
Parameter Location Type Requirements Optional Default value Description
id URI-Path string No Unique identifier of the delivery record to mark read
Response HTTP Type Description
Success 200 array The updated delivery status and read timestamp
NsApiNotFoundException 404 The requested resource was not found in the notification service.
NsApiRequestException 502 The notification service is unavailable or rejected the request unexpectedly.
MissingRequiredParameterException 400 The request is missing a required input parameter. See details for involved parameter.
InvalidParameterException 400 The request has an invalid argument. See details for involved parameter and invalidation.
AuthenticationFailedException 401 Authentication failed. Re-authenticate and retry. See error details for details.
UnauthorizedException 403 Authorization for requested method rejected. See error details for details.
Authentication required:
Yes
Authentication scheme:
JWTAuth
Required flags:
('notify:write') ⎘
POST/mgmt/customers/batch ⎘Authentication required
Creates or updates multiple customers in the notification service in one call
Parameter Location Type Requirements Optional Default value Description
items POST-body string
format: json
 No JSON-encoded string of an array of customers to upsert, each with customerId, name and optional status (e.g. '[{"customerId":"acme","name":"Acme"}]')
Response HTTP Type Description
Success 200 array Counts of created/updated/failed items, plus per-item error messages
NsApiValidationException 422 The notification service rejected the request as invalid.
NsApiRequestException 502 The notification service is unavailable or rejected the request unexpectedly.
MissingRequiredParameterException 400 The request is missing a required input parameter. See details for involved parameter.
InvalidParameterException 400 The request has an invalid argument. See details for involved parameter and invalidation.
AuthenticationFailedException 401 Authentication failed. Re-authenticate and retry. See error details for details.
UnauthorizedException 403 Authorization for requested method rejected. See error details for details.
Authentication required:
Yes
Authentication scheme:
JWTAuth
Required flags:
('notify:write') ⎘
POST/mgmt/customers/{customerId}/contacts/batch ⎘Authentication required
Creates or updates multiple contacts for a customer in one call
Parameter Location Type Requirements Optional Default value Description
customerId URI-Path string No External customer identifier
items POST-body string
format: json
 No JSON-encoded string of an array of contacts to upsert, each with userId, departmentIds, email, displayName and optional fields
Response HTTP Type Description
Success 200 array Counts of created/updated/failed items, plus per-item error messages
NsApiValidationException 422 The notification service rejected the request as invalid.
NsApiRequestException 502 The notification service is unavailable or rejected the request unexpectedly.
MissingRequiredParameterException 400 The request is missing a required input parameter. See details for involved parameter.
InvalidParameterException 400 The request has an invalid argument. See details for involved parameter and invalidation.
AuthenticationFailedException 401 Authentication failed. Re-authenticate and retry. See error details for details.
UnauthorizedException 403 Authorization for requested method rejected. See error details for details.
Authentication required:
Yes
Authentication scheme:
JWTAuth
Required flags:
('notify:write') ⎘
POST/mgmt/customers/{customerId}/departments/batch ⎘Authentication required
Creates or updates multiple departments for a customer in one call
Parameter Location Type Requirements Optional Default value Description
customerId URI-Path string
pattern: ^[a-z][a-z0-9\-]{2,13}[a-z0-9]$
 No External customer identifier
items POST-body string
format: json
 No JSON-encoded string of an array of departments to upsert, each with departmentId, name and optional status (e.g. '[{"departmentId":"sales","name":"Sales"}]')
Response HTTP Type Description
Success 200 array Counts of created/updated/failed items, plus per-item error messages
NsApiValidationException 422 The notification service rejected the request as invalid.
NsApiRequestException 502 The notification service is unavailable or rejected the request unexpectedly.
MissingRequiredParameterException 400 The request is missing a required input parameter. See details for involved parameter.
InvalidParameterException 400 The request has an invalid argument. See details for involved parameter and invalidation.
AuthenticationFailedException 401 Authentication failed. Re-authenticate and retry. See error details for details.
UnauthorizedException 403 Authorization for requested method rejected. See error details for details.
Authentication required:
Yes
Authentication scheme:
JWTAuth
Required flags:
('notify:write') ⎘
POST/mgmt/notifications ⎘
Creates a notification request to be sent to one or more recipients
Parameter Location Type Requirements Optional Default value Description
notificationType POST-body string No Unique identifier of the notification type, e.g. 'document_signing_request'
channelsRequested POST-body string[]
enum: [ "email", "in_app" ]
 No Channels to attempt delivery on
payload POST-body string
format: json
 No JSON-encoded string of the notification content object, addressable in templates as {{ field }}
contactIds POST-body string[] Yes null Recipient contact ids
departmentIds POST-body string[] Yes null Recipient department ids
customerIds POST-body string[] Yes null Recipient customer ids
testTemplateId POST-body string Yes null When set, pins template selection to this id and schedules delivery immediately (template test)
Response HTTP Type Description
Success 200 array The created notification request
NsApiValidationException 422 The notification service rejected the request as invalid.
NsApiRequestException 502 The notification service is unavailable or rejected the request unexpectedly.
PathNotWritableException 500 Path is not writable.
MissingRequiredParameterException 400 The request is missing a required input parameter. See details for involved parameter.
InvalidParameterException 400 The request has an invalid argument. See details for involved parameter and invalidation.
AuthenticationFailedException 401 Authentication failed. Re-authenticate and retry. See error details for details.
UnauthorizedException 403 Authorization for requested method rejected. See error details for details.
Authentication required:
No
Authentication scheme:
JWTAuth
Required flags:
None ⎘
POST/mgmt/notifications/{id}/process ⎘Authentication required
Triggers (re)processing of a previously created notification request
Parameter Location Type Requirements Optional Default value Description
id URI-Path string No Unique identifier of the notification request to process
Response HTTP Type Description
Success 200 array Acknowledgement from the notification service
NsApiNotFoundException 404 The requested resource was not found in the notification service.
NsApiRequestException 502 The notification service is unavailable or rejected the request unexpectedly.
MissingRequiredParameterException 400 The request is missing a required input parameter. See details for involved parameter.
InvalidParameterException 400 The request has an invalid argument. See details for involved parameter and invalidation.
AuthenticationFailedException 401 Authentication failed. Re-authenticate and retry. See error details for details.
UnauthorizedException 403 Authorization for requested method rejected. See error details for details.
Authentication required:
Yes
Authentication scheme:
JWTAuth
Required flags:
('notify:write') ⎘
PUT/mgmt/customers/{customerId} ⎘Authentication required
Creates or updates a customer in the notification service
Parameter Location Type Requirements Optional Default value Description
customerId URI-Path string
pattern: ^[a-z][a-z0-9\-]{2,13}[a-z0-9]$
 No External customer identifier, assigned by KATE
name URI-Query string No Human-readable customer name
status URI-Query string
enum: [ "active", "inactive" ]
 Yes null Whether this customer is active
Response HTTP Type Description
Success 200 array The created or updated customer
NsApiValidationException 422 The notification service rejected the request as invalid.
NsApiRequestException 502 The notification service is unavailable or rejected the request unexpectedly.
MissingRequiredParameterException 400 The request is missing a required input parameter. See details for involved parameter.
InvalidParameterException 400 The request has an invalid argument. See details for involved parameter and invalidation.
AuthenticationFailedException 401 Authentication failed. Re-authenticate and retry. See error details for details.
UnauthorizedException 403 Authorization for requested method rejected. See error details for details.
Authentication required:
Yes
Authentication scheme:
JWTAuth
Required flags:
('notify:write') ⎘
PUT/mgmt/customers/{customerId}/contacts/{userId} ⎘Authentication required
Creates or updates a contact in the notification service
Parameter Location Type Requirements Optional Default value Description
customerId URI-Path string No External customer identifier
userId URI-Path string No External contact identifier, assigned by KATE
departmentIds URI-Query string[] No Departments this contact belongs to
email URI-Query string No Email address for email channel delivery
displayName URI-Query string No Human-readable name for template rendering
language URI-Query string
enum: [ "en", "nl", "fr" ]
 Yes null Preferred content language
status URI-Query string
enum: [ "active", "inactive" ]
 Yes null Whether this contact is active
settings URI-Query string
format: json
 Yes null JSON-encoded string of user-scope notification preference settings; omitted leaves any existing preference untouched
Response HTTP Type Description
Success 200 array The created or updated contact
NsApiValidationException 422 The notification service rejected the request as invalid.
NsApiRequestException 502 The notification service is unavailable or rejected the request unexpectedly.
MissingRequiredParameterException 400 The request is missing a required input parameter. See details for involved parameter.
InvalidParameterException 400 The request has an invalid argument. See details for involved parameter and invalidation.
AuthenticationFailedException 401 Authentication failed. Re-authenticate and retry. See error details for details.
UnauthorizedException 403 Authorization for requested method rejected. See error details for details.
Authentication required:
Yes
Authentication scheme:
JWTAuth
Required flags:
('notify:write') ⎘
PUT/mgmt/customers/{customerId}/departments/{departmentId} ⎘Authentication required
Creates or updates a department in the notification service
Parameter Location Type Requirements Optional Default value Description
customerId URI-Path string
pattern: ^[a-z][a-z0-9\-]{2,13}[a-z0-9]$
 No External customer identifier
departmentId URI-Path string No External department identifier, globally unique across all customers
name URI-Query string No Human-readable department name
status URI-Query string
enum: [ "active", "inactive" ]
 Yes null Whether this department is active
Response HTTP Type Description
Success 200 array The created or updated department
NsApiValidationException 422 The notification service rejected the request as invalid.
NsApiRequestException 502 The notification service is unavailable or rejected the request unexpectedly.
MissingRequiredParameterException 400 The request is missing a required input parameter. See details for involved parameter.
InvalidParameterException 400 The request has an invalid argument. See details for involved parameter and invalidation.
AuthenticationFailedException 401 Authentication failed. Re-authenticate and retry. See error details for details.
UnauthorizedException 403 Authorization for requested method rejected. See error details for details.
Authentication required:
Yes
Authentication scheme:
JWTAuth
Required flags:
('notify:write') ⎘
Default APIs
GET/ ⎘
Provides the API-specification. Only enabled if API exposure is enabled.
Parameter Location Type Requirements Optional Default value Description
format URI-Query string
enum: [ "KateAPI", "InternalAPIMap", "OpenAPI", "Swagger" ]
 Yes "KateAPI" Documentation format. We support KateAPI documentation, Swagger/OpenAPI documentation and raw output of the internal API-map cache.
openApiVersion URI-Query int
enum: [ 2, 3 ]
 Yes 2 Version 3 is crappy with request bodies, so we prefer version 2 (which only sucks regarding Response definitions; hence we prefer KateAPI documentation).
Response HTTP Type Description
Success 200 object The API-documentation.
MissingRequiredParameterException 400 The request is missing a required input parameter. See details for involved parameter.
InvalidParameterException 400 The request has an invalid argument. See details for involved parameter and invalidation.
AuthenticationFailedException 401 Authentication failed. Re-authenticate and retry. See error details for details.
UnauthorizedException 403 Authorization for requested method rejected. See error details for details.
Authentication required:
No
Authentication schemes (Click an authentication scheme to expand it)
JWTAuth
Result wrappers (Click a result-wrapper to expand it)
Success
Error