Phone Delivery Settings

The phone delivery settings endpoints provide the ability to configure different accounts which could be used for sending an SMS or voice message. They implement operations to create, update, read and delete phone delivery settings resources for an environment.

You need the Environment Admin role to perform operations on phone delivery settings resources.
You can configure up to a maximum of 10 phone delivery settings per environment.

Phone delivery settings properties

Property Type Required Mutable Description

Property	Type	Required	Mutable	Description
`createdAt`	Date	N/A	Read-only	The time the resource was created.
`environment.id`	String	Required	Immutable	The relationship of the phone delivery settings to the environment.
`id`	String	Required	Immutable	The auto-generated ID of the phone delivery settings.
`provider`	String	Required	Immutable	The provider to use for phone delivery service. Possible values: * `CUSTOM_SYNIVERSE`: Use to send notifications via your Syniverse account. * `CUSTOM_SYNIVERSE_CHANNELS`: Use to send notifications via a Syniverse account that has defined channels. * `CUSTOM_TWILIO`: Uses the default PingOne provider (Twilio / Vonage) as the SMS/voice provider. * `CUSTOM_TWILIO_VERIFY`: Uses Twilio Verify. * `CUSTOM_TWILIO_MESSAGING_SERVICE`: Use to send notifications via a specific messaging service that you defined in your Twilio account. * `CUSTOM_PROVIDER`: Uses the custom SMS provider that you defined (if you want to use a provider other than the default PingOne provider or Syniverse).
`updatedAt`	Date	N/A	Read-only	The time the resource was last updated.

createdAt

Date

N/A

Read-only

The time the resource was created.

environment.id

String

Required

Immutable

The relationship of the phone delivery settings to the environment.

id

String

Required

Immutable

The auto-generated ID of the phone delivery settings.

provider

String

Required

Immutable

The provider to use for phone delivery service. Possible values:

* CUSTOM_SYNIVERSE: Use to send notifications via your Syniverse account.

* CUSTOM_SYNIVERSE_CHANNELS: Use to send notifications via a Syniverse account that has defined channels.

* CUSTOM_TWILIO: Uses the default PingOne provider (Twilio / Vonage) as the SMS/voice provider.

* CUSTOM_TWILIO_VERIFY: Uses Twilio Verify.

* CUSTOM_TWILIO_MESSAGING_SERVICE: Use to send notifications via a specific messaging service that you defined in your Twilio account.

* CUSTOM_PROVIDER: Uses the custom SMS provider that you defined (if you want to use a provider other than the default PingOne provider or Syniverse).

updatedAt

Date

N/A

Read-only

The time the resource was last updated.

Custom provider phone delivery settings properties (Twilio or Syniverse)

The phoneDeliverySettings instance that supports your Twilio or Syniverse custom provider phone delivery accounts.

Property Type Required Mutable Description

Property	Type	Required	Mutable	Description
`authToken`	String	Required	Immutable	The secret key of the Twilio or Syniverse account.
`channels`	Array	Required	Mutable	Contains the information about the channels defined in your Syniverse account. Returned when you create a Syniverse Channels sender and must be included when sending the PUT request to select one of the channels in the account.
`channels.available`	Boolean	Required	Immutable	Indication of whether the channel is still available for use in the Syniverse account.
`channels.capabilities`	Array	Required	Immutable	The capabilities defined for the channel in Syniverse, for example, `SMS` or `VOICE`.
`channels.createdAt`	Date	Required	Immutable	The date the Syniverse Channels sender was created in PingOne.
`channels.id`	String	Required	Immutable	The Syniverse ID for the channel.
`channels.name`	String	Required	Immutable	The name of the channel.
`channels.priority`	String	Required	Immutable	The priority set for the channel in Syniverse.
`channels.selected`	Boolean	Required	Mutable	Set to `true` for the channel you want to use for sending notifications. Note that for each sender you define, only one channel can be set to `true`.
`deliveryConfigurationsExist`	Boolean	Required	Immutable	Indication of whether the Syniverse account has a delivery configuration (webhook) defined for your PingOne environment. Returned when you create the sender and must be included when sending the PUT request to select one of the channels in the account. To include Syniverse notification events in the PingOne audit logs, you must define a webhook with the relevant PingOne callback URL.
`messagingServices`	Array	Required	Mutable	Contains the information about the messaging services defined in your Twilio account. Returned when you create a Twilio Messaging Services SID sender and must be included when sending the PUT request to select one of the messaging services in the account.
`messagingServices.messagingServiceId`	String	Required	Immutable	The ID of the messaging service.
`messagingServices.name`	String	Required	Immutable	The name of the messaging service.
`messagingServices.selected`	Boolean	Required	Mutable	Set to `true` for the specific Twilio messaging service you want to use for sending notifications. Note that for each sender you define, only one messaging service can be set to `true`.
`name`	String	Optional	Mutable	The name you want to use for the provider.
`numbers`	Array	Required	Mutable	A collection of Twilio or Syniverse numbers to use when sending a notification. The array uses the properties in the Custom provider phone number properties data model. If left blank, returns the numbers from the Twilio or Syniverse service. Not relevant when using a Syniverse Channels sender.
`sid`	String	Required	Immutable	The public ID of the Twilio account. Relevant to Twilio only.
`smsTopicSubscription`	Object	Required	Immutable	If the Syniverse account has a delivery configuration (webhook) defined for your PingOne environment, `smsTopicSubscription` contains the SMS subscription information. Returned when you create the sender and must be included when sending the PUT request to select one of the channels in the account.
`smsTopicSubscription.subscribed`	Boolean	Required	Immutable	Indicates that the webhook includes a subscription for SMS messages.
`smsTopicSubscription.startDateStr`	Date	Required	Immutable	Start date for the SMS subscription.
`verifyServiceId`	String	Optional	Mutable	The Twilio Verify service ID. Required when you are using Twilio Verify.
`voiceTopicSubscription`	Object	Required	Immutable	If the Syniverse account has a delivery configuration (webhook) defined for your PingOne environment, `voiceTopicSubscription` contains the voice subscription information. Returned when you create the sender and must be included when sending the PUT request to select one of the channels in the account.
`voiceTopicSubscription.subscribed`	Boolean	Required	Immutable	Indicates that the webhook includes a subscription for voice messages.
`voiceTopicSubscription.startDateStr`	Date	Required	Immutable	Start date for the voice subscription.

