The templates endpoints manage notifications templates and notifications contents. Each content is based on one specific template. Each template can be associated with multiple contents.

Each environment has a set of predefined notifications templates it can access. A template represents a specific process flow, for example, device_pairing or strong_authentication, that requires a notification. Each template defines the deliveryMethods (Email, SMS, Voice or Push) that it supports. You can read templates with this API, but you cannot create, update, or delete them.

A content defines one message text choice for a notification. Each content is always associated with one template and has one deliveryMethod and one locale. Each template comes with one predefined default content for each of its supported deliveryMethods. You cannot delete or update default contents with this API. You can however, create an unlimited number of custom contents for each template. To create custom contents, see Creating custom contents.

Runtime logic for content selection

Each content, whether default or custom, is associated with one template, one deliveryMethod, one locale, and optionally, one variant (For more information on variants, see Creating custom contents). When a request for content is executed at runtime, it includes a template, deliveryMethod, locale and, optionally, a variant.

  1. PingOne matches the best text notification content for the user based on locale and variant name.

  2. If a locale is specified on the request (for example, on the notification.template.locale property on POST /environments/{{envID}}/users/{{userID}}/devices), it overrides the user’s preferred language setting.

  3. If the locale on the request (or the user’s preferred locale) does not match a notification content with the exact locale, PingOne uses the best matching locale (based on the language, ignoring the region) if available. For example, es-ES falls back to es.

  4. For the locale property value, PingOne supports language tags with quality values as described in Hypertext Transfer Protocol (HTTP/1.1): Semantics and Content.

  5. For voice notifications, PingOne uses the best matching language based on the supported languages of the provider (Twilio, Syniverse, or a custom provider).

Content language selection examples

Content
available
languages
Voice
provider
support
User
preferred
language
Locale
in the
request
Resulting
notification
language
Description
fr-CA
it(default)
fr-CA
it
en
fr-CA fr-CA fr-CA User’s preference and locale in the request match an available language in the content templates
fr-CA
it(default)
fr-CA
it
en
es es it Default content language used: neither user’s preference nor locale in the request match an available content language
fr-CA
it(default)
fr-CA
it
en
es it Default content language used: no locale in the request, and no match of user’s preference with available content languages
fr-CA
it(default)
fr-CA
it
en
es it Default content language used: no definition for user’s preference, and no match of locale in the request with available content languages
fr-CA
it(default)
fr-CA
it
en
it Default content language used: no definition for both user’s preference locale in the request
fr-CA
it(default)
fr-CA
it
en
es fr-CA fr-CA Locale in the request used: user’s preference does not match an available language in the content templates, but the locale in the request does
fr
it(default)
fr
it
en
es fr-CA fr User preferred language doesn’t match any of the available contents’ locales, but locale in the request has a close match to an available content’s locale (fr ~= fr-CA).
fr-CA
it
fr-CA
it
en
es es en Both user preferred language and locale in the request don’t match an available content’s locale and there’s no available content for the environment’s default language. Falling back to English.
fr
it(default)
es
fr
it
en
fr es SMS,email,push:es
Voice:fr
User preferred language matches an available content’s locale (es). For notifications of type SMS, Email and Push, es will be used.
Since es is not a supported voice language, for Voice notifications, fr will be used, since it matches the locale in the request and is also supported for text-to-speech.

Creating custom contents

Add and update custom contents with POST /environments/{{envID}}/templates/{{templateName}}/contents and PUT /environments/{{envID}}/templates/{{templateName}}/contents/{{contentID}}. Each content is associated with one template and has one deliveryMethod and one ISO language code (locale). You can define multiple custom contents for each template + deliveryMethod + locale combination with the variant property.

Variants

If you have more than one custom content that uses the same template, deliveryMethod, and locale, these contents must have different values for the variant property. The variant property holds the unique user-defined name for each content variant that uses the same template + deliveryMethod + locale combination.

variant values can be reused by contents across different template + deliveryMethod + locale combinations. They need to be unique within the same template + deliveryMethod + locale combination only. As a best practice, use the same variant value for contents with the same message text. For example, the variant value variant_A can be used by a content with the strong_authentication + email + en combination and also by a content with the strong_authentication + push + en combination. For two contents that both use the strong_authentication + email + en combination though, if one content uses the variant value of variant_A, the other content must use a variant value such as variant_B.

