Platform APIs

Notifications templates

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
Templates and contents collections createdAt
  • eq (equals)
  • ne (not equals)
  • gt (greater than)
  • (greater than or equals)
  • lt (less than)
  • le (less than or equals)
Templates and contents collections updatedAt
  • eq (equals)
  • ne (not equals)
  • gt (greater than)
  • (greater than or equals)
  • lt (less than)
  • le (less than or equals)
Contents collections default
  • eq (equals)
Contents collections locale
  • eq (equals)
  • sw (starts with)
Contents collections deliveryMethod
  • eq (equals)

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:

https://api.pingone.com/v1/environments/000c2764-3489-4d34-a707-b23dd488049c/templates?order=-createdAt

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 strong 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 and variables.<variable name>.requiredForDeliveryMethods properties in Notifications templates data model). Required variables must be present in all contents of the deliveryMethod. For example, the strong authentication template includes the variable “otp” as a required variable (variables.otp.required) for SMS and Email deliveryMethods (variables.otp.requiredForDeliveryMethods). This means that whenever you create or update an existing content for this template with an SMS or Email deliveryMethod, it must include “${otp}”.

Notifications templates API operations

The notifications templates endpoints support the following operations:

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. Valid values are SMS, Email and Push.
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.
variables.<variable name>.requiredForDeliveryMethods The collection of deliveryMethods for which this variable is required.

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:
  • Two-character language code, for example, “en”.
  • Two-character language code followed by a two-character country code, separated by an underscore or dash, for example: “en_GB”, “en-GB”.
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.

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/f59504de-3c45-4a37-8d70-d5ad75dfaaa0/templates/"
        },
        "environment": {
            "href": "https://api.pingone.com/v1/environments/f59504de-3c45-4a37-8d70-d5ad75dfaaa0"
        },
        "next": {
            "href": "https://api.pingone.com/v1/environments/f59504de-3c45-4a37-8d70-d5ad75dfaaa0/templates/?cursor=strong_authentication"
        }
    },
    "_embedded": {
        "templates": [
            {
                "_links": {
                    "self": {
                        "href": "https://api.pingone.com/v1/environments/f59504de-3c45-4a37-8d70-d5ad75dfaaa0/templates/verification_code_template"
                    },
                    "environment": {
                        "href": "https://api.pingone.com/v1/environments/f59504de-3c45-4a37-8d70-d5ad75dfaaa0"
                    }
                },
                "id": "verification_code_template",
                "environment": {
                    "id": "f59504de-3c45-4a37-8d70-d5ad75dfaaa0"
                },
                "description": "Users will receive this message to verify their email address.",
                "deliveryMethods": [
                    "Email"
                ],
                "displayName": "Verification Code",
                "createdAt": "2019-01-10T16:39:56.000Z",
                "updatedAt": "2019-01-10T16:39:56.000Z",
                "variables": {
                    "code.value": {
                        "required": true
                    }
                }
            },
            {
                "_links": {
                    "self": {
                        "href": "https://api.pingone.com/v1/environments/f59504de-3c45-4a37-8d70-d5ad75dfaaa0/templates/recovery_code_template"
                    },
                    "environment": {
                        "href": "https://api.pingone.com/v1/environments/f59504de-3c45-4a37-8d70-d5ad75dfaaa0"
                    }
                },
                "id": "recovery_code_template",
                "environment": {
                    "id": "f59504de-3c45-4a37-8d70-d5ad75dfaaa0"
                },
                "description": "Users who need to reset their password will receive this message.",
                "deliveryMethods": [
                    "Email"
                ],
                "displayName": "Password Recovery",
                "createdAt": "2019-01-10T16:39:56.000Z",
                "updatedAt": "2019-01-10T16:39:56.000Z",
                "variables": {
                    "code.value": {
                        "required": true
                    }
                }
            },
            {
                "_links": {
                    "self": {
                        "href": "https://api.pingone.com/v1/environments/f59504de-3c45-4a37-8d70-d5ad75dfaaa0/templates/device_pairing"
                    },
                    "environment": {
                        "href": "https://api.pingone.com/v1/environments/f59504de-3c45-4a37-8d70-d5ad75dfaaa0"
                    }
                },
                "id": "device_pairing",
                "environment": {
                    "id": "f59504de-3c45-4a37-8d70-d5ad75dfaaa0"
                },
                "description": "Users will receive this message to pair their device for strong authentication.",
                "deliveryMethods": [
                    "SMS",
                    "Email"
                ],
                "displayName": "Device Pairing",
                "createdAt": "2018-12-17T13:34:36.000Z",
                "updatedAt": "2018-12-17T13:34:36.000Z",
                "variables": {
                    "user.username": {
                        "required": false
                    },
                    "otp": {
                        "required": true,
                        "requiredForDeliveryMethods": [
                            "SMS",
                            "Email"
                        ]
                    }
                }
            },
            {
                "_links": {
                    "self": {
                        "href": "https://api.pingone.com/v1/environments/f59504de-3c45-4a37-8d70-d5ad75dfaaa0/templates/strong_authentication"
                    },
                    "environment": {
                        "href": "https://api.pingone.com/v1/environments/f59504de-3c45-4a37-8d70-d5ad75dfaaa0"
                    }
                },
                "id": "strong_authentication",
                "environment": {
                    "id": "f59504de-3c45-4a37-8d70-d5ad75dfaaa0"
                },
                "description": "Users will receive this message for strong authentication.",
                "deliveryMethods": [
                    "SMS",
                    "Email",
                    "Push"
                ],
                "displayName": "Strong Authentication",
                "createdAt": "2018-12-10T10:45:05.000Z",
                "updatedAt": "2018-12-10T10:45:05.000Z",
                "variables": {
                    "user.username": {
                        "required": false
                    },
                    "otp": {
                        "required": true,
                        "requiredForDeliveryMethods": [
                            "SMS",
                            "Email"
                        ]
                    }
                }
            }
        ]
    },
    "count": 4,
    "size": 4
}

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/{templateName}" \
-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/{templateName}"
        },
        "environment": {
            "href": "https://api.pingone.com/v1/environments/000c2764-3489-4d34-a707-b23dd488049c"
        }
    },

    "environment": {
        "id": "000c2764-3489-4d34-a707-b23dd488049c"
    },
    "description": "Corporate template",
    "createdAt": "2018-08-27T05:34:51.000Z",
    "updatedAt": "2018-08-27T05:34:51.000Z",
    "displayName": "Corporate template",
    "deliveryMethods": [
        "Email",
        "SMS"
    ],
    "id": "{templateName}",
    "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/f59504de-3c45-4a37-8d70-d5ad75dfaaa0/templates/{templateName}/contents" \