authToken

String

Required

Immutable

The secret key of the Twilio or Syniverse account.

channels

Array

Required

Mutable

Contains the information about the channels defined in your Syniverse account. Returned when you create a Syniverse Channels sender and must be included when sending the PUT request to select one of the channels in the account.

channels.available

Boolean

Required

Immutable

Indication of whether the channel is still available for use in the Syniverse account.

channels.capabilities

Array

Required

Immutable

The capabilities defined for the channel in Syniverse, for example, SMS or VOICE.

channels.createdAt

Date

Required

Immutable

The date the Syniverse Channels sender was created in PingOne.

channels.id

String

Required

Immutable

The Syniverse ID for the channel.

channels.name

String

Required

Immutable

The name of the channel.

channels.priority

String

Required

Immutable

The priority set for the channel in Syniverse.

channels.selected

Boolean

Required

Mutable

Set to true for the channel you want to use for sending notifications. Note that for each sender you define, only one channel can be set to true.

deliveryConfigurationsExist

Boolean

Required

Immutable

Indication of whether the Syniverse account has a delivery configuration (webhook) defined for your PingOne environment. Returned when you create the sender and must be included when sending the PUT request to select one of the channels in the account. To include Syniverse notification events in the PingOne audit logs, you must define a webhook with the relevant PingOne callback URL.

messagingServices

Array

Required

Mutable

Contains the information about the messaging services defined in your Twilio account. Returned when you create a Twilio Messaging Services SID sender and must be included when sending the PUT request to select one of the messaging services in the account.

messagingServices.messagingServiceId

String

Required

Immutable

The ID of the messaging service.

messagingServices.name

String

Required

Immutable

The name of the messaging service.

messagingServices.selected

Boolean

Required

Mutable

Set to true for the specific Twilio messaging service you want to use for sending notifications. Note that for each sender you define, only one messaging service can be set to true.

name

String

Optional

Mutable

The name you want to use for the provider.

numbers

Array

Required

Mutable

A collection of Twilio or Syniverse numbers to use when sending a notification. The array uses the properties in the Custom provider phone number properties data model. If left blank, returns the numbers from the Twilio or Syniverse service. Not relevant when using a Syniverse Channels sender.

sid

String

Required

Immutable

The public ID of the Twilio account.
Relevant to Twilio only.

smsTopicSubscription

Object

Required

Immutable

If the Syniverse account has a delivery configuration (webhook) defined for your PingOne environment, smsTopicSubscription contains the SMS subscription information. Returned when you create the sender and must be included when sending the PUT request to select one of the channels in the account.

smsTopicSubscription.subscribed

Boolean

Required

Immutable

Indicates that the webhook includes a subscription for SMS messages.

smsTopicSubscription.startDateStr

Date

Required

Immutable

Start date for the SMS subscription.

verifyServiceId

String

Optional

Mutable

The Twilio Verify service ID. Required when you are using Twilio Verify.

voiceTopicSubscription

Object

Required

Immutable

If the Syniverse account has a delivery configuration (webhook) defined for your PingOne environment, voiceTopicSubscription contains the voice subscription information. Returned when you create the sender and must be included when sending the PUT request to select one of the channels in the account.

voiceTopicSubscription.subscribed

Boolean

Required

Immutable

Indicates that the webhook includes a subscription for voice messages.

voiceTopicSubscription.startDateStr

Date

Required

Immutable

Start date for the voice subscription.

Custom provider phone delivery settings properties (excluding Twilio and Syniverse)

The phoneDeliverySettings instance that supports your custom provider phone delivery accounts (excluding Twilio and Syniverse).

