PingOne Platform APIs

Notifications Settings

The notifications settings endpoints provide the ability to configure specific notifications settings for each environment. They implement operations to read, update and reset the settings for the environment.

You need the Environment Admin role to perform operations on notifications settings resources.

Configure an SMS/Voice provider fallback chain

The sequence of SMS/Voice providers in smsProvidersFallbackChain comprises the notification fallback sequence, in the event of a primary or subsequent provider failing to send the notification.

  1. The providers must be configured in the Phone Delivery Settings resource.

  2. Update the notifications setting resource by using the PUT {{apiPath}}/v1/environments/{{envID}}/notificationsSettings/ operation. For example, to define your own provider (represented here as TwilioPhoneDeliverySettingsId) as the primary provider, and Ping’s Twilio account as the fallback:

    {
 "smsProvidersFallbackChain": [ "TwilioPhoneDeliverySettingsId", "PINGONE_TWILIO" ]
}

Notifications settings properties

Property Type Required Mutable Description

emailProviderFallbackChain

Array

Optional

Mutable

For email notifications, you can use the Ping server or a customer server/provider that you have defined. If you defined a custom server/provider and want to switch to the Ping server, send an update request and include the emailProviderFallbackChain array with the single value PINGONE_EMAIL. To switch back to your custom server/provider, send an update request and include emailProviderFallbackChain as an empty array.

environment.id

String

Required

Immutable

The environment resource’s unique identifier.

from.name

String

Optional

Mutable

The email’s "from" name.
Refer to Note for details.

from.address

String

Optional

Mutable

The email’s "from" address. This value must be a trusted email address.
Refer to Note for details.

replyTo.name

String

Optional

Mutable

The email’s "reply to" name.
Refer to Note for details.

replyTo.address

String

Optional

Mutable

The email’s "reply to" address. This value must be a trusted email address.
Refer to Note for details.

smsProvidersFallbackChain

Array

Optional

Mutable

A comma-separated list that represents the execution order of different SMS/Voice providers configured for the environment. The providers and their accounts' configurations are represented in the list by the ID of the corresponding PhoneDeliverySettings resource. The only provider which is not represented by a PhoneDeliverySettingsId is the PingOne Twilio provider. The PingOne Twilio provider is represented by the "PINGONE_TWILIO" string. If the smsProvidersFallbackChain list is empty, an SMS or voice message will be sent using the default Ping Twilio account. Otherwise, an SMS or voice message will be sent using the first provider in the list. If the server fails to queue the message using that provider, it will use the next provider in the list to try to send the message. This process will go on until there are no more providers in the list. If the server failed to send the message using all providers, the notification status is set to FAILED.

updatedAt

Date

N/A

Read-Only

The time the resource was last updated.

  • If the environment is configured to use the Ping Identity email sender, only trusted email addresses can be used for from.address and replyTo.address.

  • If the from or replyTo settings are not defined in the content or in notificationsSettings, PingOne uses the default from.name (PingOne) and from.address (noreply@pingidentity.com), and replyTo.name and replyTo.address are not populated.

  • When switching the configuration from a custom email sender to to use the Ping Identity email sender, any untrusted email address that is configured for existing contents is ignored and PingOne uses the trusted address that’s defined in notificationsSettings.

Notifications settings events generated

Refer to Audit Reporting Events for the events generated.

Notifications settings response codes

Code Message

200

Successful operation.

201

Successfully created.

400

The request could not be completed.

401

You do not have access to this resource.

403

You do not have permissions or are not licensed to make this request.

404

The requested resource was not found.

Notifications settings errors

In addition to the general error codes, notifications settings operations can return the following errors:

HTTP status Top‑level code Detail code When it happens and what the response contains

400

INVALID_DATA

EMPTY_VALUE or INVALID_VALUE

Message: Validation Error : [<field> <message>] (for example, Validation Error : [whitelist size must be between 0 and 50], or for defaultLanguage, the message is:)

Validation Error : [defaultLanguage must be a valid language tag that is a sequence of one or more case-insensitive sub-tags, each separated by a hyphen (e.g. fr, en-US, es-419, az-Arab, x-pig-latin, man-Nkoo-GN)]
When and details