Use PATCH environments/{{envID}}/templates/{{templateName}}/contents?filter=variant eq {{variantName}} to bulk update the variant value in contents with the same variant value. Use DELETE environments/{{envID}}/templates/{{templateName}}/contents?filter=variant eq {{variantName}} to bulk delete contents with the same variant value.

Variables

Variables are placeholders for values that change depending on the context. For example:

The resulting message is:
Hi John! Your one time passcode is 548263, which includes the variable values John and 548263.

Predefined variables

If a template includes predefined variables, the template lists which variables can be optionally used in its contents and which variables are required in its contents. For example, user.username can be optionally used by strong_authentication contents, while otp is required for all SMS, Voice and Email contents.

"variables": {
    "user.username": {
        "required": false
    },
    "otp": {
        "required": true,
        "requiredForDeliveryMethods": [
            "SMS",
            "Voice",
            "Email"
        ]
    }
}

Dynamic variables

In addition to predefined variables, some templates also allow dynamic variables. If a template has the property allowDynamicVariables set to true, its contents can contain any user-defined variable in the format ${variable_name}.

Variable settings per template

Template Required Predefined Variables Optional Predefined Variables Dynamic Variables Allowed Endpoints for Passing
Dynamic Variables
Device Pairing otp user.username, user.name.given, user.name.family Yes devices
General None None Yes N/A
ID Verification app.open.url (SMS, Email) user.username, user.name.given, user.name.family Yes verifyTransactions, webVerifications
Password Recovery code.value user.username, user.name.given, user.name.family No N/A
Strong Authentication otp (SMS, Voice, Email) user.username, user.name.given, user.name.family Yes authorize, deviceAuthentications
Transaction otp (SMS, Voice, Email) user.username, user.name.given, user.name.family Yes authorize, deviceAuthentications
Verification Code code.value user.username, user.name.given, user.name.family No N/A

Filtering result data

You can filter GET /environments/{{envID}}/templates and GET /environments/{{envID}}/templates/{{templateName}}/contents 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

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)
  • 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)
Contents collections variant
  • eq (equals)
  • sw (starts with)

Additionally, the logical and and or operators may be used for building 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 descending 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

For more information about SCIM syntax and operators, see Conventions.

Properties

Template Properties

Property Type Required? Mutable? Description
id String Required Immutable The template id.
displayName String Required Mutable The template’s display name.
deliveryMethods Array Required Mutable The delivery methods supported for this template. Valid values are SMS, Voice, Email and Push.
createdAt Date N/A Read only The time the resource was created.
updatedAt Date N/A Read only The time the resource was last updated.
description String Optional Mutable The description of the template.
variables Object Required Mutable Lists the variables you can use in each template content. The required property indicates whether the variable is required in template content. If required is true, the requiredForDeliveryMethods property lists the deliveryMethods types that require the variable. Note that if required is true, but requiredForDeliveryMethods is not returned, all deliveryMethods types are required. For more information, see Variables.
allowDynamicVariables Boolean Required Mutable Specifies whether dynamic variables can be used in the template’s contents. For more information, see Dynamic variables.

Content Properties

