---
title: Phone Delivery Settings
description: 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.
component: pingone-api
page_id: pingone-api:platform:notifications/phone-delivery-settings
canonical_url: https://developer.pingidentity.com/pingone-api/platform/notifications/phone-delivery-settings.html
section_ids:
phone-delivery-settings-properties: Phone delivery settings properties
custom-provider-phone-delivery-settings-properties-twilio-or-syniverse: Custom provider phone delivery settings properties (Twilio or Syniverse)
custom-provider-phone-delivery-settings-properties-excluding-twilio-and-syniverse: Custom provider phone delivery settings properties (excluding Twilio and Syniverse)
custom-provider-phone-number-properties: Custom provider phone number properties
phone-delivery-capabilities-properties: Phone delivery capabilities properties
phone-delivery-events-generated: Phone delivery events generated
phone-delivery-settings-response-codes: Phone delivery settings response codes
configure-your-custom-phone-delivery-vendor-account-twilio-or-syniverse: Configure your custom phone delivery vendor account (Twilio or Syniverse)
configure-your-custom-phone-delivery-vendor-account-excluding-twilio-and-syniverse: Configure your custom phone delivery vendor account (excluding Twilio and Syniverse)
---
# 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`: 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_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. |
| `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. |
| `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](#phone-delivery-settings-numbers-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 |
| ------------------------------------------- | --------- | --------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `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.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](#phone-delivery-settings-numbers-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: ` ` |
| `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: `` |
| `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 nameYou can also use dynamic variables in the body. For more information, refer to [Dynamic variables](notifications-templates.html#notifications-templates-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 |
| -------------------- | --------- | --------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `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](#phone-delivery-settings-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 |
| ------------ | ------ | --------- | -------- | ------------------------------------------------------------------------------- |
| `capability` | String | Required | Mutable | The type of phone delivery service capability. Possible values: `VOICE`, `SMS`. |
## Phone delivery events generated
Refer to [Audit Reporting Events](../reference/audit-reporting-events.html) 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}}/v1/environments/{{envID}}/notificationsSettings/phoneDeliverySettings` operation. [Twilio](phone-delivery-settings/create-phone-delivery-settings-twilio.html):
```json
{
"sid": "someSid",
"authToken": "someAuthToken",
"provider": "CUSTOM_TWILIO"
}
```
For [Syniverse](phone-delivery-settings/create-phone-delivery-settings-syniverse.html), remove the `sid` property in the above example, and set `"provider": "CUSTOM_SYNIVERSE"`.
2. Use the [PUT {{apiPath}}/environments/{{envID}}/notificationsSettings/phoneDeliverySettings/{{phoneDeliverySettingID}}](phone-delivery-settings/update-phone-delivery-settings.html) to select the numbers you would like to use for sending messages, by marking them as `selected`. The Twilio example is as follows:
```json
{
"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](notifications-settings.html) 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](#platform:):
```json
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer ' \
--data-raw '{
"name": "Custom Provider Name",
"provider":"CUSTOM_PROVIDER",
"authentication":{
"method":"BASIC",
"username":"",
"password":""
},
"requests":[{
"deliveryMethod":"SMS",
"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:
```json
curl --request POST '' \
--header 'content-type: application/json' \
--header 'Authorization: Basic QUN...YQ==' \
--data-raw '{
"message": "",
"to": "",
"from": ""
}'
```