Notifications templates
The templates endpoints manage notification templates and notifications content.
A template represents a specific notification related flow, for example, “multi-factor authentication” or “password reset”. Each environment has a default set of predefined templates it can access. Each template contains a unique template name and a short description.
Email and text messages contents are defined in the context of a specific template. Each template is associated with a list of predefined default email and text message contents. These contents cannot be deleted or updated. Additional customized contents can be added, but only one customized content can be defined per template, delivery method (text message or email) and locale.
Note: You need the Environment Admin role to perform operations on notifications template resources.
Filtering result data
You can filter collection results by applying a SCIM filtering expression to the request URL. For large collections, a filtering expression appended to the query returns a targeted, more useful data set. For example, the following URL-encoded SCIM filter returns templates created before 2018-07-30 and updated after 2018-08-30:
[https://api.pingone.com/v1/environments/000c2764-3489-4d34-a707-b23dd488049c/templates?filter=(createdAt%20lt%20%222018-08-30%22)%20and%20(updatedAt%20gt%20%222018-07-30%22)%20](https://api.pingone.com/v1/environments/000c2764-3489-4d34-a707-b23dd488049c/templates?filter=(createdAt%20lt%20%222018-08-30%22)%20and%20(updatedAt%20gt%20%222018-07-30%22)%20)
SCIM operators can be applied to the following attributes:
Collection | Attribute | Supported Operators |
---|---|---|
Templates and contents collections | createdAt |
|
Templates and contents collections | updatedAt |
|
Contents collections | default |
|
Contents collections | locale |
|
Contents collections | deliveryMethod |
|
Additionally, the logical “AND” and “OR” operators may be used for building a compound expressions.
Ordering result data
You can order the collections returned by the GET collection endpoints according to the createdAt
and updatedAt
attribute. Ordering by any attribute returns the collection in a descending order. Using the attribute with the “-
” prefix returns the collection ordered in ascending order. For example, the following URL returns all the templates ordered by ascending creation date:
Note:
- Multiple columns ordering is not supported.
- Default ordering is descending, by
UpdatedAt
.
For more information about SCIM syntax and operators, see Conventions.
Variables restrictions
Variables may be used in order to allow dynamic content. For example:
- The SMS content is “
Hi ${user.username}! Your one time passcode is ${otp}
” - The
${user.username}
variable has a value of “John
” - The ${otp} variable has a value of “
548263
”
The resulting message is:
"Hi John! Your one time passcode is 548263
", which includes the dynamic values “John
" and “548263
”.
Each template defines the variables that can be used on its contents. For example, “otp
” is relevant for the offline authentication template, while “code.value
” is relevant for the password reset flow. When defining a new content or updating an existing content, you may only use variables defined in the template. Thus, if the authentication template supports the two defined variables “otp
” and “user.username
”, you can not create an SMS content with the message “${greeting}! Your one time passcode is ${otp}
”, because the template does not support the “greeting
” variable.
Required variables
Some variables are required (refer to the variables.<variable name>.required
property in Notifications templates data model). Required variables must be present in all contents. For example, the offline authentication template includes the variable “otp
” as a required variable (variables.otp.required
). This means that whenever you create or update an existing content for this template, it must include “${otp}
”.
Notifications templates API operations
The notifications templates endpoints support the following operations:
-
GET /environments/{environmentId}/templates
Read all templates -
GET /environments/{environmentId}/templates/{templateName}
Read one template -
PUT /environments/{environmentId}/templates/{templateName}/contents/{contentId}
Update content -
GET /environments/{environmentId}/templates/{templateName}/contents
Read content resources -
DELETE /environments/{environmentId}/templates/{templateName}/contents/{contentId}
Delete content
For hands-on experience with the notifications templates API endpoints, click the Run in Postman button below to download a Postman collection that you can import and open in your local Postman application.
Notifications templates data model
Template
Property | Description |
---|---|
id |
A string that specifies the template id. |
displayName |
A string that specifies the template’s display name. |
deliveryMethods |
An array of strings that specifies the delivery methods supported for this template. |
createdAt |
The time the resource was created. |
updatedAt |
The time the resource was last updated. |
description |
A string that specifies the description of the template. |
variables.<variable name>.required |
The declaration of a variable, and the boolean indicator that specifies whether this variable must be present in the template’s contents or not. |
Content
Property | Description |
---|---|
id |
A string that specifies the template id. |
createdAt |
The time the resource was created. |
updatedAt |
The time the resource was last updated. |
default |
A boolean indicator that specifies whether the template is a default template or not. |
locale |
A valid case-insensitive locale, complying with the ISO-639 language code and ISO-3166 country code standards:
|
deliveryMethod |
The content’s delivery method. |
content |
The SMS content (relevant when deliveryMethod is SMS). |
sender |
The SMS sender ID (relevant when deliveryMethod is SMS). |
from |
The email’s “from” address (relevant when deliveryMethod is Email). |
subject |
The email’s subject line (relevant when deliveryMethod is Email). |
body |
The email body (relevant when deliveryMethod is Email). |
replyTo |
The email’s “reply to” address (relevant when deliveryMethod is Email). |
Response codes
Code | Message |
---|---|
200 | Successful operation. |
201 | Successfully created. |
204 | Successfully removed. No content. |
400 | The request could not be completed. |
401 | You do not have access to this resource. |
404 | The requested resource was not found. |
409 | A resource with the specified name already exists. |
Endpoint examples
Get templates
The GET /environments/{environmentId}/templates
endpoint returns a list of all notifications template resources for the specified environment resource.
curl -X "GET" "https://api.pingone.com/v1/environments/000c2764-3489-4d34-a707-b23dd488049c/templates" \
-H 'Authorization: Bearer jwtToken'
The response data looks like this:
{
"_links": {
"self": {
"href": "https://api.pingone.com/v1/environments/000c2764-3489-4d34-a707-b23dd488049c/templates"
},
"environment": {
"href": "https://api.pingone.com/v1/environments/000c2764-3489-4d34-a707-b23dd488049c"
},
"next": {
"href": "https://api.pingone.com/v1/environments/000c2764-3489-4d34-a707-b23dd488049c/templates?cursor=testTemplate"
}
},
"_embedded": {
"templates": [
{
"_links": {
"self": {
"href": "https://api.pingone.com/v1/environments/000c2764-3489-4d34-a707-b23dd488049c/templates/testTemplate"
},
"environment": {
"href": "https://api.pingone.com/v1/environments/000c2764-3489-4d34-a707-b23dd488049c"
}
"environment": {
"id": "000c2764-3489-4d34-a707-b23dd488049c"
},
},
"description": "Template for test purposes",
"createdAt": "2018-08-27T05:34:51.000Z",
"updatedAt": "2018-08-27T05:34:51.000Z",
"displayName": "Test Template",
"deliveryMethods": [
"Email",
"SMS"
],
"id": "testTemplate",
"variables": {
"user.username": {
"required": false
},
"otp": {
"required": false
}
}
}
]
},
"count": 1,
"size": 1
}
Get data for a single template resource
To get data for a single template resource, the GET /environments/{environmentId}/templates/{templateName}
operation returns data only for the template resource with the template name specified in the request URL.
curl -X "GET" "https://api.pingone.com/v1/environments/000c2764-3489-4d34-a707-b23dd488049c/templates/testTemplate" \
-H 'Authorization: Bearer jwtToken'
The response data looks like this:
{
"_links": {
"self": {
"href": "https://api.pingone.com/v1/environments/000c2764-3489-4d34-a707-b23dd488049c/templates/testTemplate"
},
"environment": {
"href": "https://api.pingone.com/v1/environments/000c2764-3489-4d34-a707-b23dd488049c"
}
},
"environment": {
"id": "000c2764-3489-4d34-a707-b23dd488049c"
},
"description": "Template for test purposes",
"createdAt": "2018-08-27T05:34:51.000Z",
"updatedAt": "2018-08-27T05:34:51.000Z",
"displayName": "Test Template",
"deliveryMethods": [
"Email",
"SMS"
],
"id": "testTemplate",
"variables": {
"user.username": {
"required": false
},
"otp": {
"required": false
}
}
}
Create email notification content
The POST /environments/{environmentId}/templates/{templateName}/contents
operation can be used to create a new customized email content resource associated with the template specified in the request URL.
Note that the email’s body should weigh no more than 100 KB, the subject should contain no more than 256 characters and the Variables restrictions should apply. Additionally, “noreply@pingidentity.com” is used as ‘From’ by default.
curl -X "POST" "https://api.pingone.com/v1/environments/{environmentId}/templates/{templateName}/contents" \
-H 'Content-type: application/json' \
-H 'Authorization: Bearer jwtToken' \
-d $'{
"locale":"en"
"subject":"The subject of the email",
"body":"The body of the notification email.",
"deliveryMethod":"Email"
}'
The response returns a 201 created message and the data for the created email content resource.
Create text message notification content
The POST /environments/{environmentId}/templates/{templateName}/contents
operation can be used to create a new customized text message content resource associated with the template specified in the request URL.
The size restriction on the content
value is derived from the content
encoding. UC-2 encoding is used for messages that contain non GSM-7 characters, and in this case, a size restriction of 67 characters is enforced. However, GSM-7 encoded messages may contain up to 153 characters.
The sender
value may contain only alphanumeric characters and spaces, and its length may be up to 11 characters.
In some countries, including the US, it is impossible to send an SMS with an alphanumeric sender ID. For those countries, the sender ID must be empty. For international alphanumeric sender support, please refer to https://support.twilio.com/hc/en-us/articles/223133767-International-support-for-Alphanumeric-Sender-ID.
Due to India’s pre-registration laws, “PingID” is always used as the sender ID for SMS recipients in India.
In addition, the Variables restrictions should apply to text message notification content.
curl -X "POST" "https://api.pingone.com/v1/environments/{environmentId}/templates/{templateName}/contents" \
-H 'Content-type: application/json' \
-H 'Authorization: Bearer jwtToken' \
-d $'{
"locale":"en",
"content":"The text message content.",
"sender":"PingID",
"deliveryMethod":"SMS"
}'
The response returns a 201 created message and the data for the created text message content resource.
Update content
The PUT /environments/{environmentId}/templates/{templateName}/contents/{contentId}
operation updates an existing customized content resource associated with the template specified in the request URL.
In addition, the Variables restrictions should apply.
curl -X "PUT" "https://api.pingone.com/v1/environments/{environmentId}/templates/{templateName}/contents/{contentId}" \
-H 'Content-type: application/json' \
-H 'Authorization: Bearer jwtToken' \
-d $'{
"locale":"en"
"subject":"The subject of the email",
"body":"The body of the notification email.",
"deliveryMethod":"Email"
}'
The response returns a 200 successful message and the data for the updated content resource.
Get content resources
The GET /environments/{environmentId}/templates/{templateName}/contents
endpoint returns a list of all content resources associated with the template specified in the request URL.
curl -X "GET" "https://api.pingone.com/v1/GET /environments/000c2764-3489-4d34-a707-b23dd488049c/templates/testTemplate/contents" \
-H 'Authorization: Bearer jwtToken'
The response data looks like this:
{
"_links": {
"self": {
"href": "https://api.pingone.com/v1/environments/000c2764-3489-4d34-a707-b23dd488049c/templates/testTemplate/contents"
},
"environment": {
"href": "https://api.pingone.com/v1/environments/000c2764-3489-4d34-a707-b23dd488049c"
},
"template": {
"href": "https://api.pingone.com/v1/environments/000c2764-3489-4d34-a707-b23dd488049c/templates/testTemplate"
},
"next": {
"href": "https://api.pingone.com/v1/environments/000c2764-3489-4d34-a707-b23dd488049c/templates/testTemplate/contents?cursor=7400313b-69fe-7164-1e44-f80b490cc03c"
}
},
"_embedded": {
"contents": [
{
"_links": {
"self": {
"href": "https://api.pingone.com/v1/environments/000c2764-3489-4d34-a707-b23dd488049c/templates/testTemplate/contents/3ee39182-067f-7b04-1ac6-a014da113c81"
},
"template": {
"href": "https://api.pingone.com/v1/environments/000c2764-3489-4d34-a707-b23dd488049c/templates/testTemplate"
},
"environment": {
"href": "https://api.pingone.com/v1/environments/000c2764-3489-4d34-a707-b23dd488049c"
}
},
"environment": {
"id": "000c2764-3489-4d34-a707-b23dd488049c"
},
"template": {
"id": "testTemplate"
},
"id": "3ee39182-067f-7b04-1ac6-a014da113c81",
"createdAt": "2018-08-27T05:34:52.000Z",
"updatedAt": "2018-08-27T05:34:52.000Z",
"locale": "fr",
"subject": "Email subject in French",
"body": "Email body in French.",
"replyTo": "noreply@pingidentity.com",
"from": "noreply@pingidentity.com",
"default": true,
"deliveryMethod":"Email"
},
{
"_links": {
"self": {
"href": "https://api.pingone.com/v1/environments/000c2764-3489-4d34-a707-b23dd488049c/templates/testTemplate/contents/7400313b-69fe-7164-1e44-f80b490cc03c"
},
"template": {
"href": "https://api.pingone.com/v1/environments/000c2764-3489-4d34-a707-b23dd488049c/templates/testTemplate"
},
"environment": {
"href": "https://api.pingone.com/v1/environments/000c2764-3489-4d34-a707-b23dd488049c"
}
},
"environment": {
"id": "000c2764-3489-4d34-a707-b23dd488049c"
},
"template": {
"id": "testTemplate"
},
"id": "7400313b-69fe-7164-1e44-f80b490cc03c",
"createdAt": "2018-08-27T05:34:51.000Z",
"updatedAt": "2018-08-27T05:34:51.000Z",
"locale": "en",
"subject": "Email subject in English",
"body": "Email body in English.",
"replyTo": "noreply@pingidentity.com",
"from": "noreply@pingidentity.com",
"default": true,
"deliveryMethod":"Email"
},
{
"_links": {
"self": {
"href": "https://api.pingone.com/v1/environments/000c2764-3489-4d34-a707-b23dd488049c/templates/testTemplate/contents/5ad11033-8eeb-7dad-19ad-17b4cb1cd58f"
},
"template": {
"href": "https://api.pingone.com/v1/environments/000c2764-3489-4d34-a707-b23dd488049c/templates/testTemplate"
},
"environment": {
"href": "https://api.pingone.com/v1/environments/000c2764-3489-4d34-a707-b23dd488049c"
}
},
"environment": {
"id": "000c2764-3489-4d34-a707-b23dd488049c"
},
"template": {
"id": "testTemplate"
},
"id": "5ad11033-8eeb-7dad-19ad-17b4cb1cd58f",
"createdAt": "2018-08-27T05:34:52.000Z",
"updatedAt": "2018-08-27T05:34:52.000Z",
"locale": "fr",
"content": "SMS content in French",
"sender": "sender French",
"default": true,
"deliveryMethod":"SMS"
},
{
"_links": {
"self": {
"href": "https://api.pingone.com/v1/environments/000c2764-3489-4d34-a707-b23dd488049c/templates/testTemplate/content/69b212d1-a4ba-7366-1f92-c1387eeb8293"
},
"template": {
"href": "https://api.pingone.com/v1/environments/000c2764-3489-4d34-a707-b23dd488049c/templates/testTemplate"
},
"environment": {
"href": "https://api.pingone.com/v1/environments/000c2764-3489-4d34-a707-b23dd488049c"
}
},
"environment": {
"id": "000c2764-3489-4d34-a707-b23dd488049c"
},
"template": {
"id": "testTemplate"
}, "id": "69b212d1-a4ba-7366-1f92-c1387eeb8293",
"createdAt": "2018-08-27T05:34:51.000Z",
"updatedAt": "2018-08-27T05:34:51.000Z",
"locale": "en",
"content": "SMS content in English",
"sender": "sender English",
"default": true,
"deliveryMethod":"SMS"
}
]
},
"count": 4,
"size": 4
}
Get data for a single content resource
To get data for a single content resource, the GET /environments/{environmentId}/templates/{templateName}/contents/{contentId}
operation returns data only for the content resource with the content ID specified in the request URL.
curl -X GET "https://api.pingone.com/v1/environments/{environmentId}/templates/{templateName}/contents/{contentId}" \
-H "Authorization: Bearer jwtToken"
The response returns a 200 successful message and the data for the specified email content resource.
Delete content
The DELETE /environments/{environmentId}/templates/{templateName}/contents/{contentId}
operation deletes an existing customized content resource associated with the template specified in the request URL.
curl -X "DELETE" "https://api.pingone.com/v1/environments/{environmentId}/templates/{templateName}/contents/{contentId}" \
-H 'Authorization: Bearer jwtToken'
The response returns a 204 no content message.