-H 'Authorization: Bearer jwtToken'

The response data looks like this:

{
    "_links": {
        "self": {
            "href": "https://api.pingone.com/v1/environments/f59504de-3c45-4a37-8d70-d5ad75dfaaa0/templates/strong_authentication/contents"
        },
        "environment": {
            "href": "https://api.pingone.com/v1/environments/f59504de-3c45-4a37-8d70-d5ad75dfaaa0"
        },
        "template": {
            "href": "https://api.pingone.com/v1/environments/f59504de-3c45-4a37-8d70-d5ad75dfaaa0/templates/strong_authentication"
        },
        "next": {
            "href": "https://api.pingone.com/v1/environments/f59504de-3c45-4a37-8d70-d5ad75dfaaa0/templates/strong_authentication/contents?cursor=b36dadb6-1f30-7a6b-337b-ceca79259ec1"
        }
    },
    "_embedded": {
        "contents": [
            {
                "_links": {
                    "self": {
                        "href": "https://api.pingone.com/v1/environments/f59504de-3c45-4a37-8d70-d5ad75dfaaa0/templates/strong_authentication/contents/600f8646-98fe-4ba8-aea7-088b8f35e457"
                    },
                    "template": {
                        "href": "https://api.pingone.com/v1/environments/f59504de-3c45-4a37-8d70-d5ad75dfaaa0/templates/strong_authentication"
                    },
                    "environment": {
                        "href": "https://api.pingone.com/v1/environments/f59504de-3c45-4a37-8d70-d5ad75dfaaa0"
                    }
                },
                "id": "600f8646-98fe-4ba8-aea7-088b8f35e457",
                "environment": {
                    "id": "f59504de-3c45-4a37-8d70-d5ad75dfaaa0"
                },
                "createdAt": "2019-07-14T13:04:58.291Z",
                "updatedAt": "2019-07-14T13:04:58.291Z",
                "locale": "en",
                "template": {
                    "id": "strong_authentication"
                },
                "subject": "PingOne: New authentication request",
                "body": "Your passcode is: ${otp}",
                "from": "noreply@pingidentity.com",
                "deliveryMethod": "Email",
                "default": false
            },
            {
                "_links": {
                    "self": {
                        "href": "https://api.pingone.com/v1/environments/f59504de-3c45-4a37-8d70-d5ad75dfaaa0/templates/strong_authentication/contents/5d2e8554-c541-7804-2078-480bbdf31355"
                    },
                    "template": {
                        "href": "https://api.pingone.com/v1/environments/f59504de-3c45-4a37-8d70-d5ad75dfaaa0/templates/strong_authentication"
                    },
                    "environment": {
                        "href": "https://api.pingone.com/v1/environments/f59504de-3c45-4a37-8d70-d5ad75dfaaa0"
                    }
                },
                "id": "5d2e8554-c541-7804-2078-480bbdf31355",
                "environment": {
                    "id": "f59504de-3c45-4a37-8d70-d5ad75dfaaa0"
                },
                "createdAt": "2018-08-27T05:34:51.000Z",
                "updatedAt": "2018-12-17T13:34:36.000Z",
                "locale": "en",
                "template": {
                    "id": "strong_authentication"
                },
                "content": "Your PingOne passcode is: ${otp}",
                "deliveryMethod": "SMS",
                "default": true
            },
            {
                "_links": {
                    "self": {
                        "href": "https://api.pingone.com/v1/environments/f59504de-3c45-4a37-8d70-d5ad75dfaaa0/templates/strong_authentication/contents/e85680da-5fe3-771c-37fe-1bc5465ce4f3"
                    },
                    "template": {
                        "href": "https://api.pingone.com/v1/environments/f59504de-3c45-4a37-8d70-d5ad75dfaaa0/templates/strong_authentication"
                    },
                    "environment": {
                        "href": "https://api.pingone.com/v1/environments/f59504de-3c45-4a37-8d70-d5ad75dfaaa0"
                    }
                },
                "id": "e85680da-5fe3-771c-37fe-1bc5465ce4f3",
                "environment": {
                    "id": "f59504de-3c45-4a37-8d70-d5ad75dfaaa0"
                },
                "createdAt": "2018-08-27T05:34:51.000Z",
                "updatedAt": "2018-12-17T13:34:36.000Z",
                "locale": "en",
                "template": {
                    "id": "strong_authentication"
                },
                "subject": "PingOne: New authentication request",
                "body": "Your passcode is: ${otp}",
                "from": "noreply@pingidentity.com",
                "deliveryMethod": "Email",
                "default": true
            },
            {
                "_links": {
                    "self": {
                        "href": "https://api.pingone.com/v1/environments/f59504de-3c45-4a37-8d70-d5ad75dfaaa0/templates/strong_authentication/contents/b36dadb6-1f30-7a6b-337b-ceca79259ec1"
                    },
                    "template": {
                        "href": "https://api.pingone.com/v1/environments/f59504de-3c45-4a37-8d70-d5ad75dfaaa0/templates/strong_authentication"
                    },
                    "environment": {
                        "href": "https://api.pingone.com/v1/environments/f59504de-3c45-4a37-8d70-d5ad75dfaaa0"
                    }
                },
                "id": "b36dadb6-1f30-7a6b-337b-ceca79259ec1",
                "environment": {
                    "id": "f59504de-3c45-4a37-8d70-d5ad75dfaaa0"
                },
                "createdAt": "2018-12-17T13:34:36.000Z",
                "updatedAt": "2018-12-17T13:34:36.000Z",
                "locale": "en",
                "template": {
                    "id": "strong_authentication"
                },
                "title": "New Authentication Request",
                "body": "You have a new authentication request.",
                "deliveryMethod": "Push",
                "default": true
            }
        ]
    },
    "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.