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
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
| description |
Bearer JWT token in Authorization header. |
| realm |
kate.v2 |
| supportedIssuers |
[
"auth.api.katedev.com",
"legacy-adapter.api.katedev.com",
"auth.api.wouter.katedevelopment.com",
"legacy-adapter.api.wouter.katedevelopment.com"
] |
| verificationKeyIdentifier |
[
"iss"
] |
| flagsIdentifier |
perm |
| detailsIdentifiers |
{
"idUser": "sub",
"username": "name",
"idCustomer": "idc",
"idDepartment": "idd",
"businessNumber": "bn"
} |
Result wrappers (Click a result-wrapper to expand it)
Success
{
result: < mixed, success result, type specified in API route documentation >,
error: null,
messages: {
"type": "error|warning|success|info|debug",
"namespace": string,
"namedArguments": < optional object that has information referenced in the translation linked to the namespace>
}[],
apiVersion: < string, current serving API version in format ^[0-9]+\.[0-9]+\.[0-9]+(\-[A-Za-z0-9]+)?$ >
}
Error
{
result: null,
error: {
code: < string, response error code as described in API route documentation. Use this code in language translation files. >,
description: < string, optional, technical description of error. Only intended for developers for debug, not suitable for end-users >,
details: < object|array|string, contains detailed data about error, if applicable >
},
messages: {
"type": "error|warning|success|info|debug",
"namespace": string,
"namedArguments": < optional object that has information referenced in the translation linked to the namespace>
}[],
apiVersion: < string, current serving API version in format ^[0-9]+\.[0-9]+\.[0-9]+(\-[A-Za-z0-9]+)?$ >
}
{
"error": {
"description": "Fatal error: error in exception handling while reporting exception.",
"message": "Another service invoked by this service using intra-service communication resulted in an error. See details for involved request and resulting error. HTTP status code is dynamically inherited, but defaults to 500.",
"details": {
"serviceName": "error-reporting",
"serviceURI": "https:\/\/error-reporting.api.wouter.katedevelopment.com\/register",
"error": "error-missing"
},
"file": "\/app\/Commons\/KateIntraService\/Request.php",
"line": 284,
"trace": [
{
"file": "\/app\/Commons\/KateAPI\/ErrorReporting\/ErrorReporting.php",
"line": 247,
"function": "execute",
"class": "KATEv2\\Commons\\KateIntraService\\Request",
"type": "->",
"args": []
},
{
"file": "\/app\/Commons\/KateAPI\/KateAPIRunner.php",
"line": 271,
"function": "reportException",
"class": "KATEv2\\Commons\\KateAPI\\ErrorReporting\\ErrorReporting",
"type": "::",
"args": [
{},
{}
]
},
{
"function": "onKateErrorHandlerError",
"class": "KATEv2\\Commons\\KateAPI\\KateAPIRunner",
"type": "::",
"args": [
{
"fatal": null,
"preceding-non-fatal": [
{
"errLevel": 8192,
"level": 2,
"type": "DEPRECATED:PHP",
"msg": "KATEv2\\Commons\\Plugins\\SecureStaticBinary\\SSBinService::getUploadURL(): Implicitly marking parameter $callbackURL as nullable is deprecated, the explicit nullable type must be used instead",
"file": "\/Commons\/Plugins\/SecureStaticBinary\/SSBinService.php",
"line": 117,
"trace": [
"01: KATEv2\\Commons\\KateAPI\\KateAPIRunner->__construct('main', '[OBJECT]')\n \\-> Line 0032 in \/Notify\/bootstrapper.php",
"02: KATEv2\\Commons\\KateCache\\Cache->__construct('[OBJECT]')\n \\-> Line 0057 in \/Commons\/KateAPI\/KateAPIRunner.php",
"03: KATEv2\\Commons\\KateCache\\Cache::getDefaultCommonsCacheModes('[OBJECT]')\n \\-> Line 0087 in \/Commons\/KateCache\/Cache.php",
"04: KATEv2\\PSR4Autoloader->loadClass('KATEv2\\Commons\\Plugi...')\n \\-> Line 0355 in \/Commons\/KateCache\/Cache.php",
"05: require_once('\/Commons\/KateErr...')\n \\-> Line 0058 in \/PSR4Autoloader.php",
"06: Error raised\n \\-> Line 0058 in \/PSR4Autoloader.php\n(Skipped 2 internal calls)\n"
],
"vars": [
8192,
"KATEv2\\Commons\\Plugins\\SecureStaticBinary\\SSBinService::getUploadURL(): Implicitly marking parameter $callbackURL as nullable is deprecated, the explicit nullable type must be used instead",
"\/app\/Commons\/Plugins\/SecureStaticBinary\/SSBinService.php",
117
],
"code": {
"112": " * @throws \\KATEv2\\Commons\\Plugins\\SecureStaticBinary\\Exceptions\\SSBinMalformedFileURLException",
"113": " * @throws \\KATEv2\\Commons\\Plugins\\SecureStaticBinary\\Exceptions\\SSBinNotFoundException",
"114": " * @throws \\KATEv2\\Commons\\Plugins\\SecureStaticBinary\\Exceptions\\SSBinRevokedAudienceException",
"115": " * @throws \\KATEv2\\Commons\\Plugins\\SecureStaticBinary\\Exceptions\\SSBinUnregisteredSigningServiceException",
"116": " *\/",
"117": " public function getUploadURL(string $fileName, string $audience = 'kate', string | int $validFor = '+2 years', string $callbackURL = null): string {",
"118": " if ($this->customer === null) throw new ImplementationException(__METHOD__.': Customer must be defined; pass it to constructor.');",
"119": " if ($this->department === null) throw new ImplementationException(__METHOD__.': Department must be defined; pass it to constructor.');",
"120": " if (strlen($this->customer) > 15) throw new ImplementationException('Customer-name too long, given:\"'.$this->customer.'\".');",
"121": " if (strlen($this->department) > 15) throw new ImplementationException('Department-name too long, given:\"'.$this->department.'\".');",
"122": " if (strlen($audience) > 7) throw new ImplementationException('Audience-name too long, given:\"'.$audience.'\".');"
},
"mark": [
"fileName",
"audience",
"validFor",
"callbackURL"
]
},
{
"errLevel": 8192,
"level": 2,
"type": "DEPRECATED:PHP",
"msg": "KATEv2\\Commons\\Plugins\\SecureStaticBinary\\SSBinService::getUploadURLForPublicFile(): Implicitly marking parameter $callbackURL as nullable is deprecated, the explicit nullable type must be used instead",
"file": "\/Commons\/Plugins\/SecureStaticBinary\/SSBinService.php",
"line": 164,
"trace": [
"01: KATEv2\\Commons\\KateAPI\\KateAPIRunner->__construct('main', '[OBJECT]')\n \\-> Line 0032 in \/Notify\/bootstrapper.php",
"02: KATEv2\\Commons\\KateCache\\Cache->__construct('[OBJECT]')\n \\-> Line 0057 in \/Commons\/KateAPI\/KateAPIRunner.php",
"03: KATEv2\\Commons\\KateCache\\Cache::getDefaultCommonsCacheModes('[OBJECT]')\n \\-> Line 0087 in \/Commons\/KateCache\/Cache.php",
"04: KATEv2\\PSR4Autoloader->loadClass('KATEv2\\Commons\\Plugi...')\n \\-> Line 0355 in \/Commons\/KateCache\/Cache.php",
"05: require_once('\/Commons\/KateErr...')\n \\-> Line 0058 in \/PSR4Autoloader.php",
"06: Error raised\n \\-> Line 0058 in \/PSR4Autoloader.php\n(Skipped 2 internal calls)\n"
],
"vars": [
8192,
"KATEv2\\Commons\\Plugins\\SecureStaticBinary\\SSBinService::getUploadURLForPublicFile(): Implicitly marking parameter $callbackURL as nullable is deprecated, the explicit nullable type must be used instead",
"\/app\/Commons\/Plugins\/SecureStaticBinary\/SSBinService.php",
164
],
"code": {
"159": " elseif ($errorType === 'SSBinNotFoundException') throw new Exceptions\\SSBinNotFoundException();",
"160": " throw $e; \/\/ Should not happen.",
"161": " }",
"162": " }",
"163": "",
"164": " public function getUploadURLForPublicFile(string $filename, string $callbackURL = null): string {",
"165": " return $this->getUploadURL($filename, 'public', 0, $callbackURL);",
"166": " }",
"167": "",
"168": " \/**",
"169": " * @param string $uploadURL Allocated upload link from ->getUploadURL()"
},
"mark": [
"filename",
"callbackURL"
]
}
]
}
]
},
{
"file": "\/app\/Commons\/KateErrorHandler\/ErrorHandler.php",
"line": 338,
"function": "call_user_func",
"args": [
[
"KATEv2\\Commons\\KateAPI\\KateAPIRunner",
"onKateErrorHandlerError"
],
{
"fatal": null,
"preceding-non-fatal": [
{
"errLevel": 8192,
"level": 2,
"type": "DEPRECATED:PHP",
"msg": "KATEv2\\Commons\\Plugins\\SecureStaticBinary\\SSBinService::getUploadURL(): Implicitly marking parameter $callbackURL as nullable is deprecated, the explicit nullable type must be used instead",
"file": "\/Commons\/Plugins\/SecureStaticBinary\/SSBinService.php",
"line": 117,
"trace": [
"01: KATEv2\\Commons\\KateAPI\\KateAPIRunner->__construct('main', '[OBJECT]')\n \\-> Line 0032 in \/Notify\/bootstrapper.php",
"02: KATEv2\\Commons\\KateCache\\Cache->__construct('[OBJECT]')\n \\-> Line 0057 in \/Commons\/KateAPI\/KateAPIRunner.php",
"03: KATEv2\\Commons\\KateCache\\Cache::getDefaultCommonsCacheModes('[OBJECT]')\n \\-> Line 0087 in \/Commons\/KateCache\/Cache.php",
"04: KATEv2\\PSR4Autoloader->loadClass('KATEv2\\Commons\\Plugi...')\n \\-> Line 0355 in \/Commons\/KateCache\/Cache.php",
"05: require_once('\/Commons\/KateErr...')\n \\-> Line 0058 in \/PSR4Autoloader.php",
"06: Error raised\n \\-> Line 0058 in \/PSR4Autoloader.php\n(Skipped 2 internal calls)\n"
],
"vars": [
8192,
"KATEv2\\Commons\\Plugins\\SecureStaticBinary\\SSBinService::getUploadURL(): Implicitly marking parameter $callbackURL as nullable is deprecated, the explicit nullable type must be used instead",
"\/app\/Commons\/Plugins\/SecureStaticBinary\/SSBinService.php",
117
],
"code": {
"112": " * @throws \\KATEv2\\Commons\\Plugins\\SecureStaticBinary\\Exceptions\\SSBinMalformedFileURLException",
"113": " * @throws \\KATEv2\\Commons\\Plugins\\SecureStaticBinary\\Exceptions\\SSBinNotFoundException",
"114": " * @throws \\KATEv2\\Commons\\Plugins\\SecureStaticBinary\\Exceptions\\SSBinRevokedAudienceException",
"115": " * @throws \\KATEv2\\Commons\\Plugins\\SecureStaticBinary\\Exceptions\\SSBinUnregisteredSigningServiceException",
"116": " *\/",
"117": " public function getUploadURL(string $fileName, string $audience = 'kate', string | int $validFor = '+2 years', string $callbackURL = null): string {",
"118": " if ($this->customer === null) throw new ImplementationException(__METHOD__.': Customer must be defined; pass it to constructor.');",
"119": " if ($this->department === null) throw new ImplementationException(__METHOD__.': Department must be defined; pass it to constructor.');",
"120": " if (strlen($this->customer) > 15) throw new ImplementationException('Customer-name too long, given:\"'.$this->customer.'\".');",
"121": " if (strlen($this->department) > 15) throw new ImplementationException('Department-name too long, given:\"'.$this->department.'\".');",
"122": " if (strlen($audience) > 7) throw new ImplementationException('Audience-name too long, given:\"'.$audience.'\".');"
},
"mark": [
"fileName",
"audience",
"validFor",
"callbackURL"
]
},
{
"errLevel": 8192,
"level": 2,
"type": "DEPRECATED:PHP",
"msg": "KATEv2\\Commons\\Plugins\\SecureStaticBinary\\SSBinService::getUploadURLForPublicFile(): Implicitly marking parameter $callbackURL as nullable is deprecated, the explicit nullable type must be used instead",
"file": "\/Commons\/Plugins\/SecureStaticBinary\/SSBinService.php",
"line": 164,
"trace": [
"01: KATEv2\\Commons\\KateAPI\\KateAPIRunner->__construct('main', '[OBJECT]')\n \\-> Line 0032 in \/Notify\/bootstrapper.php",
"02: KATEv2\\Commons\\KateCache\\Cache->__construct('[OBJECT]')\n \\-> Line 0057 in \/Commons\/KateAPI\/KateAPIRunner.php",
"03: KATEv2\\Commons\\KateCache\\Cache::getDefaultCommonsCacheModes('[OBJECT]')\n \\-> Line 0087 in \/Commons\/KateCache\/Cache.php",
"04: KATEv2\\PSR4Autoloader->loadClass('KATEv2\\Commons\\Plugi...')\n \\-> Line 0355 in \/Commons\/KateCache\/Cache.php",
"05: require_once('\/Commons\/KateErr...')\n \\-> Line 0058 in \/PSR4Autoloader.php",
"06: Error raised\n \\-> Line 0058 in \/PSR4Autoloader.php\n(Skipped 2 internal calls)\n"
],
"vars": [
8192,
"KATEv2\\Commons\\Plugins\\SecureStaticBinary\\SSBinService::getUploadURLForPublicFile(): Implicitly marking parameter $callbackURL as nullable is deprecated, the explicit nullable type must be used instead",
"\/app\/Commons\/Plugins\/SecureStaticBinary\/SSBinService.php",
164
],
"code": {
"159": " elseif ($errorType === 'SSBinNotFoundException') throw new Exceptions\\SSBinNotFoundException();",
"160": " throw $e; \/\/ Should not happen.",
"161": " }",
"162": " }",
"163": "",
"164": " public function getUploadURLForPublicFile(string $filename, string $callbackURL = null): string {",
"165": " return $this->getUploadURL($filename, 'public', 0, $callbackURL);",
"166": " }",
"167": "",
"168": " \/**",
"169": " * @param string $uploadURL Allocated upload link from ->getUploadURL()"
},
"mark": [
"filename",
"callbackURL"
]
}
]
}
]
},
{
"file": "\/app\/Commons\/KateErrorHandler\/ErrorHandler.php",
"line": 232,
"function": "presentErrors",
"class": "KATEv2\\Commons\\KateErrorHandler\\ErrorHandler",
"type": "->",
"args": []
},
{
"function": "onShutdown",
"class": "KATEv2\\Commons\\KateErrorHandler\\ErrorHandler",
"type": "->",
"args": []
}
],
"code": 0
}
}