Property Type Required Mutable Description

Property	Type	Required	Mutable	Description
`authentication`	Object	Required	Mutable	Contains the information for authenticating with the provider.
`authentication.assertion`	String	Required	Mutable	The assertion to use if `authentication.grantType` is set to `JWT_BEARER`. Must be a valid JWT.
`authentication.authToken`	String	Required	Mutable	The authentication token for the custom provider account. Required when `authentication.method`=`BEARER`
`authentication.authUrl`	String	Required	Mutable	The URL of the authorization server that provides the access token. Required when `authentication.method`=`OAUTH2`
`authentication.clientAuthenticationMethod`	String	N/A	Read-only	The method used for sending credentials for OAuth2. Returned in responses for custom providers that require OAuth 2 authentication. For client ID/secret-based authentication, the value returned is `BASIC_AUTH_HEADER`. For JWT-based authentication, the value returned is `BODY`.
`authentication.clientId`	String	Required	Mutable	The client’s public identifier. Required when `authentication.grantType` is set to `CLIENT_CREDENTIALS`.
`authentication.clientSecret`	String	Required	Mutable	The client’s secret. Required when `authentication.grantType` is set to `CLIENT_CREDENTIALS`.
`authentication.grantType`	String	Optional	Mutable	The grant type used. Relevant for custom providers that require OAuth 2 authentication. Set to `JWT_BEARER` for JWT-based authentication, and to `CLIENT_CREDENTIALS` for authentication based on client ID and secret. If not specified in the request, the default value is `CLIENT_CREDENTIALS`.
`authentication.headerName`	String	Required	Mutable	The name of the custom header used for authentication. Required when `authentication.method`=`CUSTOM_HEADER`
`authentication.headerValue`	String	Required	Mutable	The value to use for the custom header used for authentication. Required when `authentication.method`=`CUSTOM_HEADER`
`authentication.method`	String	Required	Mutable	The custom provider account’s authentication method. Possible values: * BASIC - username/password * BEARER - bearer token * OAUTH2 - OAuth 2 * CUSTOM_HEADER - authentication using a custom header
`authentication.password`	String	Required	Mutable	The password for the custom provider account. Required when `authentication.method`=`BASIC`
`authentication.scopes`	Array	Optional	Mutable	When `authentication.method` is set to OAUTH2, use `scopes` to specify the capabilities that the issued token should have, for example, `["sms:send", "voice:send"]`.
`authentication.username`	String	Required	Mutable	The username for the custom provider account. Required when `authentication.method`=`BASIC`
`name`	String	Required	Mutable	The name you want to use for the provider.
`numbers`	Array	Required	Mutable	A collection of Twilio or Syniverse numbers to use when sending a notification. The array uses the properties in the Custom provider phone number properties data model.
`requests.afterTag`	String	Optional	Mutable	For voice OTP notifications only. A closing tag which is commonly used by custom providers for defining a pause between each number in the OTP number string. Possible value: `</Say> <Pause length="1"/>`
`requests.beforeTag`	String	Optional	Mutable	For voice OTP notifications only. An opening tag which is commonly used by custom providers for defining a pause between each number in the OTP number string. Possible value: `<Say>`
`requests.body`	String	Optional	Mutable	The notification’s request body. This property is required when `requests.method` is set to `POST`. The body must include the mandatory `${to}` and `${message}` variables. If your provider’s API requires that the phone number be split into the country code and the rest of the number, you can use `${to.country-code}` and `${to.national-number}` instead of `${to}`. The `${from}` variable is required if the `numbers` attribute is set, and any object in the `number` array is selected. For example: `messageType=ARN&message=${message}&phoneNumber=${to}&sender=${from}` In addition, you can use the following optional variables: `${voice}` - the type of voice configured for notifications `${locale}` - locale `${OTP}` - OTP `${user.user.name}` - user’s username `${user.name.given}` - user’s given name `${user.name.family}` - user’s family name You can also use dynamic variables in the body. For more information, refer to Dynamic variables.
`requests.deliveryMethod`	String	Required	Mutable	The notification’s delivery method. Possible value: `SMS` `VOICE`
`requests.headers`	String[]	Optional	Mutable	The notification’s request header, matching the format of the request body. When the `request.method` value is `POST`, it can be one of: Form `(content-type=application/x-www-form-urlencoded)` JSON `(content-type=application/json)` Otherwise, custom header values are also allowed.
`requests.method`	String	Required	Mutable	The type of HTTP request method. Possible values: `GET` `POST`
`requests.phoneNumberFormat`	String	Required	Mutable	The phone number format. Possible values: `FULL` (default) The phone number format with a leading ` sign, in the E.164 standard format. For example: `14155552671` `NUMBER_ONLY` The phone number format without a leading ` sign, in the E.164 standard format. For example: `14155552671`
`requests.url`	String	Required	Mutable	The provider’s remote gateway or customer gateway URL. For requests using the `POST` method, use the provider’s remote gateway URL. For requests using the `GET` method, use the provider’s remote gateway URL, and include the mandatory `${to}` and `${message}` variables. If your provider’s API requires that the phone number be split into the country code and the rest of the number, you can use `${to.country-code}` and `${to.national-number}` instead of `${to}`. The `${from}` variable is required if the `numbers` attribute is set, and any object in the `number` array is selected. For example: `https://api.transmitsms.com/send-sms.json?to=${to}&from=${from}&message=${message}"`

