Work with notifications templates


Notifications templates

The templates service manages 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 may 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. For more information, see Work with user roles.

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:

SCIM operators can be applied to the following attributes:

Placeholder for table

Collection Attribute Supported Operators
Templates, email contents and text message contents collections createdAt
  • eq (equals)
  • ne (not equals)
  • gt (greater than)
  • ge (greater than or equals)
  • lt (less than)
  • le (less than or equals)
Templates, email contents and text message contents collections updatedAt
  • eq (equals)
  • ne (not equals)
  • gt (greater than)
  • ge (greater than or equals)
  • lt (less than)
  • le (less than or equals)
Email contents and text message contents collections default
  • eq (equals)
Email contents and text message contents collections locale
  • eq (equals)
  • sw (starts with)

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 will return the collection in a descending order. Using the attribute with “-” prefix will return the collection ordered in ascending order. For example, the following URL will return 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.

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 'Content-type: application/json' \
-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"
                    }
                },
                "description": "Template for test purposes",
                "createdAt": "2018-08-27T05:34:51.000Z",
                "updatedAt": "2018-08-27T05:34:51.000Z",
                "name": "testTemplate"
            }
        ]
    },
    "count": 1,
    "size": 1
}

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 "Content-type: application/json" \
-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"
        }
    },
    "description": "Template for test purposes",
    "createdAt": "2018-08-27T05:34:51.000Z",
    "updatedAt": "2018-08-27T05:34:51.000Z",
    "name": "testTemplate"
}

Create email notification content

The POST /environments/{environmentId}/templates/{templateName}/emails operation creates 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 and the subject should contain no more than 256 characters. Additionally, “noreply@pingidentity.com” is used as ‘Reply To’ and ‘From’ by default.

curl -X "POST" "https://api.pingone.com/v1/environments/000c2764-3489-4d34-a707-b23dd488049c/templates/testTemplate/emails" \
-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."
}'

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}/testMessages operation creates 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.

Note that in cases where the text message is sent to a country where an alphanumeric sender ID is forbidden or not supported, or if the sender ID is not provided, a default number is used as the sender ID during the actual sending of the text message. Due to India’s pre-registration laws, “PingID” is always used as the sender ID for SMS recipients.

curl -X "POST" "https://api.pingone.com/v1/environments/cfe9d853-2993-44d9-9cd2-cbc2e83fdbfd/template/testTemplate/textMessages" \
-H 'Content-type: application/json' \
-H 'Authorization: Bearer jwtToken' \
-d $'{
  "locale":"en",
  "content":"The text message content.",
  "sender":"PingID"
}'

The response returns a 201 created message and the data for the created text message content resource.

Update email notification content

The PUT /environments/{environmentId}/templates/{templateName}/emails/{emailId} operation updates an existing customized email content resource associated with the template specified in the request URL.

curl -X "PUT" "https://api.pingone.com/v1/environments/000c2764-3489-4d34-a707-b23dd488049c/templates/testTemplate/emails/83c19ab3-fa88-4b2a-8c0c-6ee1046f8a3e" \
-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."
}'

The response returns a 200 successful message and the data for the updated email content resource.

Update text message notification content

The PUT /environments/{environmentId}/templates/{templateName}/textMessages/{textMessageId} operation updates an existing customized text message content resource associated with the template specified in the request URL.

curl -X "POST" "https://api.pingone.com/v1/environments/cfe9d853-2993-44d9-9cd2-cbc2e83fdbfd/template/testTemplate/textMessages/83c19ab3-fa88-4b2a-8c0c-6ee1046f8a3e" \
-H 'Content-type: application/json' \
-H 'Authorization: Bearer jwtToken' \
-d $'{
  "locale":"en",
  "content":"The text message content.",
  "sender":"PingID"
}'

The response returns a 200 successful message and the data for the updated text message content resource.

Delete email notification content

