Platform APIs

Notifications templates service

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 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
  • eq (equals)
  • ne (not equals)
  • gt (greater than)
  • ge (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)
  • ge (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 - 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.

Notifications templates API operations

The notifications templates service supports the following endpoint 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.

Import tasks data model

Property Description
createdAt The time the resource was created.
description A string that specifies the description of the template.
name A string that specifies the template name.
email.body A string that specifies the email message body.
email.default A boolean that species whether this template is the default.
email.from A string that specifies the email’s ‘From’ address.
email.id A string that specifies the resource’s unique identifier.
email.locale A string that specifies the locale associated with the content. This attribute is set to ‘en’ by default.
email.replyTo A string that specifies the email’s ‘Reply-to’ address.
email.subject A string that specifies the email’s subject line.
textMessages.default A boolean that species whether this template is the default.
textMessages.locale A string that specifies the locale associated with the content. This attribute is set to ‘en’ by default.
textMessages.content A string that specifies the text message content.
textMessages.sender A string that specifies the text message sender ID.
updatedAt The time the resource was last updated.

Response codes

Code Message
200 Successful operation.
201 Successfully created.
204 Successfully removed. No content.
400 The request was invalid.
401 You weren’t authenticated to perform this operation.
404 The specified object doesn’t exist.
429 Too many requests.

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/{environmentId}/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"
                    }
                    "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",
                "id": "testTemplate"
            }
        ]
    },
    "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/{environmentId}/templates/{templateName}" \
-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"
        }
    },

    "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",
    "name": "testTemplate"
}

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 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/{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.

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/{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.

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 '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/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 "Content-type: application/json" \
-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.