Managing Line Options and Features
Overview
- About
- Single TN Option Assignment
- Calling Name Display
- Directory Listing and Directory Assistance (DLDA)
- Creating and Managing a DLDA Order
- Retrieving the history of a DLDA order
- Checking DLDA information associated with a TN
- Setting a Failover URI
About
The Bandwidth Phone Number Phone Number API allows the association of a number of “Option” or “Feature” characteristics with a Telephone Number.
Initially this capability is restricted to the management of Calling Name Display and Call Forwarding for the TN, but will be expanded to additional “Line Features” with subsequent releases.
In addition to the configuration of Calling Name information, other per-TN capabilities already supported by the API will be addressed in this new document section.
Note about imported Phone Numbers for Hosted Messaging
Line Options feature management is NOT available for Phone numbers that have been imported for use with Hosted Messaging.
Single TN Option Assignment
There are a number of TN capabilities that can be easily assigned directly to the Telephone Number(TN) on a per-TN basis. This set of Per-TN Options includes:
- Call Forwarding
- Rewrite User
- Inbound Calls Number Format
- Remote Party ID Format
The path for managing these options is: /accounts/{accountId>/sites/{siteId}/sippeers/{sippeerId}/tns/{tn#}
Calling Name Display
In addition to setting Calling Name Display information on a per-TN basis as described above, the Bandwidth Phone Number Phone Number API allows the establishment of Calling Name Display settings for a collection of TNs at a time. Bandwidth provides this API as a convenience to enable provisioning collections of TNs. It can support the configuration of up to 1000 TNs in a single call.
The Calling Line Display is associated with TNs using a POST
to the tnOptions
resource with a payload that describes the option and its disposition.
The key elements of the XML payload are:
TelephoneNumber
: The TN that Calling Name Display will be activated onCallingNameDisplay
: [on
|off
|systemdefault
] wheresystemdefault
will result in causing the TN to display the network default behavior.
The Bandwidth Phone Number API allows the updating of CNAM Display (LIDB) information in the network for Bandwidth TNs managed within the customer’s account. This capability works within the same asynchronous work-order mechanism as is used for managing other delay-prone system interactions, where a “work-order” is created by the initial API call, and used as a reference for tracking and confirming the subsequent states, and the ultimate success and failure of the result.
Calling Name Display Update (LIDB)
The Request to add LIDB information to the TNs in an account is made by a POST
request to the /lidbs
resource associated with an account. This request contains a set of requests, each one specific to an individual TN on the account.
Directory Listing and Directory Assistance (DLDA)
The DLDA service allows the association of a name and address listing with a Telephone Number or Telephone Numbers in the Bandwidth Phone Number Phone Number system. The DLDA API follows the asynchronous order processing request model described elsewhere in this document, where a request is submitted, an order ID is returned as an ID of that request or order, and then the request is fulfilled in the background. The status of the request is reflected in the status of the order, and can be queried at any time.
DLDA Fields
There are a number of fields involved in submitting a DLDA order, summarized in the table below:
Field Name | Field Meaning and Values | API Element | required |
---|---|---|---|
Listed Telephone Number | 10 Digit US Number | <TelephoneNumber> |
y |
Listing Type | Listed (in DA & Dir)NonListed (in DA Only),NonPublished (No DA & No Dir) | <ListingType> |
y |
Type of Account | Residential orBusiness | <SubscriberType> |
y |
Listed Name Last | Last Name or First Name of Business | <LastName> |
y |
Listed Name First | First Name or Remaining Name of Business | <FirstName> |
|
Listed Name First 2 | First name of Second Party. It will be appended to the First Name with an "&" | <FirstName2> |
|
Designation | Atty, Plmbr, etc… | <Designation> |
|
Title of Lineage | Jr, Sr, III, IV, etc… | <TitleOfLineage> |
|
Title of Address | Rev, Sgt, etc… | <TitleOfAddress> |
|
Title of Address2 | Dr, etc.. | <TitleOfAddress2> |
|
Title of Lineage for Dual Name | Jr, Sr, III, IV, etc… | <TitleOfLineageName2> |
|
Title of Address 1 for Dual Name | Rev, Sgt, etc… | <TitleOfAddressName2> |
|
Title of Address 2 for Dual Name | Dr, etc.. | <TitleOfAddress2Name2> |
|
Place Listing As | Business Name Sorting String. This will be used as a string to control the sorting of the Listing if the Business Name above would not yield the correct results. For example, if 1040 Tax was the listed name; the PLA would be populated as either One Zero Forty Tax, Ten Forty Tax, or One Zero Four Zero Tax. The words within the PLA field will tell the publishers how to alphabetize the listed name. | <PlaceListingAs> |
|
Address Indicator | Used to control whether the address is listed or not. | <ListAddress> |
y |
Listed Address House Number Prefix | Valid USPS Prefix | <HousePrefix> |
|
Listed Address House Number | Valid USPS House Number | <HouseNumber> |
|
Listed Address Street No Suffix | Valid USPS Street Number Suffix | <HouseSuffix> |
|
Listed Address Street Directional | N = North, S = South, E = East, W = West, NE = Northeast,NW = Northwest, SE = Southeast, SW = Southwest | <PreDirectional> |
|
Listed Address Street Name | Valid USPS Street Name | <StreetName> |
|
Listed Address Street Thoroughfare | St, Rd, Ct, Dr, etc… | <StreetSuffix> |
|
Listed Address Street Directional Suffix | N = North, S = South, E = East, W = West, NE = Northeast,NW = Northwest, SE = Southeast, SW = Southwest | <PostDirectional> |
|
Listed Address Location | Suite 320, Apartment 104A, 2nd Floor, 3rd Level, etc. | <AddressLine2> |
|
Listed Address City | Valid USPS Community | <City> |
y |
Listed Address State | Valid USPS State | <StateCode> |
y |
Listed Address Zip Code | Valid USPS Zip Code, zip plus code or international zip code | <Zip> |
y |
Creating and Managing a DLDA Order
A DLDA order is created with a POST
to the /dldas
resource of the account. The dldas resource represents the requests made to the Bandwidth Phone Number API to add or otherwise manage a request to associate a name and street address with the telephone number. This API allows the creation and observation of a DLDA work order that causes the update of name and address information in a network Database.
Retrieving the history of a DLDA order
The history of a DLDA order can be retrieved with a GET
on the /history
resource, using the API signature: /accounts/{accountId}/dldas/{orderid}/history
Checking DLDA information associated with a TN
The GET
method retrieves detailed information about the phone number.
GET
/tns/{tn}/tndetails
retrieves detailed information about the phone number.
In addition to the name and address information inherent in a DLDA update, the DLDA information associated with the TN includes a <Status>
element are:
Status | Description |
---|---|
Success |
The information reported in the payload is the information that has been successfully registered with the Listing Provider. If a subsequent attempt has been made and failed, the original successful status and information will be retained. The failure can be interpreted based on the order state. |
Failed |
The only attempt to update DLDA information for this TN has failed, and there is no DLDA information associated with the TN with the Listing Provider. |
Pending-Editable |
An attempt to update DLDA information with the Listing Provider is in progress, but can be altered. |
Pending-Locked |
An attempt to update DLDA information with the Listing Provider is in progress, but cannot be changed at this time. A new order will be required once the current attempt succeeds or fails. |
If the <Status>
of the DLDA order impacting the TN is transient, indicating that there is an order in process and the outcome is inconclusive, the DLDA information will be replaced with a link to the order currently processing a DLDA change for that TN. This will be the case if the status is Pending-Editable
or Pending-Locked
.
Set a Failover URI
Please Note that the Failover URI functionality is only available for SIP Voice users at this time.
Setting a failover URI (Final Destination URI) allows Bandwidth to forward voice traffic to an alternate number in the event of a delivery failure to your original call route.
To set the Final Destination URI to a SIP address, use the format sip:{address}@{host}
To set the Final Destination URI to a PSTN address, use the format +13332221111@PSTN
More detailed informaion on setting a Final Destination URI can be found here.
How to Establish Automatic Failover for a Location (Sip Peer)
To enable a Final Destination URI on a location, you can make a PUT
request to accounts/{accountId}/sites/{siteId}/sippeers/{sippeerId}
.
PUT https://dashboard.bandwidth.com/api/account/{accountId}/sites/{siteId}/sippeers/{sippeerId} HTTP/1.1
Authorization: Basic {base64_encoded_credentials)
Content-Type: application/xml
<SipPeer>
<PeerName>{location_name}</PeerName>
<FinalDestinationUri>{final_destination}</FinalDestinationUri>
<IsDefaultPeer>true</IsDefaultPeer>
</SipPeer>
How to Establish Automatic Failover for a Phone Number
To enable a Final Destination URI on an individual number, you can create a TnOptions
order to update the line features. Other TnOptionGroup
features can be included when adding a Final Destination URI. You may update up to 5,000 numbers at a time.
POST https://dashboard.bandwidth.com/api/accounts/{accountId}/tnoptions HTTP/1.1
Authorization: Basic {base64_encoded_credentials}
Content-Type: application/xml
<TnOptionOrder>
<TnOptionGroups>
<TnOptionGroup>
<FinalDestinationURI>{final_destination}</FinalDestinationURI>
<TelephoneNumbers>
<TelephoneNumber>{TN_1}</TelephoneNumber>
<TelephoneNumber>{TN_N}</TelephoneNumber>
<TelephoneNumber>{TN_last}</TelephoneNumber>
</TelephoneNumbers>
</TnOptionGroup>
</TnOptionGroups>
</TnOptionOrder>