authentication

Object

Required

Mutable

Contains the information for authenticating with the provider.

authentication.assertion

String

Required

Mutable

The assertion to use if authentication.grantType is set to JWT_BEARER. Must be a valid JWT.

authentication.authToken

String

Required

Mutable

The authentication token for the custom provider account.
Required when authentication.method=BEARER

authentication.authUrl

String

Required

Mutable

The URL of the authorization server that provides the access token.
Required when authentication.method=OAUTH2

authentication.clientAuthenticationMethod

String

N/A

Read-only

The method used for sending credentials for OAuth2. Returned in responses for custom providers that require OAuth 2 authentication. For client ID/secret-based authentication, the value returned is BASIC_AUTH_HEADER. For JWT-based authentication, the value returned is BODY.

authentication.clientId

String

Required

Mutable

The client’s public identifier.
Required when authentication.grantType is set to CLIENT_CREDENTIALS.

authentication.clientSecret

String

Required

Mutable

The client’s secret.
Required when authentication.grantType is set to CLIENT_CREDENTIALS.

authentication.grantType

String

Optional

Mutable

The grant type used. Relevant for custom providers that require OAuth 2 authentication. Set to JWT_BEARER for JWT-based authentication, and to CLIENT_CREDENTIALS for authentication based on client ID and secret. If not specified in the request, the default value is CLIENT_CREDENTIALS.

authentication.headerName

String

Required

Mutable

The name of the custom header used for authentication.
Required when authentication.method=CUSTOM_HEADER

authentication.headerValue

String

Required

Mutable

The value to use for the custom header used for authentication.
Required when authentication.method=CUSTOM_HEADER

authentication.method

String

Required

Mutable

The custom provider account’s authentication method. Possible values:

* BASIC - username/password

* BEARER - bearer token

* OAUTH2 - OAuth 2

* CUSTOM_HEADER - authentication using a custom header

authentication.password

String

Required

Mutable

The password for the custom provider account.
Required when authentication.method=BASIC

authentication.scopes

Array

Optional

Mutable

When authentication.method is set to OAUTH2, use scopes to specify the capabilities that the issued token should have, for example, ["sms:send", "voice:send"].

authentication.username

String

Required

Mutable

The username for the custom provider account.
Required when authentication.method=BASIC

name

String

Required

Mutable

The name you want to use for the provider.

numbers

Array

Required

Mutable

A collection of Twilio or Syniverse numbers to use when sending a notification. The array uses the properties in the Custom provider phone number properties data model.

requests.afterTag

String

Optional

Mutable

For voice OTP notifications only.
A closing tag which is commonly used by custom providers for defining a pause between each number in the OTP number string.
Possible value: </Say> <Pause length="1"/>

requests.beforeTag

String

Optional

Mutable

For voice OTP notifications only.
An opening tag which is commonly used by custom providers for defining a pause between each number in the OTP number string.
Possible value: <Say>

requests.body

String

Optional

Mutable

The notification’s request body. This property is required when requests.method is set to POST. The body must include the mandatory ${to} and ${message} variables. If your provider’s API requires that the phone number be split into the country code and the rest of the number, you can use ${to.country-code} and ${to.national-number} instead of ${to}. The ${from} variable is required if the numbers attribute is set, and any object in the number array is selected. For example:
messageType=ARN&message=${message}&phoneNumber=${to}&sender=${from}
In addition, you can use the following optional variables:

${voice} - the type of voice configured for notifications
${locale} - locale
${OTP} - OTP
${user.user.name} - user’s username
${user.name.given} - user’s given name
${user.name.family} - user’s family name

You can also use dynamic variables in the body. For more information, refer to Dynamic variables.

requests.deliveryMethod

String

Required

Mutable

The notification’s delivery method. Possible value:

SMS
VOICE

requests.headers

String[]

Optional

Mutable

The notification’s request header, matching the format of the request body. When the request.method value is POST, it can be one of:

Form
(content-type=application/x-www-form-urlencoded)
JSON
(content-type=application/json)

Otherwise, custom header values are also allowed.

requests.method

String

Required

Mutable

The type of HTTP request method. Possible values:

GET
POST

requests.phoneNumberFormat

String

Required

Mutable

The phone number format. Possible values:

FULL (default)
The phone number format with a leading ` sign, in the E.164 standard format.
For example: 14155552671
NUMBER_ONLY
The phone number format without a leading ` sign, in the E.164 standard format.
For example: 14155552671

requests.url

String

Required

Mutable

The provider’s remote gateway or customer gateway URL.

