--- title: Notification Policies description: You can define notification policies to limit the use of SMS/voice and email notifications for pairing and authentication. component: pingone-api page_id: pingone-api:platform:notifications/notification-policies canonical_url: https://developer.pingidentity.com/pingone-api/platform/notifications/notification-policies.html section_ids: parameters-for-creatingupdating-notification-policies: Parameters for creating/updating notification policies notification-policy-events-generated: Notification Policy events generated --- # Notification Policies You can define notification policies to limit the use of SMS/voice and email notifications for pairing and authentication. ## Parameters for creating/updating notification policies | Property | Type | Required? | Mutable? | Description | | ------------------------------------------------------------------ | ------- | ----------------- | --------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `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. | When you create/update a notification policy, the response also includes the following information: * `id` - the ID assigned to the notification policy * `createdAt` - date and time when the policy was created * `updatedAt` - date and time when the policy was updated ## Notification Policy events generated Refer to [Audit Reporting Events](../reference/audit-reporting-events.html) for the events generated.