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.

Note:

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
`id`	String	Required	Immutable	The auto-generated ID of the phone delivery settings.
`environment.id`	String	Required	Immutable	The relationship of the phone delivery settings to the environment.
`provider`	String	Required	Immutable	The ID of the provider of phone delivery service. Possible values: `CUSTOM_TWILIO`: Specifies that your Twilio account is the SMS/voice provider. `CUSTOM_SYNIVERSE`: Specifies that your Syniverse account is the SMS/voice provider. `CUSTOM_PROVIDER`: Specifies a custom-defined SMS provider (excluding Twilio and Syniverse).
`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.

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
`id`	String	Required	Immutable	The auto-generated ID of the phone delivery settings.
`environment.id`	String	Required	Immutable	The relationship of the phone delivery settings to the environment.
`sid`	String	Required	Immutable	The public ID of the Twilio account. Relevant to Twilio only.
`authToken`	String	Required	Immutable	The secret key of the Twilio or Syniverse account.
`provider`	String	Required	Immutable	The ID of the provider of phone delivery service. In this case it has the value `CUSTOM_TWILIO` or `CUSTOM_SYNIVERSE`, depending on your vendor.
`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.
`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.

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
`name`	String	Required	Mutable	The customer provider’s name.
`requests.deliveryMethod`	String	Required	Mutable	The notification’s delivery method. Possible value: `SMS` `VOICE`
`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, including the `${to}` and `${message}` mandatory variables. 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}"`
`requests.body`	String	Optional	Mutable	The notification’s request body. This property is required when `requests.method` is set to `POST`. The body should include the `${to}` and `${message}` mandatory variables. 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, see Dynamic variables.
`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.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.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"/>`
`authentication.method`	String	Required	Mutable	The custom provider account’s authentication method. Possible values: BASIC BEARER
`authentication.username`	String	Required/Optional	Mutable	The username for the custom provider account. Required when `authentication.method`=`BASIC`
`authentication.password`	String	Required/Optional	Mutable	The password for the custom provider account. Required when `authentication.method`=`BASIC`
`authentication.authToken`	String	Required/Optional	Mutable	The authentication token for the custom provider account. Required when `authentication.method`=`BEARER`
`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.

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
`type`	String	Required	Mutable	The type of phone number. Possible values: `SHORT_CODE`, `TOLL_FREE`, `PHONE_NUMBER`
`selected`	Boolean	Required	Mutable	Specifies whether the number is selected by the admin for sending messages.
`createdAt`	Date	N/A	Read-only	The time the resource was created.
`number`	String	Required	Mutable	The phone number, toll-free number or short code.
`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`. See the Phone delivery capabilities properties data model.
`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.

Phone delivery capabilities properties

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

Audit reporting events

To see the effects of these events for an API call, see the event types in the Audit Report, Audit Activities API, or Webhook stream.

Service	Event
notifications	PHONE_DELIVERY_SETTINGS.CREATED
notifications	PHONE_DELIVERY_SETTINGS.UPDATED
notifications	PHONE_DELIVERY_SETTINGS.DELETED

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 /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 /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. See 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 /environments/{{envID}}/notificationsSettings/phoneDeliverySettings operation. Create phone delivery settings:

--header 'Content-Type: application/json' \
--header 'Authorization: Bearer eyJhbGciOiJ...txM2YtQ' \
--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"]}]
}'

Note: 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>"
 }'