For requests using the POST method, use the provider’s remote gateway URL.
For requests using the GET method, use the provider’s remote gateway URL, and include the mandatory ${to} and ${message} variables. If your provider’s API requires that the phone number be split into the country code and the rest of the number, you can use ${to.country-code} and ${to.national-number} instead of ${to}. The ${from} variable is required if the numbers attribute is set, and any object in the number array is selected. For example:
https://api.transmitsms.com/send-sms.json?to=${to}&from=${from}&message=${message}"

We add a Correlation-Id setting in the header of the request to the custom provider. You can track notifications sent by the custom provider using the Correlation-Id value.

Custom provider phone number properties

Property Type Required Mutable Description

Property	Type	Required	Mutable	Description
`available`	Boolean	Required	Mutable	Specifies whether the number is currently available in the provider account.
`capabilities`	String[]	Required	Mutable	A collection of the phone delivery service capabilities. Possible values: `VOICE`, `SMS`. Refer to the Phone delivery capabilities properties data model.
`number`	String	Required	Mutable	The phone number, toll-free number or short code.
`selected`	Boolean	Required	Mutable	Specifies whether the number is selected by the admin for sending messages.
`supportedCountries`	String[]	Required	Mutable	Specifies the number’s supported countries for notification recipients, depending on the phone number `type: * `SHORT_CODE`: A collection containing a single 2-character ISO country code, for example, `US`, `GB`, `CA`. If the custom provider is of `type=CUSTOM_PROVIDER`, supportedCountries must not be empty or null. For other custom provider types, if `supportedCountries` is null (empty is not supported), the specified short code `number` can only be used to dispatch notifications to United States recipient numbers. * `TOLL_FREE`: A collection of valid 2-character country ISO codes, for example, `US`, `GB`, `CA`. If the custom provider is of `type=CUSTOM_PROVIDER`, supportedCountries must not be empty or null. For other custom provider types, if `supportedCountries` is null (empty is not supported), the specified toll-free `number` can only be used to dispatch notifications to United States recipient numbers. * `PHONE_NUMBER`: `supportedCountries` can not be specified. If an SMS template has an alphanumeric `sender` ID and also has short code, the `sender` ID will be used for destination countries that support both alphanumeric senders and short codes. For Unites States and Canada that don’t support alphanumeric sender IDs, a short code will be used if both an alphanumeric sender and a short code are specified.
`type`	String	Required	Mutable	The type of phone number. Possible values: `SHORT_CODE`, `TOLL_FREE`, `PHONE_NUMBER`

available

Boolean

Required

Mutable

Specifies whether the number is currently available in the provider account.

capabilities

String[]

Required

Mutable

A collection of the phone delivery service capabilities. Possible values: VOICE, SMS. Refer to the Phone delivery capabilities properties data model.

number

String

Required

Mutable

The phone number, toll-free number or short code.

selected

Boolean

Required

Mutable

Specifies whether the number is selected by the admin for sending messages.

supportedCountries

String[]

Required

Mutable

Specifies the number’s supported countries for notification recipients, depending on the phone number `type:

* SHORT_CODE: A collection containing a single 2-character ISO country code, for example, US, GB, CA.
If the custom provider is of type=CUSTOM_PROVIDER, supportedCountries must not be empty or null.
For other custom provider types, if supportedCountries is null (empty is not supported), the specified short code number can only be used to dispatch notifications to United States recipient numbers.

* TOLL_FREE: A collection of valid 2-character country ISO codes, for example, US, GB, CA.
If the custom provider is of type=CUSTOM_PROVIDER, supportedCountries must not be empty or null.
For other custom provider types, if supportedCountries is null (empty is not supported), the specified toll-free number can only be used to dispatch notifications to United States recipient numbers.

* PHONE_NUMBER: supportedCountries can not be specified.

If an SMS template has an alphanumeric sender ID and also has short code, the sender ID will be used for destination countries that support both alphanumeric senders and short codes. For Unites States and Canada that don’t support alphanumeric sender IDs, a short code will be used if both an alphanumeric sender and a short code are specified.

type

String

Required

Mutable

The type of phone number. Possible values: SHORT_CODE, TOLL_FREE, PHONE_NUMBER

Phone delivery capabilities properties

Property Type Required Mutable Description

Property	Type	Required	Mutable	Description
`capability`	String	Required	Mutable	The type of phone delivery service capability. Possible values: `VOICE`, `SMS`.

capability

String

Required

Mutable

The type of phone delivery service capability. Possible values: VOICE, SMS.

Phone delivery events generated

Refer to Audit Reporting Events for the events generated.

Phone delivery 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.

Configure your custom phone delivery vendor account (Twilio or Syniverse)

Create a custom Twilio or Syniverse phone delivery settings resource using the POST {{apiPath}}/v1/environments/{{envID}}/notificationsSettings/phoneDeliverySettings operation. Twilio:
```
{
  "sid": "someSid",
  "authToken": "someAuthToken",
  "provider": "CUSTOM_TWILIO"
}
```
For Syniverse, remove the sid property in the above example, and set "provider": "CUSTOM_SYNIVERSE".

