Notification Policies

cooldownConfiguration

Object

Optional

Mutable

Include the cooldownConfiguration object in the request if you want to specify a period of time that users must wait before requesting an additional notification such as an additional OTP.

cooldownConfiguration.email

Object

Required

Mutable

Required if you have included the cooldownConfiguration object. Contains the notification cooldown period settings for email notifications.

cooldownConfiguration.sms

Object

Required

Mutable

Required if you have included the cooldownConfiguration object. Contains the notification cooldown period settings for sms notifications.

cooldownConfiguration.voice

Object

Required

Mutable

Required if you have included the cooldownConfiguration object. Contains the notification cooldown period settings for voice notifications.

cooldownConfiguration.whatsApp

Object

Required

Mutable

Required if you have included the cooldownConfiguration object. Contains the notification cooldown period settings for whatsApp notifications.

cooldownConfiguration.(authentication method).enabled

Boolean

Required

Mutable

Set to true if you want to specify notification cooldown periods for the authentication method. Set to false if you don’t want notification cooldown periods for this authentication method.

cooldownConfiguration.(authentication method).periods

Array

Required/Optional

Mutable

Required if cooldownConfiguration.(authentication method).enabled is true. Use the periods array to specify the amount of time the user has to wait before requesting another notification such as another OTP. The array should contain three objects: the time to wait before the first retry, the time to wait before the second retry, and the time to wait before any subsequent retries.

cooldownConfiguration.(authentication method).periods[].duration

Integer

Required/Optional

Mutable

Required if cooldownConfiguration.(authentication method).enabled is true. Used in conjunction with timeUnit to specify the waiting period. Minimum is ten seconds, maximum is ten minutes.

cooldownConfiguration.(authentication method).periods[].timeUnit

String

Required/Optional

Mutable

Required if cooldownConfiguration.(authentication method).enabled is true. Used in conjunction with duration to specify the waiting period. Can be set to SECONDS or MINUTES.

cooldownConfiguration.(authentication method).groupBy

String

Optional

Mutable

Since bad actors may try to target multiple users at a single email address or phone number, by default the cooldown settings (both waiting period and maximum retries) are applied to the email address or phone number. If you want the settings to be applied at the single-user level for the address/number, include the groupBy parameter in the request and set it to USER_ID.

cooldownConfiguration.(authentication method).resendLimit

Integer

Required/Optional

Mutable

Required if cooldownConfiguration.(authentication method).enabled is true. The maximum number of requests that a user can send to receive another notification, such as another OTP, before they are blocked for 30 minutes.

countryLimit

Object

Optional

Mutable

You can use the countryLimit object to limit the countries where you can send SMS and voice notifications.

countryLimit.type

String

Required/Optional

Mutable

Determines the kind of limitation being defined. The possible values are

* NONE

* ALLOWED - allows SMS/Voice notifications only for the countries specified with countryLimit.countries

* DENIED - denies SMS/Voice notifications for the countries specified with countryLimit.countries

countryLimit.deliveryMethods

Array

Optional

Mutable

The delivery methods that the defined limitation should be applied to. Content of the array can be SMS, Voice, or both. If the parameter is not provided, the default is SMS and Voice.

countryLimit.countries

Array

Required/Optional

Mutable

The countries where the specified methods should be allowed or denied. Use the two-letter country codes from ISO 3166-1.

createdAt

Date

N/A

Read-only

The date and time the notification policy was created.

default

Boolean

Optional

Mutable

Indication of whether this policy is the default notification policy for the environment. If the parameter is not provided, the value used is false

environment.id

String

N/A

Read-only

The ID of the PingOne environment that contains the notification policy.

id

String

N/A

Read-only

The ID generated for the notification policy when it was created.

name

String

Required

Mutable

The name to use for the notification policy. Must be unique among the notification policies in the environment.

providerConfiguration

Object

Optional

Mutable

If you have defined more than one custom provider, you can use the providerConfiguration object to specify the provider preference to use for different countries and for the different methods (SMS and Voice).

providerConfiguration.conditions

Array

Optional

Mutable

Each element in the conditions array represents the provider fallback order to use for a specific group of countries for the specified methods (SMS and/or Voice). Note that in addition to any country-specific orders specified, the array must contain a fallback order without the countries array in the object. This order is used for all countries that were not specified in one of the other fallback orders defined.

providerConfiguration.conditions[].deliveryMethods

Array

Optional

Mutable

The authentication methods that the fallback order should be used for. The array can contain VOICE, SMS, or both.

providerConfiguration.conditions[].countries

Array

Optional

Mutable

The countries for which the fallback order should be used. Use the two-letter country codes from ISO 3166-1.

providerConfiguration.conditions[].fallbackChain

Array

Optional

Mutable

An array containing the IDs of the defined custom providers, in the order that they should be used if available.

providerConfiguration.conditions[].fallbackChain.id

String

Optional

Mutable

The ID of one of the defined custom providers. This is the ID that is returned when you create the provider using the phoneDeliverySettings endpoint or when you run the GET request with that endpoint to retrieve the details of all the providers.

quotas

Array

Required

Mutable

Collection of objects that define the SMS/voice and email limits. Each object contain the following elements: type, deliveryMethods, total. Note that instead of total, you can use the pair of fields: claimed and unclaimed.

quotas[].type

String

Required

Mutable

Specifies whether the limit defined is per-user or per environment. Value must be either USER or ENVIRONMENT.

quotas[].deliveryMethods

Array

Required

Mutable

The delivery methods for which the limit is being defined. The value can be Email or SMS,Voice. When you use the SMS, Voice option, it means that the combined total of SMS and voice notifications must be below the limit defined. If you are limiting both email and SMS/voice, each limit should be represented by a different object in the quotas array, for example:
"quotas": [{"type": "USER","deliveryMethods": ["SMS","Voice"],"total": 30},{"type": "USER","deliveryMethods": ["Email"],"total": 30}]

quotas[].total

Integer

Required/Optional

Mutable

The maximum number of notifications allowed per day.

quotas[].claimed

Integer

Required/Optional

Mutable

The maximum number of notifications that can be received and responded to each day. Used in conjunction with unclaimed in place of the single field total.

quotas[].unclaimed

Integer

Required/Optional

Mutable

The maximum number of notifications that can be received and not responded to each day. Used in conjunction with claimed in place of the single field total.

updatedAt

Date

N/A

Read-only

The date and time the notification policy was last updated.