PingOne Platform APIs

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

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_TWILIO: Uses the default PingOne provider (Twilio / Vonage) as the SMS/voice provider.

* CUSTOM_SYNIVERSE: Specifies that your Syniverse account is the SMS/voice provider.

* CUSTOM_TWILIO_VERIFY: Uses Twilio Verify.

* 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

authToken

String

Required

Immutable

The secret key of the Twilio or Syniverse account.

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.

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.

provider

String

Required

Immutable

The ID of the provider of phone delivery service. In this case it has the value CUSTOM_TWILIO, CUSTOM_SYNIVERSE, or CUSTOM_TWILIO_VERIFY.

sid

String

Required

Immutable

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

updatedAt

Date

N/A

Read-only

The time the resource was last updated.

verifyServiceId

String

Optional

Mutable

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

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

authentication

Object

Required

Mutable

Contains the information for authenticating with the provider.

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 the client ID and secret. Returned in responses for custom providers that require OAuth 2 authentication. Currently, value returned is always BASIC_AUTH_HEADER.

authentication.clientId

String

Required

Mutable

The client’s public identifier.
Required when authentication.method=OAUTH2

authentication.clientSecret

String

Required

Mutable

The client’s secret.
Required when authentication.method=OAUTH2

authentication.grantType

String

N/A

Read-only

The grant type used. Returned in responses for custom providers that require OAuth 2 authentication. Currently, value returned is always 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.username

String

Required

Mutable

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

name

String

Required

Mutable

The customer provider’s name.

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

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

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.

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.

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

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)

  1. Create a custom Twilio or Syniverse phone delivery settings resource using the POST {{apiPath}}/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".

  2. Use the PUT {{apiPath}}/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}}/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>"
 }'