Use the PUT {{apiPath}}/v1/environments/{{envID}}/notificationsSettings/phoneDeliverySettings/{{phoneDeliverySettingID}} to select the numbers you would like to use for sending messages, by marking them as selected. The Twilio example is as follows:

{
  "id": "someTwilioPhoneDeliverySettingsId",
  "sid": "someSid",
  "provider": "CUSTOM_TWILIO",
  "numbers": [
 {
   "type": "SHORT_CODE",
   "capabilities": [
     "SMS"
   ],
   "selected": true,
   "available": true,
   "number": "894546"
 },
 {
   "type": "TOLL_FREE",
   "capabilities": [
     "SMS"
   ],
   "selected": false,
   "available": true,
   "number": "+18544440098"
 },
 {
   "type": "PHONE_NUMBER",
   "capabilities": [
     "SMS",
     "VOICE"
   ],
   "selected": true,
   "available": true,
   "number": "+172544440091"
 }
  ]
}

For Syniverse, remove the sid property in the above example, and set "provider": "CUSTOM_SYNIVERSE".

The sequence of SMS/Voice providers in the notification settings resource’s smsProvidersFallbackChain comprises the notification fallback sequence, in the event of a primary or subsequent provider failing to send a notification. Refer to Notifications Settings for details on configuring an SMS/Voice provider fallback chain.

Configure your custom phone delivery vendor account (excluding Twilio and Syniverse)

Create a custom phone delivery settings resource using the POST {{apiPath}}/v1/environments/{{envID}}/notificationsSettings/phoneDeliverySettings operation. Create phone delivery settings:

--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <insert access token>' \
--data-raw '{
  "name": "Custom Provider Name",
  "provider":"CUSTOM_PROVIDER",
  "authentication":{
      "method":"BASIC",
      "username":"<username>",
      "password":"<password>"
    },
  "requests":[{
      "deliveryMethod":"SMS",
      "url":"<Custom provider API URL>",
      "method":"POST",
      "body":"messageType=ARN&message=${message}&phoneNumber=${to}&sender=${from}"
    }],
    "numbers":[{"type":"PHONE_NUMBER","number":"+1 222 333","capabilities":["SMS"]}]
}

The following is relevant only if the provided URL is a gateway API implemented by a customer. If the URL is the provider’s remote gateway URL, it is not applicable.

After the admin has updated the provider configuration, PingOne will send the following POST request to your gateway every time a user signs up, logs in, adds a new device, or issues another SMS or voice notification:

curl --request POST '<Custom provider API URL>' \
--header 'content-type: application/json' \
--header 'Authorization: Basic QUN...YQ==' \
--data-raw '{
   "message": "<notification message>",
   "to": "<user phone number>",
   "from": "<sender phone number>"
 }'

