To start to use this component, please install the "GOV UK Notify Service" application in your factory.
It's provided an integration to send text messages, emails (with or without a file), letters and precompiled letters. Additionally, you can verify the status of a single message or multiple messages, as well as get the details of a single template or multiple templates.
The authentication/authorization of each request is made by converting the API key of your service account into JSON Web Token (JWT) of JWT the forge component. The outcome is then added to the HTTP request "Authorization" header.
JSON Web Tokens (JWT) are encoded using a secret key with the format of 3d844edf-8d35-48ac-975b-e847b4f122b0.
That secret key forms a part of your API key, which follows the format {key_name}-{iss-uuid}-{secret-key-uuid}.
{key_name}-{iss-uuid}-{secret-key-uuid}
For example, if your API key is my_test_key-26785a09-ab16-4eb0-8407-a37497a57506-3d844edf-8d35-48ac-975b-e847b4f122b0:
my_test_key-26785a09-ab16-4eb0-8407-a37497a57506-3d844edf-8d35-48ac-975b-e847b4f122b0
my_test_key
26785a09-ab16-4eb0-8407-a37497a57506
3d844edf-8d35-48ac-975b-e847b4f122b0
iat (issued at) is the current time in UTC in epoch seconds. The token expires within 30 seconds of the current time.
iat
Refer to the JSON Web Tokens website for more information on encoding your authorisation header.
When you have an encoded and signed token, add that token to a header as follows:
"Authorization": "Bearer encoded_jwt_token".
In the "OnBeforeRequest" of GovUKNotifyAPIv2 consumed REST API is called a server action wrapper "OnBeforeRequest_GovUKNotifyAPI".This wrapper manipulates the HTTP Request before it is sent, and one of the actions taken into consideration is a wrapper "GenerateTokenFromHTTPHeaderAPIKey". The main goal of this wrapper is to gather the API Key from the header request and with it to generate a JWT bearer token to be appended and defined as a value of the "Authorization" HTTP request header.
The "GenerateTokenFromHTTPHeaderAPIKey" server action receives as an input parameter a list of all HTTP Request Headers and returns the encoded token. From the Headers parameter will be extracted the API Key that was originally sent. For this extraction, we are using a private server action (GetAPIKeyFromHeaders) that filters the Headers list by a specific header name.
After obtaining the API Key, it is used as an input parameter for a new wrapper (GenerateJWT) that will be used to generate the final encoded token.To keep the token's lifetime short, no value is defined in the "Expires" parameter, meaning the token must be used within 30 seconds after its generation.
Inside the "GenerateJWT" wrapper, a local action "SplitAPIKey" is invoked which, after validating whether the API Key matches the intended format, returns: Name, Service Id and Secret Key (as indicated in the "Authorization Header" section).
For the proper generation of the JWT token, it is used the Service Id as the Issuer, HS256 as the Algorithm, and the Secret Key as the Key and KeyId. If the encoded token is generated successfully, its value is returned. To know a little bit more about how to use the service below, please click here.
Finally, after the encoded token has been generated, it is added to the "Authorization" header of the HTTP request, such as the "Content-Type" header as "application/json".
An Integration with the "postSMS" method of GovUKNotifyAPIv2 is done through the service action "Send_SMS" implemented in the GovUKNotify_IS module.
This service action includes all the flow needed to validate the required fields APIKey and TemplateID, through a "CheckRequest" server action wrapper, and checks if the MobileNumber is empty.
Additionally, the "Request" input parameter is converted to the required structure of the "postSMS" API method, and the integration response is converted to a local "Response" structure.
Below are presented the required and optional request fields for this integration and also its definitions:
To get an API key, sign in to GOV.UK Notify and go to the API integration page.Your API key follows the format {key_name}-{iss-uuid}-{secret-key-uuid} that is validated using the regular expression ^\w+-([\da-fA-F]{8}-([\da-fA-F]{4}-){3}[\da-fA-F]{12}-?){2}$.The value of the API Key is then encoded to be sent in the "Authorization" header of the request.To see more details about the Authorization Header, please click here.
^\w+-([\da-fA-F]{8}-([\da-fA-F]{4}-){3}[\da-fA-F]{12}-?){2}$
The SMS template ID is mapped with the argument template_id from the REST API.Your template ID follows a format that is validated using the regular expression ^[\da-fA-F]{8}-([\da-fA-F]{4}-){3}[\da-fA-F]{12}$.
^[\da-fA-F]{8}-([\da-fA-F]{4}-){3}[\da-fA-F]{12}$
To find the template ID:
The phone number of the recipient of the text message is mapped with the argument phone_number from the REST API. This can be a UK or international number.
A unique identifier of the sender of the text message notification that is mapped with the argument sms_sender_id from the REST API.
To find the text message sender:
An identifier you can create if necessary that is mapped with the argument reference from the REST API. This reference identifies a single notification or a batch of notifications. It must not contain any personal information such as name or postal address.
You can leave out this argument if you do not have a reference.
This is being mapped with the argument personalisation from the REST API.If a template has placeholder fields for personalised information such as name or reference number, you must provide their values in a dictionary with key-value pairs.
You can leave out this argument if a template does not have any placeholder fields for personalised information.
To use this integration you can create a server action wrapper, i.e. "SendSMSWrapper", that will call the service action "Send_SMS" from the GovUKNotify_IS module, passing the information required, and optional if needed, avoiding misbehaviour of this integration.
If your application needs to present the response on the screen, please check the following example or use this test page:
An integration with the "postEmail" method of GovUKNotifyAPIv2 is done through the service action "Send_Email" implemented in the GovUKNotify_IS module.
This service action includes all the flow needed to validate the required fields APIKey and TemplateID, through a "CheckRequest" server action wrapper, and checks if the EmailAddress is empty.
Additionally, the "Request" input parameter is converted to the required structure of the "postEmail" API method, and the integration response is converted to a local "Response" structure.
The email template ID is mapped with the argument template_id from the REST API.Your template ID follows a format that is validated using the regular expression ^[\da-fA-F]{8}-([\da-fA-F]{4}-){3}[\da-fA-F]{12}$.
The email address of the recipient is mapped with the argument email_address from the REST API. This can be a UK or international number.
This is an email address specified by you to receive replies from your users that is mapped with the argument email_reply_to_id from the REST API. You must add at least one reply-to email address before your service can go live.
To add a reply-to email address:
To use this integration you can create a server action wrapper, i.e. "SendEmailWrapper", that will call the service action "Send_Email " from the GovUKNotify_IS module, passing the information required, and optional if needed, avoiding misbehaviour of this integration.
An integration with the "postFileByEmail" method of GovUKNotifyAPIv2 is done through the service action "Send_FileByEmail" implemented in the GovUKNotify_IS module.
This service action includes all the flow needed to validate the required fields APIKey and TemplateID, through a "CheckRequest" server action wrapper, and checks if the EmailAddress and Placeholder are empty, and the Content is an empty file.
Additionally, the "Request" input parameter is converted to the required structure of the "postFileByEmail" API method, and the integration response is converted to a local "Response" structure.
Below are presented the required and optional request fields for this integration and also its definitions.
Structure with attributes related to the file to send that will be converted to a JSON string and to be added as pair key-value in the Personalisation.
To use this integration you can create a server action wrapper, i.e. "SendFileByEmailWrapper", that will call the service action "Send_FileByEmail" from the GovUKNotify_IS module, passing the information required, and optional if needed, avoiding misbehaviour of this integration.
An integration with the "postLetter" method of GovUKNotifyAPIv2 is done through the service action "Send_Letter" implemented in the GovUKNotify_IS module.
This service action includes all the flow needed to validate the required fields APIKey and TemplateID, through a "CheckRequest" server action wrapper.
The letter template ID is mapped with the argument template_id from the REST API.Your template ID follows a format that is validated using the regular expression ^[\da-fA-F]{8}-([\da-fA-F]{4}-){3}[\da-fA-F]{12}$.
Structure with attributes related to the recipient's address that will be transformed into pairs of key-value in the Personalisation.
address_line_1
address_line_2
address_line_3
address_line_4
address_line_5
address_line_6
address_line_7
This is being mapped with the argument personalisation from the REST API.If a template has placeholder fields different from AddressLines, you must provide their values in a dictionary with key-value pairs.
You can leave out this argument if a template does not have any other placeholder fields for personalised information.
To use this integration you can create a server action wrapper, i.e. "SendLetterWrapper", that will call the service action "Send_Letter" from the GovUKNotify_IS module, passing the information required, and optional if needed, avoiding misbehaviour of this integration.
An integration with the "postPrecompiledLetter" method of GovUKNotifyAPIv2 is done through the service action "Send_PrecompiledLetter" implemented in the GovUKNotify_IS module.
This service action includes all the flow needed to validate the required field APIKey, through a "CheckRequest" server action wrapper, and checks if the Reference is empty, and the Content is an empty file.
Additionally, the "Request" input parameter is converted to the required structure of the "postPrecompiledLetter" API method, and the integration response is converted to a local "Response" structure.
The precompiled letter must be a PDF file which meets the GOV.UK Notify letter specification that is mapped with the argument content from the REST API. This content will be converted to a base64 encoded string before being sent.
This is being mapped with the argument postage.
You can choose first or second-class postage for your precompiled letter. Set the value to first for first class, or second for second class. If you do not pass this argument, the postage will default to second class.
first
second
To use this integration you can create a server action wrapper, i.e. "SendPrecompiledLetterWrapper", that will call the service action "Send_PrecompiledLetter" from the GovUKNotify_IS module, passing the information required, and optional if needed, avoiding misbehaviour of this integration.
An integration with the "getNotification" method of GovUKNotifyAPIv2 is done through the service action "Get_Notification" implemented in the GovUKNotify_IS module.
This service action includes all the flow needed to validate the required field APIKey, through a "CheckRequest" server action wrapper, and checks if the NotificationId is empty.
Additionally, the "Request" input parameter is converted to the required structure of the "getNotification" API method, and the integration response is converted to a local "Response" structure.
The ID of the notification that is mapped with the argument notification_id from the REST API. You can find the notification ID in the response to the original notification method call.
To use this integration you can create a server action wrapper, i.e. "GetNotificationWrapper", that will call the service action "Get_Notification" from the GovUKNotify_IS module, passing the information required, and optional if needed, avoiding misbehaviour of this integration.
An integration with the "getNotifications" method of GovUKNotifyAPIv2 is done through the service action "Get_Notifications" implemented in the GovUKNotify_IS module.
This API call returns one page of up to 250 messages and statuses. You can get either the most recent messages or older messages by specifying a particular notification ID in the OlderThan argument.
OlderThan
This service action includes all the flow needed to validate the required field APIKey through a "CheckRequest" server action wrapper.
Additionally, the "Request" input parameter is converted to the required structure of the "getNotifications" API method, and the integration response is converted to a local "Response" structure.
This is being mapped with the argument template_type.
You can leave out this argument to ignore this filter.
You can filter by:
email
sms
letter
This is being mapped with the argument status.
Input the ID of a notification, i.e. 740e5834-3a29-46b4-9a6f-16142fde533a, into this argument that is mapped with the argument older_than from the REST API. If you use this argument, the method returns the next 250 received notifications older than the given ID.
740e5834-3a29-46b4-9a6f-16142fde533a
If you leave out this argument, the method returns the most recent 250 notifications.
The client only returns notifications that are 7 days old or newer. If the notification specified in this argument is older than 7 days, the client returns an empty response.
To use this integration you can create a server action wrapper, i.e. "GetNotificationsWrapper", that will call the service action "Get_Notifications" from the GovUKNotify_IS module, passing the information required, and optional if needed, avoiding misbehaviour of this integration.If your application needs to present the response on the screen, please check the following example or use this test page:
As the above examples don't have all fields from the response, please check the expected full response from the API here.
An integration with the "getLetterPDF" method of GovUKNotifyAPIv2 is done through the service action "Get_LetterPDF" implemented in the GovUKNotify_IS module.
This API returns the PDF contents of a letter.
Additionally, the "Request" input parameter is converted to the required structure of the "getLetterPDF" API method, and the integration response is converted to a local "Response" structure.
To use this integration you can create a server action wrapper, i.e. "GetLetterPDFWrapper", that will call the service action "Get_LetterPDF" from the GovUKNotify_IS module, passing the information required, and optional if needed, avoiding misbehaviour of this integration.
If your application needs to provide the ability to download the PDF on the screen, please check the following examples or use this test page:
An integration with the "getTemplate" method of GovUKNotifyAPIv2 is done through the service action "Get_TemplateById" implemented in the GovUKNotify_IS module.
This returns the latest version of the template.
Additionally, the "Request" input parameter is converted to the required structure of the "getTemplate" API method, and the integration response is converted to a local "Response" structure.
The ID of the template that is mapped with the argument template_id from the REST API.Your template ID follows a format that is validated using the regular expression ^[\da-fA-F]{8}-([\da-fA-F]{4}-){3}[\da-fA-F]{12}$.
To use this integration you can create a server action wrapper, i.e. "GetTemplateWrapper", that will call the service action "Get_TemplateById" from the GovUKNotify_IS module, passing the information required, and optional if needed, avoiding misbehaviour of this integration.
An integration with the "getTemplateByVersion" method of GovUKNotifyAPIv2 is done through the service action "Get_TemplateByIdAndVersion" implemented in the GovUKNotify_IS module.
This returns the version of the template.
This service action includes all the flow needed to validate the required fields APIKey and TemplateID, through a "CheckRequest" server action wrapper, and checks if the Version is greater than 0.
Additionally, the "Request" input parameter is converted to the required structure of the "getTemplateByVersion" API method, and the integration response is converted to a local "Response" structure.
The version number of the template that is mapped with the argument version.
To use this integration you can create a server action wrapper, i.e. "GetTemplateByVersionWrapper", that will call the service action "Get_TemplateByIdAndVersion" from the GovUKNotify_IS module, passing the information required, and optional if needed, avoiding misbehaviour of this integration.
An integration with the "getTemplates" method of GovUKNotifyAPIv2 is done through the service action "Get_Templates" implemented in the GovUKNotify_IS module.
This returns the latest version of all templates.
This service action includes all the flow needed to validate the required field APIKey, through a "CheckRequest" server action wrapper.
Additionally, the "Request" input parameter is converted to the required structure of the "templates" API method, and the integration response is converted to a local "Response" structure.
This is being mapped with the argument type.
If you leave out this argument, the method returns all templates.
To use this integration you can create a server action wrapper, i.e. "GetTemplatesWrapper", that will call the service action "Get_Templates" from the GovUKNotify_IS module, passing the information required, and optional if needed, avoiding misbehaviour of this integration.
An integration with the "postTemplatePreview" method of GovUKNotifyAPIv2 is done through the service action "Get_TemplatePreview" implemented in the GovUKNotify_IS module.
This generates a preview version of a template.
Additionally, the "Request" input parameter is converted to the required structure of the "postTemplatePreview" API method, and the integration response is converted to a local "Response" structure.
To use this integration you can create a server action wrapper, i.e. "GetTemplatePreviewWrapper", that will call the service action "Get_TemplatePreview" from the GovUKNotify_IS module, passing the information required, and optional if needed, avoiding misbehaviour of this integration.
An integration with the "getReceivedSMS" method of GovUKNotifyAPIv2 is done through the service action "Get_ReceivedSMS" implemented in the GovUKNotify_IS module.
Additionally, the "Request" input parameter is converted to the required structure of the "getReceivedSMS" API method, and the integration response is converted to a local "Response" structure.
The ID of a received text message, i.e. 740e5834-3a29-46b4-9a6f-16142fde533a, into this argument that is mapped with the argument older_than from the REST API. If this is passed, the response will only list text messages received before that message.
If you leave out this argument, the method returns the most recent 250 received text messages.
The client only returns messages that are 7 days old or newer. If the message specified in this argument is older than 7 days, the client returns an empty response.
To use this integration you can create a server action wrapper, i.e. "GetReceivedSMSWrapper", that will call the service action "Get_ReceivedSMS" from the GovUKNotify_IS module, passing the information required, and optional if needed, avoiding misbehaviour of this integration.
The callback authorization is checked in the "OnAuthentication" event of each callback exposed REST API by validating the bearer token sent through the "Authorization" HTTP Request header. In the "OnAuthentication" is called a server action wrapper "ValidateCallbackAuthorization" that will validate the bearer token for the authorization.This is a wrapper to the "ReadTokenService" JWT integration which decodes and validates a signed token.
Besides the "EncodedToken", which is obtained through the "Authorization" HTTP Request header, the remaining parameters values are identified in the following site properties, which value must be set using the Service Center:
If the encoded token is valid, the callback request is accepted. Otherwise, a 403 "Invalid token" exception is retrieved.
An exposed REST API method "postUpdateStatus" is available through the endpoint DeliveryReceiptCallback whose main goal is to update a notification status through the received request.This callback API only should be used/set up through GOV.UK Notify if you are using the service actions available in the GovUKNotify_CS to store the request/response of the email, SMS and letter sent.
Below are presented the request fields for this API and its definitions:
Notify’s ID for the status receipts.Format: UUID
The email address or phone number of the recipient.Format: hello@gov.uk or 07700912345
hello@gov.uk
07700912345
The reference was sent by the service. This reference identifies a single notification or a batch of notifications.Format: 12345678 or null
12345678
The status of the notification.Format: delivered, permanent-failure, temporary-failure or technical-failure
delivered
permanent-failure
temporary-failure
technical-failure
The time the service sent the request.Format: 2017-05-14T12:15:30.000000Z
2017-05-14T12:15:30.000000Z
The last time the status was updated.Format: 2017-05-14T12:15:30.000000Z or null
The time the notification was sent.Format: 2017-05-14T12:15:30.000000Z or null
The notification type.Format: email or SMS
SMS
The id of the template that was used.Format: UUID
The version number of the template that was used.Format: 1
1
This API receives a request that will be serialized to JSON and its binary is stored as a record in NotificationToProcess database entity. If the request is successful, the status code of the response is 200.
200
If you don't want to process the request, a site property DisableUpdateStatus is available whose value "true" allows you to send the status code 200 in the response without the request having been sent for processing.
Being exposed to process events, when a record is created in the NotificationToProcess database entity, a light process execution activity UpdateNotificationActivity is automatically triggered.
Before processing the notification status update begins, it's validated that the record exists in the NotificationToProcess entity and its request content is not empty. If any of the sentences fail, the process ends.
Once a binary request is obtained from the NotificationToProcess entity, it's converted to JSON so that it can be deserialized into the correct structure and sent to the "ProcessingUpdateNotificationActivity" wrapper so that it can be processed.
This wrapper verifies if the notification to process is not processed yet, using the service action "GetNotificationNotProcessed" of the GovUKNotify_CS module (i.e. if the notification status is empty, created or sending).
If the notification is not processed yet, its status is updated using the "UpdateNotificationStatus" service action of the GovUKNotify_CS module. However, before that, if the Gov.UK Notify ID of the notification being processed is not stored, it is updated using the "UpdateGovUkNotificationId" service action from the same module.
If your service receives text messages in Notify, Notify can forward them to your callback URL as soon as they arrive.
Contact the Notify team using the support page or chat with us on Slack to request a unique number for text message replies.
An exposed REST API method "postReceiveSMS" is available through the endpoint ReceiveSMSCallback if you want to store received text messages (SMS) sent by users using your service.
Notify’s ID for the received message.Format: UUID
The phone number the message was sent from.Format: 07700912345
The number the message was sent to (your number).Format: 07700987654
07700987654
The received message.Format: Hello Notify!
The UTC datetime that the message was received by Notify.Format: 2017-05-14T12:15:30.000000Z
This API receives a request that is saved locally using the service action "SaveSMS" of the GovUKNotify_CS module. If the request is successful, the status code of the response is 200.
If you don't want to process the request, a site property DisableReceiveSMS is available whose value "true" allows you to send the status code 200 in the response without the request having been saved locally.
To get the received text messages saved locally, a service action "GetSMS" of the GovUKNotify_CS module is provided for this purpose.
To get multiple notifications, or a single notification, saved locally, the service actions "GetNotifications" and "GetNotificationById" of the GovUKNotify_CS module are provided for this purpose.
In the "OnBeforeRequest" of GovUKNotifyAPIv2 consumed REST API is called a server action wrapper "OnBeforeRequest_GovUKNotifyAPI".This wrapper manipulate the HTTP Request before it is sent, and one of the actions taken in consideration is a wrapper "GenerateTokenFromHTTPHeaderAPIKey". The main goal of this wrapper is to gather the API Key from the header request and with it to generate a JWT bearer token to be appended defined as a value of "Authorization" HTTP request header.
The "GenerateTokenFromHTTPHeaderAPIKey" server action receives as input parameter a list of all HTTP Request Headers and returns the encoded token. From the Headers parameter will be extracted the API Key that was originally sent. For this extraction, we are using a private server action (GetAPIKeyFromHeaders) that filters the Headers list by a specific header name.
After obtaining the API Key, it is used an input parameter for a new wrapper (GenerateJWT) that will be used to generate the final encoded token.In order to keep the token's lifetime short, no value is defined in the "Expires" parameter, meaning the token must be used within 30 seconds after its generation.
For the proper generation of the JWT token, it is used the Service Id as the Issuer, HS256 as the Algorithm, and Secret Key as the Key and KeyId. If the encoded token is generated successfuly, its value is returned. To know a little bit more about how to use the service below, please click here.
An integration with the "postSMS" method of GovUKNotifyAPIv2 is done through the service action "Send_SMS" implemented in the GovUKNotify_IS module.
The callback authorization is checked in the "OnAuthentication" event of each callback exposed REST API by validating the bearer token sent through the "Authorization" HTTP Request header. In the "OnAuthentication" is called a server action wrapper "ValidateCallbackAuthorization" that will validate the bearer token for the authorization. This is a wrapper to the "ReadTokenService" JWT integration which decodes and validates a signed token.