Property Type Required? Mutable? Description
id String Required Immutable The template id.
createdAt Date N/A Read only The time the resource was created.
updatedAt Date N/A Read only The time the resource was last updated.
default Boolean Optional Mutable Specifies whether the template is a predefined default template.
locale String Required Immutable 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”.
Cannot be changed after it is initially set in POST /environments/{{envID}}/templates/{{templateName}}/contents.
deliveryMethod String Required Immutable The content’s delivery method. Possible values are Email, SMS, Voice or Push. Cannot be changed after it is initially set in POST /environments/{{envID}}/templates/{{templateName}}/contents.
content String Required/Optional Mutable Only required when deliveryMethod is SMS or Voice. The SMS or voice text.
  • SMS: UC-2 encoding is used for text that contains non GSM-7 characters. UC-2 encoded text cannot exceed 67 characters. GSM-7 encoded text cannot exceed 153 characters. If supported, it can include variables.
  • Voice: Limited to 1Kb characters.
    The following substitution place holders can be embedded in the message:
    • <pause1sec>: Pauses the message narration for 1 second.
      The pause interval <pause1sec> cannot be modified. To pause the message narration for more than one second, repeat multiple <pause1sec> occurrences in succession, according to the desired pause interval duration. For example, <pause1sec><pause1sec><pause1sec> pauses the message narration for three seconds.
    • <sayCharValue> .. </sayCharValue>: Reads the character name of each character of the enclosed string separately.
    • <repeatMessage val=x> .. </repeatMessage>: Narrates the enclosed text <val> number of times.
    In the following message example, ${otp} is assigned the value "123456", and ${email} is assigned the value "joe@bxz.com":
    Hello <pause1sec> your authentication code is 
    <sayCharValue>${otp}</​sayCharValue>
    <repeatMessage val=2> I repeat your code is
    <sayCharValue>${otp}</​sayCharValue>
    </​repeatMessage> <pause1sec>
    Mail <sayCharValue>${email}</​sayCharValue> for help
    The narrated message on the voice call sounds like:
    HELLO <1 second silence> YOUR AUTHENTICATION CODE IS 
    ONE TWO THREE FOUR FIVE SIX
    I REPEAT YOUR CODE IS ONE TWO THREE FOUR FIVE SIX
    I REPEAT YOUR CODE IS ONE TWO THREE FOUR FIVE SIX <1 second silence>
    MAIL JAY OH EE AT BEE EX ZEE DOT SEE OH EM FOR HELP

    Voice OTP supports vendor-specific voices.
    • Supported Twilio voices:
      • Man, Woman
        Supported locales (default: en):
        en, en_GB, es, fr, de
      • Alice (Twilio only)
        Supported locales (default: en US):
        da_DK, de_DE, en_AU, en_CA, en_GB, en_US, ca_ES, es_ES, es_MX, fi_FI, fr_CA, fr_FR, it_IT, ja_JP, ko_KR, nb_NO, nl_NL, pl_PL, pt_BR, pt_PT, ru_RU, sv_SE, zh_CN, zh_HK, zh_TW
      • Amazon Polly
        cy_GB, ro_RO, is_IS, hi_IN tr_TR
    • Supported Syniverse voices:
      • Man, Woman
        Supported locales:
        en_US, en_GB, es_ES, es_US, fr_FR, de_DE, it_IT, en_AU, da_DK, is_IS, nl_NL, pl_PL, pt_BR, pt_PT, ru_RU, ja_JP
      • Woman only
        Supported locales:
        cmn_CN, cy_GB, en_IN, fr_CA, hi_IN, nb_NO, ro_RO, sv_SE, tr_TR, ko_KR, ar
body String Required/Optional Mutable Only required when deliveryMethod is Email or Push. The email or push text (maximum 400 characters for push text). Email text cannot be larger than 100 kB. Email text can contain HTML. If supported, this can include variables.
variant String Optional Mutable Holds the unique user-defined name for each content variant that uses the same template + deliveryMethod + locale combination. This property is case insensitive and has a limit of 100 characters. For more information, see Creating custom contents.
sender String Optional Mutable Relevant when deliveryMethod is SMS. The SMS sender ID. This property can contain only alphanumeric characters and spaces, and its length cannot exceed 11 characters. In some countries, it is impossible to send an SMS with an alphanumeric sender ID. For those countries, the sender ID must be empty. For SMS recipients in specific countries, refer to Twilio’s documentation on International support for Alphanumeric Sender ID.
from.name String Optional Mutable Relevant when deliveryMethod is Email.
The email’s sender name.
If the environment uses the Ping Identity email sender, the name “PingOne” is used.
You can configure other email sender names per environment.
See Note for details.
from.address String Optional Mutable Relevant when deliveryMethod is Email.
The sender email address.
If the environment uses the Ping Identity email sender, or if the address field is empty, the address “noreply@pingidentity.com” is used.
You can configure other email sender addresses per environment.
See Note for details.
subject String Optional Mutable Relevant when deliveryMethod is Email. The email’s subject line. Cannot exceed 256 characters. If supported, can include variables.
replyTo.name String Optional Mutable Relevant when deliveryMethod is Email.
The email’s “reply to” name.
If the environment uses the Ping Identity email sender, the name “PingOne” is used.
You can configure other email “reply to” names per environment.
See Note for details.
replyTo.address String Optional Mutable Relevant when deliveryMethod is Email.
The “reply to” email address.
If the environment uses the Ping Identity email sender, or if the address field is empty, the address “noreply@pingidentity.com” is used.
You can configure other email “reply to” addresses per environment.
See Note for details.
charset String Optional Mutable Relevant when deliveryMethod is Email. If not specified, UTF-8 is the default value.
emailContentType String Optional Mutable Relevant when deliveryMethod is Email. If not specified, text/html is the default value.
title String Optional Mutable Relevant when deliveryMethod is Push. The push title (maximum 200 characters). If supported, this can include variables.

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.