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.

Phone delivery settings properties

Property Description
id A string that specifies the auto-generated ID of the phone delivery settings.
environment.id A string that specifies the relationship of the phone delivery settings to the environment.
provider A string that specifies the ID of the provider of phone delivery service. Possible values:
  • PINGONE_TWILIO: Specifies that Ping Identity’s Twilio account is the SMS/voice provider.
  • 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 The time the resource was created.
updatedAt 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 Description
id A string that specifies the auto-generated ID of the phone delivery settings.
environment.id A string that specifies the relationship of the phone delivery settings to the environment.
sid A string that specifies the public ID of the Twilio account.
Relevant to Twilio only.
authToken A string that specifies the secret key of the Twilio or Syniverse account.
provider A string that specifies the ID of the provider of phone deliveryservice. In this case it has the value CUSTOM_TWILIO or CUSTOM_SYNIVERSE, depending on your vendor.
createdAt The time the resource was created.
updatedAt The time the resource was last updated.
numbers A collection of Twilio or Syniverse numbers to use when sending a notification.

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 Description
name A string that specifies the customer provider’s name.
requests.deliveryMethod A string that specifies the notification’s delivery method. Possible value:
  • SMS
  • VOICE
requests.url A string that specifies 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, and the optional ${from} variable, for example:
    https://api.transmitsms.com/send-sms.json?to=${to}&from=${from}&message=${message}"
requests.body A string that specifies the notification’s request body. The body should include the ${to} and ${message} mandatory variables. For some vendors, the optional ${from} variable may also be required. 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 A string that specifies the the notification’s request header, matching the format of the request body. The header can be one of:
  • Form
    (content-type=application/x-www-form-urlencoded)
  • JSON
    (content-type=application/json)
requests.method A string that specifies the type of HTTP request method. Possible values:
  • GET
  • POST
requests.phoneNumberFormat A string that specifies 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 For voice OTP notifications only.
A string that specifies 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 For voice OTP notifications only.
A string that specifies 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 A string that specifies the custom provider account’s authentication method. Possible values:
  • BASIC
  • BEARER
authentication.username A string that specifies the username for the custom provider account.
Required when authentication.method=BASIC
authentication.password A string that specifies the password for the custom provider account.
Required when authentication.method=BASIC
authentication.token A string that specifies the authentication token for the custom provider account.
Required when authentication.method=BEARER

Custom provider phone number properties

Property Description
type A string that specifies the type of phone number. Possible values: SHORT_CODE, TOLL_FREE, PHONE_NUMBER
selected A boolean that specifies whether the number is selected by the admin for sending messages.
createdAt The time the resource was created.
number A string that specifies the phone number, toll-free number or short code.
available A boolean that specifies whether the number is currently available in the provider account.
capabilities A collection of the phone delivery service capabilities.
supportedCountries 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 Description
capability A string that specifies the type of phone delivery service capability. Possible values: VOICE, SMS

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)

  1. 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".

  1. Use the PUT /environments/{envId}/notificationsSettings/phoneDeliverySettings/{id} 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"]}]
}'

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