Phone delivery settings errors

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

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

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 : [name size must be between 0 and 100]`, `Validation Error : [authentication.username username may not be blank]`, or, for a blank name on a custom provider, `Validation Error : [name Name may not be blank]`) When and details When: A create or update request body fails constraint validation (for example, a `CUSTOM_PROVIDER` request omits `name`, or defines a `name` longer than 100 characters). Details: Per violated constraint: detail `EMPTY_VALUE` for `NotNull` constraints, `OUT_OF_RANGE` for `Size` constraints (with `rangeMinimumValue` and `rangeMaximumValue` in `innerError`), `INVALID_VALUE` otherwise, target = the field path, message = the constraint message. The class-level `Name may not be blank` validator is reported with detail `EMPTY_VALUE` and target `name`.
400	`INVALID_REQUEST`	None	Message: `The request could not be completed. The request was malformed or invalid.` When and details When: A create or update request body is malformed JSON or contains a value of the wrong type (for example, a non-UUID `phoneDeliverySettingsId`). Details: For JSON deserialization failures, detail `INVALID_VALUE` with target = the JSON path of the failing property and message `Invalid value for attribute.`
400	`INVALID_REQUEST`	`INVALID_VALUE`	Message: `The request could not be completed. The request was malformed or invalid.` When and details When: A create or update request carries a discriminator value that does not resolve to a resource subtype (for example, a `provider` value that is not one of the supported values, or a `requests` entry whose `deliveryMethod` is not `SMS` or `VOICE`). Details: Detail `INVALID_VALUE` with target `requests` and message `Invalid value for attribute.`
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 `POST` Create Phone Delivery Settings request omits `providerCredentialsSecret`. Details: Detail `INVALID_VALUE` with message `Provider Credentials Secret should not be null`.
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 create or update request violates a provider selection rule: a Syniverse Channels request selects zero or more than one channel (`Exactly one Syniverse channel must be selected`), or a Twilio Messaging Service request selects more than one messaging service (`Only one messaging service can be selected`). Details: Detail `INVALID_VALUE` with the rule-violation message.
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 create or update request cannot be validated against the provider (the Twilio, Syniverse, Twilio Verify, or TeleSign account credentials are rejected by the provider, or a custom provider’s requests are invalid — a GET request with a body, a POST body whose form-encoded content does not match its `content-type` header, or a request missing the `${message}` or `${to}` variable), or a request URL is invalid, or a custom provider’s numbers include an invalid `supportedCountries` value for the number type. Details: Detail `INVALID_VALUE` with the provider or validator message, for example `URL cannot be empty for SMS delivery method`, `Body required to be empty in GET request for SMS delivery method`, `Invalid body. Form pattern does not match the format for SMS delivery method`, `${message} variable is missing for SMS delivery method`, `${to} variable is missing for SMS delivery method`, `Validation Error : [requests[0].url must be a valid URL]` (with target `requests[0].url`), or `Validation Error : [numbers[0] The short code must contain the two-letter ISO country code for the supported country.]` (with target `numbers[0]`).
400	`INVALID_DATA`	`REQUIRED_VALUE`	Message: `The request could not be completed. One or more validation errors were in the request.` When and details When: A custom provider request selects numbers that do not support the capability required by one of its request delivery methods (for example, an SMS request with no number having the `SMS` capability). Details: Detail `REQUIRED_VALUE` with target `numbers`, the capability-violation message, and a `missingCapability` entry (`SMS` or `VOICE`) in `innerError`.
400	`INVALID_DATA`	`UNIQUENESS_VIOLATION`	Message: `The request could not be completed. One or more validation errors were in the request.` When and details When: A create or update request uses a `name` that already exists for another phone delivery settings resource in the environment (case-insensitive). Details: Detail `UNIQUENESS_VIOLATION` with message `A resource with the specified name already exists.`, target `name`, and `existingId` in `innerError` holding the ID of the existing resource.
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 create or update request changes a custom provider’s authentication method without providing a new `providerCredentialsSecret`. Details: Detail `INVALID_VALUE` with message `Credentials secret must be provided for <method> authentication method.`.
400	`REQUEST_LIMITED`	`LIMIT_EXCEEDED`	Message: `The request exceeded the allowed rate limit.` When and details When: A `POST` Create Phone Delivery Settings request would exceed the maximum of 10 phone delivery settings per environment, or would create a second custom Twilio Verify provider in the environment. Details: Detail `LIMIT_EXCEEDED` with message `Maximum allowed PhoneDeliverySettings limit has been reached, limit=10` or `Only 1 custom twilio verify provider allowed`.
400	`REQUEST_FAILED`	`CONSTRAINT_VIOLATION`	Message: `The request violates a constraint imposed by the service.` When and details When: A `DELETE` Delete Phone Delivery Settings request targets a provider that is referenced by one or more notification policies. Details: Detail `CONSTRAINT_VIOLATION` with message `You cannot delete this PhoneDeliverySettings because it is used in the following notificationsPolicies:` and `usedBy` in `innerError` listing the referencing policies.
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 create or update request references an mTLS key pair that is expired, has the wrong usage type, or cannot be loaded. Details: Detail `INVALID_VALUE` with target `tlsClientAuthKeyPair.id` and the reason: `Key pair is expired <keyPairId>`, `Key pair must be of the OUTBOUND_MTLS usage type, but <usageType> was found`, or `Could not load key store <keyPairId>`.
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:update:notificationsSettings` (`POST` Create and `PUT` Update operations), `notifications:read:notificationsSettings` (`GET` operations), or `notifications:delete:notificationsSettings` (`DELETE` Delete Phone Delivery 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`	`INVALID_VALUE`	Message: `The request could not be completed. The requested resource was not found.` When and details When: A request specifies a `phoneDeliverySettingsId` that does not exist in the environment, or an update request references an mTLS key pair that does not exist. Details: For an unknown settings ID, detail `INVALID_VALUE` with message `PhoneDeliverySettings resource not found, id=<id> providerCredentialsKey=<key>`. For an unknown key pair, detail `INVALID_VALUE` with target `tlsClientAuthKeyPair.id` and message `Could not find key pair <keyPairId>`.

400

INVALID_DATA

EMPTY_VALUE or INVALID_VALUE

Message: Validation Error : [<field> <message>] (for example, Validation Error : [name size must be between 0 and 100], Validation Error : [authentication.username username may not be blank], or, for a blank name on a custom provider, Validation Error : [name Name may not be blank])

When and details

When: A create or update request body fails constraint validation (for example, a CUSTOM_PROVIDER request omits name, or defines a name longer than 100 characters).

Details: Per violated constraint: detail EMPTY_VALUE for NotNull constraints, OUT_OF_RANGE for Size constraints (with rangeMinimumValue and rangeMaximumValue in innerError), INVALID_VALUE otherwise, target = the field path, message = the constraint message. The class-level Name may not be blank validator is reported with detail EMPTY_VALUE and target name.

400

INVALID_REQUEST

None

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

When and details

When: A create or update request body is malformed JSON or contains a value of the wrong type (for example, a non-UUID phoneDeliverySettingsId).

Details: For JSON deserialization failures, detail INVALID_VALUE with target = the JSON path of the failing property and message Invalid value for attribute.

400

INVALID_REQUEST

INVALID_VALUE

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

When and details

When: A create or update request carries a discriminator value that does not resolve to a resource subtype (for example, a provider value that is not one of the supported values, or a requests entry whose deliveryMethod is not SMS or VOICE).

Details: Detail INVALID_VALUE with target requests and message Invalid value for attribute.

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 POST Create Phone Delivery Settings request omits providerCredentialsSecret.

Details: Detail INVALID_VALUE with message Provider Credentials Secret should not be null.

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 create or update request violates a provider selection rule: a Syniverse Channels request selects zero or more than one channel (Exactly one Syniverse channel must be selected), or a Twilio Messaging Service request selects more than one messaging service (Only one messaging service can be selected).

Details: Detail INVALID_VALUE with the rule-violation message.

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 create or update request cannot be validated against the provider (the Twilio, Syniverse, Twilio Verify, or TeleSign account credentials are rejected by the provider, or a custom provider’s requests are invalid — a GET request with a body, a POST body whose form-encoded content does not match its content-type header, or a request missing the ${message} or ${to} variable), or a request URL is invalid, or a custom provider’s numbers include an invalid supportedCountries value for the number type.

Details: Detail INVALID_VALUE with the provider or validator message, for example URL cannot be empty for SMS delivery method, Body required to be empty in GET request for SMS delivery method, Invalid body. Form pattern does not match the format for SMS delivery method, ${message} variable is missing for SMS delivery method, ${to} variable is missing for SMS delivery method, Validation Error : [requests[0].url must be a valid URL] (with target requests[0].url), or Validation Error : [numbers[0] The short code must contain the two-letter ISO country code for the supported country.] (with target numbers[0]).

400

INVALID_DATA

REQUIRED_VALUE

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

When and details

When: A custom provider request selects numbers that do not support the capability required by one of its request delivery methods (for example, an SMS request with no number having the SMS capability).

Details: Detail REQUIRED_VALUE with target numbers, the capability-violation message, and a missingCapability entry (SMS or VOICE) in innerError.

400

INVALID_DATA

UNIQUENESS_VIOLATION

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

When and details

When: A create or update request uses a name that already exists for another phone delivery settings resource in the environment (case-insensitive).

Details: Detail UNIQUENESS_VIOLATION with message A resource with the specified name already exists., target name, and existingId in innerError holding the ID of the existing resource.

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 create or update request changes a custom provider’s authentication method without providing a new providerCredentialsSecret.

Details: Detail INVALID_VALUE with message Credentials secret must be provided for <method> authentication method..

400

REQUEST_LIMITED

LIMIT_EXCEEDED

Message: The request exceeded the allowed rate limit.

When and details

When: A POST Create Phone Delivery Settings request would exceed the maximum of 10 phone delivery settings per environment, or would create a second custom Twilio Verify provider in the environment.

Details: Detail LIMIT_EXCEEDED with message Maximum allowed PhoneDeliverySettings limit has been reached, limit=10 or Only 1 custom twilio verify provider allowed.

400

REQUEST_FAILED

CONSTRAINT_VIOLATION

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

When and details

When: A DELETE Delete Phone Delivery Settings request targets a provider that is referenced by one or more notification policies.

Details: Detail CONSTRAINT_VIOLATION with message You cannot delete this PhoneDeliverySettings because it is used in the following notificationsPolicies: and usedBy in innerError listing the referencing policies.

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 create or update request references an mTLS key pair that is expired, has the wrong usage type, or cannot be loaded.

Details: Detail INVALID_VALUE with target tlsClientAuthKeyPair.id and the reason: Key pair is expired <keyPairId>, Key pair must be of the OUTBOUND_MTLS usage type, but <usageType> was found, or Could not load key store <keyPairId>.

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:update:notificationsSettings (POST Create and PUT Update operations), notifications:read:notificationsSettings (GET operations), or notifications:delete:notificationsSettings (DELETE Delete Phone Delivery 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

INVALID_VALUE

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

When and details

When: A request specifies a phoneDeliverySettingsId that does not exist in the environment, or an update request references an mTLS key pair that does not exist.

Details: For an unknown settings ID, detail INVALID_VALUE with message PhoneDeliverySettings resource not found, id=<id> providerCredentialsKey=<key>. For an unknown key pair, detail INVALID_VALUE with target tlsClientAuthKeyPair.id and message Could not find key pair <keyPairId>.

PingOne Platform APIs

Phone Delivery Settings

Phone delivery settings properties

Custom provider phone delivery settings properties (Twilio or Syniverse)

Custom provider phone delivery settings properties (excluding Twilio and Syniverse)

Custom provider phone number properties

Phone delivery capabilities properties

Phone delivery events generated

Phone delivery settings response codes

Configure your custom phone delivery vendor account (Twilio or Syniverse)

Configure your custom phone delivery vendor account (excluding Twilio and Syniverse)

Phone delivery settings errors