Skip to content

REST Notification API specification

This section describes the API that the Token Server expects when notifications are send by the Token Server to an external service which handles the actual notification delivery to an end-user.

The notification interface defines two types of notifications:

  • Email
  • SMS

The Token Server will make an HTTP POST request to the notification endpoint specified via the Docker Compose environment variables for notifications. Along with the API endpoint you also need to specify a number of other properties, such as the credentials that are used in the API request by the Token Server.

Email API

The request that the Token Server will make to trigger an Email notification will look as follows:

POST /notify/email HTTP/1.1
Host: trustbuilder.example.com
Content-Type: application/json;charset=UTF-8

{
    "from_address": "[email protected]",
    "recipients": [ "<John Doe>[email protected]", "[email protected]" ],
    "subject" : "Consent given",
    "plain_text":"message text",
    "html_text":"<html><body>html text</body></html>"
}

SMS API

The request that the Token Server will make to trigger an SMS notification will look as follows:

POST /notify/sms HTTP/1.1
Host: trustbuilder.example.com
Content-Type: application/json;charset=UTF-8

{
    "recipient": "+3112345768",
    "message":"message text"
}

Responses

The Token Server expects the following responses from the Notification service.

Success response

HTTP/1.1 204 No Content
Cache-Control: no-store
Pragma: no-cache

Error response

HTTP/1.1 400 Bad Request
Content-Type: application/json;charset=UTF-8
Cache-Control: no-store
Pragma: no-cache

{
    "error" : "reason"
}