The DELETE /environments/{environmentId}/templates/{templateName}/emails/{emailId} operation deletes an existing customized email content resource associated with the template specified in the request URL.

curl -X "DELETE" "https://api.pingone.com/v1/environments/000c2764-3489-4d34-a707-b23dd488049c/templates/testTemplate/emails/83c19ab3-fa88-4b2a-8c0c-6ee1046f8a3e" \
-H 'Authorization: Bearer jwtToken'

The response returns a 204 no content message.

Delete text message notification content

The DELETE /environments/{environmentId}/templates/{templateName}/textMessages/{textMessageId} operation deletes an existing customized text message content resource associated with the template specified in the request URL.

curl -X "PUT" "https://api.pingone.com/v1/environments/cfe9d853-2993-44d9-9cd2-cbc2e83fdbfd/template/testTemplate/textMessages/83c19ab3-fa88-4b2a-8c0c-6ee1046f8a3e" \
-H 'Authorization: Bearer jwtToken'

The response returns a 204 no content message.

Get email content resources

The GET /environments/{environmentId}/templates/{templateName}/emails endpoint returns a list of all email notification 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/emails" \
-H 'Content-type: application/json' \
-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/emails"
        },
        "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/emails?cursor=7400313b-69fe-7164-1e44-f80b490cc03c"
        }
    },
    "_embedded": {
        "emails": [
            {
                "_links": {
                    "self": {
                        "href": "https://api.pingone.com/v1/environments/000c2764-3489-4d34-a707-b23dd488049c/templates/testTemplate/emails/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"
                    }
                },
                "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
            },
            {
                "_links": {
                    "self": {
                        "href": "https://api.pingone.com/v1/environments/000c2764-3489-4d34-a707-b23dd488049c/templates/testTemplate/emails/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"
                    }
                },
                "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
            }
        ]
    },
    "count": 2,
    "size": 2
}

Get data for a single email notification content resource

To get data for a single email notification content resource, the /environments/{environmentId}/templates/{templateName}/emails/{emailId} operation returns data only for the email notification content resource with the email content ID specified in the request URL.

curl -X GET "https://api.pingone.com/v1/environments/000c2764-3489-4d34-a707-b23dd488049c/templates/testTemplate/emails/7400313b-69fe-7164-1e44-f80b490cc03c" \
-H "Content-type: application/json" \
-H "Authorization: Bearer jwtToken"

The response returns a 200 successful message and the data for the specified email content resource.

Get text message content resources

The GET /environments/{environmentId}/templates/{templateName}/textMessages endpoint returns a list of all text message notification 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/textMessages" \
-H 'Content-type: application/json' \
-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/textMessages"
        },
        "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/textMessages?cursor=69b212d1-a4ba-7366-1f92-c1387eeb8293"
        }
    },
    "_embedded": {
        "textMessages": [
            {
                "_links": {
                    "self": {
                        "href": "https://api.pingone.com/v1/environments/000c2764-3489-4d34-a707-b23dd488049c/templates/testTemplate/textMessages/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"
                    }
                },
                "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
            },
            {
                "_links": {
                    "self": {
                        "href": "https://api.pingone.com/v1/environments/000c2764-3489-4d34-a707-b23dd488049c/templates/testTemplate/textMessages/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"
                    }
                },
                "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
            }
        ]
    },
    "count": 2,
    "size": 2
}

Get data for a single text message notification content resource

To get data for a single text message notification content resource, the GET /environments/{environmentId}/templates/{templateName}/textMessages/{textMessageId} operation returns data only for the text message notification content resource with the text message content ID specified in the request URL.

curl -X GET "https://api.pingone.com/v1/environments/000c2764-3489-4d34-a707-b23dd488049c/templates/testTemplate/textMessages/69b212d1-a4ba-7366-1f92-c1387eeb8293" \
-H "Content-type: application/json" \
-H "Authorization: Bearer jwtToken"

The response returns a 200 successful message and the data for the specified email notification content resource.