When: A PUT Update Notifications Settings request body fails constraint validation (for example, the whitelist array has more than 50 entries, or defaultLanguage is not a valid locale tag).

Details: Per violated constraint: detail EMPTY_VALUE for NotNull or NotEmpty constraints, OUT_OF_RANGE for Size constraints (with rangeMinimumValue and rangeMaximumValue in innerError), INVALID_VALUE otherwise, target = the field path, message = the constraint message.

400

INVALID_REQUEST

INVALID_VALUE or None

Message: The request could not be completed. The request was malformed or invalid.

When and details

When: A PUT Update Notifications Settings request body is malformed JSON or contains a value of the wrong type (for example, a non-UUID entry in the whitelist array).

Details: For a JSON field conversion error, detail INVALID_VALUE with target = the JSON path of the failing property and message Invalid value for attribute. Otherwise no detail is returned.

404

NOT_FOUND

None

Message: The request could not be completed. The requested resource was not found.

When and details

When: A PUT Update Notifications Settings request sets from.address or replyTo.address to an address whose domain is not a trusted email domain in the environment (when the environment uses the Ping Identity email sender).

Details: An un-coded detail carrying the message Trusted email domain not found in the environment: <address>

400

REQUEST_FAILED

None

Message: The request violates a constraint imposed by the service.

When and details

When: A PUT Update Notifications Settings request sets from.address or replyTo.address to a trusted email address that exists but is not yet verified.

Details: An un-coded detail carrying the message Trusted email is not active and requires verification: <address>

400

INVALID_DATA

INVALID_VALUE

Message: The request could not be completed. One or more validation errors were in the request.

When and details

When: A PUT Update Notifications Settings request sets smsProvidersFallbackChain to an ID that does not match a Phone Delivery Settings resource in the environment (a value other than PINGONE_TWILIO).

Details: Detail INVALID_VALUE with message PhoneDeliverySettings resource not found, id=<id>.

400

INVALID_DATA

INVALID_VALUE

Message: The request could not be completed. One or more validation errors were in the request.

When and details

When: A PUT Update Notifications Settings request sets emailProviderFallbackChain to more than one value, or to a value other than PINGONE_EMAIL.

Details: Detail INVALID_VALUE with target emailProviderFallbackChain and message Only one email provider fallback is allowed at the moment or Only PINGONE_EMAIL is allowed as email provider fallback at the moment.

400

REQUEST_FAILED

CONSTRAINT_VIOLATION

Message: The request could not be completed. There was an issue processing the request.

When and details

When: A PUT Update Notifications Settings request is submitted while a PingID-to-PingOne deployment is in process for the environment (and the actor is not a platform client).

Details: Detail CONSTRAINT_VIOLATION with message:

The notifications settings could not be updated because a deployment of PingID to PingOne is also in process. Try again in a few minutes.

(the source message has a trailing space after the final period)

403

ACCESS_FAILED

LICENSE_EXCEEDED

Message: The request exceeded your license limit.

When and details

When: A PUT Update Notifications Settings request includes PINGONE_TWILIO in smsProvidersFallbackChain for an environment whose license does not include the Ping SMS account capability.

Details: Detail LICENSE_EXCEEDED with message Fallback to Ping phone providers isn’t allowed for environment=<environmentId>.

403

ACCESS_FAILED

None

Message: The actor attempting to perform the request is not authorized.

When and details

When: The actor lacks the permission for the operation: notifications:read:notificationsSettings (GET Read Notifications Settings), notifications:update:notificationsSettings (PUT Update Notifications Settings), or notifications:delete:notificationsSettings (DELETE Reset Notifications Settings).

Details: None.

404

NOT_FOUND

None

Message: The request could not be completed. The requested resource was not found.

When and details

When: A request specifies an environment that does not exist.

Details: None.

404

NOT_FOUND

None

Message: The request could not be completed. The requested resource was not found.

When and details

When: A PUT Update Notifications Settings request includes a whitelist entry whose user.id does not exist in the environment.

Details: None.