Apply Options and Features to Numbers

In this guide, we will show you how to apply options and features to your telephone numbers.

Single TN Option Assignment

There are a set of options that can be assigned to a telephone number on a per-number basis.

To update these options, make a PUT request to our Update SipPeer TNs settings API endpoint.

Set of Options:

Call Forwarding

Use one of the examples to update the Call Forwarding option for a telephone number

Examples:

Payload

Request URL:

PUThttps://dashboard.bandwidth.com/api/accounts/{accountId}/sites/{siteId}/sippeers/{sippeerId}/tns/{tn}

<SipPeerTelephoneNumber>
    <FullNumber>2052160156</FullNumber>
    <CallForward>7042661720</CallForward>
</SipPeerTelephoneNumber>

Response

<SipPeerTelephoneNumberResponse>
    <SipPeerTelephoneNumber>
        <FullNumber>2052160156</FullNumber>
        <CallForward>7042661720</CallForward>
    </SipPeerTelephoneNumber>
</SipPeerTelephoneNumberResponse>

cURL

curl -X PUT 'https://dashboard.bandwidth.com/api/accounts/{accountId}/sites/{siteId}/sippeers/{sippeerId}/tns/{tn}'
-u '{userName}:{password}'
-H 'Content-Type: application/xml'
-d '<SipPeerTelephoneNumber>
        <FullNumber>2052160156</FullNumber>
        <CallForward>7042661720</CallForward>
    </SipPeerTelephoneNumber>'

Response

<SipPeerTelephoneNumberResponse>
    <SipPeerTelephoneNumber>
        <FullNumber>2052160156</FullNumber>
        <CallForward>7042661720</CallForward>
    </SipPeerTelephoneNumber>
</SipPeerTelephoneNumberResponse>

Rewrite User

Use one of the examples to update the Rewrite User option for a telephone number

Examples:

Payload

Request URL:

PUThttps://dashboard.bandwidth.com/api/accounts/{accountId}/sites/{siteId}/sippeers/{sippeerId}/tns/{tn}

<SipPeerTelephoneNumber>
    <FullNumber>2052160156</FullNumber>
    <RewriteUser>SomeUser</RewriteUser>
</SipPeerTelephoneNumber>

Response

<SipPeerTelephoneNumberResponse>
    <SipPeerTelephoneNumber>
        <FullNumber>2052160156</FullNumber>
        <RewriteUser>SomeUser</RewriteUser>
    </SipPeerTelephoneNumber>
</SipPeerTelephoneNumberResponse>

cURL

curl -X PUT 'https://dashboard.bandwidth.com/api/accounts/{accountId}/sites/{siteId}/sippeers/{sippeerId}/tns/{tn}'
-u '{userName}:{password}'
-H 'Content-Type: application/xml'
-d '<SipPeerTelephoneNumber>
        <FullNumber>2052160156</FullNumber>
        <RewriteUser>SomeUser</RewriteUser>
    </SipPeerTelephoneNumber>'

Response

<SipPeerTelephoneNumberResponse>
    <SipPeerTelephoneNumber>
        <FullNumber>2052160156</FullNumber>
        <RewriteUser>SomeUser</RewriteUser>
    </SipPeerTelephoneNumber>
</SipPeerTelephoneNumberResponse>

Inbound Calls Number Format

Use one of the examples to update the Inbound Calls Number Format option for a telephone number

Possible values are: 10digit, 11digit, e164, false

Examples:

Payload

Request URL:

PUThttps://dashboard.bandwidth.com/api/accounts/{accountId}/sites/{siteId}/sippeers/{sippeerId}/tns/{tn}

<SipPeerTelephoneNumber>
    <FullNumber>2052160156</FullNumber>
    <NumberFormat>10digit</NumberFormat>
</SipPeerTelephoneNumber>

Response

<SipPeerTelephoneNumberResponse>
    <SipPeerTelephoneNumber>
        <FullNumber>2052160156</FullNumber>
        <NumberFormat>10digit</NumberFormat>
    </SipPeerTelephoneNumber>
</SipPeerTelephoneNumberResponse>

cURL

curl -X PUT 'https://dashboard.bandwidth.com/api/accounts/{accountId}/sites/{siteId}/sippeers/{sippeerId}/tns/{tn}'
-u '{userName}:{password}'
-H 'Content-Type: application/xml'
-d '<SipPeerTelephoneNumber>
        <FullNumber>2052160156</FullNumber>
        <NumberFormat>10digit</NumberFormat>
    </SipPeerTelephoneNumber>'

Response

<SipPeerTelephoneNumberResponse>
    <SipPeerTelephoneNumber>
        <FullNumber>2052160156</FullNumber>
        <NumberFormat>10digit</NumberFormat>
    </SipPeerTelephoneNumber>
</SipPeerTelephoneNumberResponse>

Remote Party ID Format

Use one of the examples to update the Remote Party ID Format option for a telephone number

Possible values are: 10digit, 11digit, e164, false

Examples:

Payload

Request URL:

PUThttps://dashboard.bandwidth.com/api/accounts/{accountId}/sites/{siteId}/sippeers/{sippeerId}/tns/{tn}

<SipPeerTelephoneNumber>
    <FullNumber>2052160156</FullNumber>
    <RPIDFormat>10digit</RPIDFormat>
</SipPeerTelephoneNumber>

Response

<SipPeerTelephoneNumberResponse>
    <SipPeerTelephoneNumber>
        <FullNumber>2052160156</FullNumber>
        <RPIDFormat>10digit</RPIDFormat>
    </SipPeerTelephoneNumber>
</SipPeerTelephoneNumberResponse>

cURL

curl -X PUT 'https://dashboard.bandwidth.com/api/accounts/{accountId}/sites/{siteId}/sippeers/{sippeerId}/tns/{tn}'
-u '{userName}:{password}'
-H 'Content-Type: application/xml'
-d '<SipPeerTelephoneNumber>
        <FullNumber>2052160156</FullNumber>
        <RPIDFormat>10digit</RPIDFormat>
    </SipPeerTelephoneNumber>'

Response

<SipPeerTelephoneNumberResponse>
    <SipPeerTelephoneNumber>
        <FullNumber>2052160156</FullNumber>
        <RPIDFormat>10digit</RPIDFormat>
    </SipPeerTelephoneNumber>
</SipPeerTelephoneNumberResponse>

Using Other Order Types to Apply Number Features

Several order types described below are appropriate for use cases like applying caller ID information, directory listings, or other number features.

TN Options Order

The TnOptions order type is used to apply number options described in the Create TN Options Order section of the API documentation.

To create a TN Options Order, make a POST request to our Create TN Option Order API endpoint. This can be done through tools like Postman or cURL.

Examples:

Payload

Request URL:

POSThttps://dashboard.bandwidth.com/api/accounts/{accountId}/tnOptions

<TnOptionOrder>
    <CustomerOrderId>TnOptionOrder1</CustomerOrderId>
    <TnOptionGroups>
        <TnOptionGroup>
            <CallForward>6042661720</CallForward>
            <PortOutPasscode>a1b2c3</PortOutPasscode>
            <TelephoneNumbers>
                <TelephoneNumber>2018551020</TelephoneNumber>
            </TelephoneNumbers>
        </TnOptionGroup>
        <TnOptionGroup>
            <CallingNameDisplay>on</CallingNameDisplay>
            <Sms>on</Sms>
            <TelephoneNumbers>
                <TelephoneNumber>9195551234</TelephoneNumber>
            </TelephoneNumbers>
        </TnOptionGroup>
    </TnOptionGroups>
</TnOptionOrder>

cURL

curl -X POST 'https://dashboard.bandwidth.com/api/accounts/{accountId}/tnOptions'
-u '{userName}:{password}'
-H 'Content-Type: application/xml'
-d '<TnOptionOrder>
    <CustomerOrderId>TnOptionOrder1</CustomerOrderId>
        <TnOptionGroups>
            <TnOptionGroup>
                <CallForward>6042661720</CallForward>
                <PortOutPasscode>a1b2c3</PortOutPasscode>
                <TelephoneNumbers>
                    <TelephoneNumber>2018551020</TelephoneNumber>
                </TelephoneNumbers>
            </TnOptionGroup>
            <TnOptionGroup>
                <CallingNameDisplay>on</CallingNameDisplay>
                <Sms>on</Sms>
                <TelephoneNumbers>
                    <TelephoneNumber>9195551234</TelephoneNumber>
                </TelephoneNumbers>
            </TnOptionGroup>
        </TnOptionGroups>
    </TnOptionOrder>

Response

<TnOptionOrderResponse>
    <TnOptionOrder>
        <OrderCreateDate>2016-01-15T12:01:14.324Z</OrderCreateDate>
        <AccountId>14</AccountId>
        <CreatedByUser>jbm</CreatedByUser>
        <OrderId>ddbdc72e-dc27-490c-904e-d0c11291b095</OrderId>
        <LastModifiedDate>2016-01-15T12:01:14.324Z</LastModifiedDate>
        <ProcessingStatus>RECEIVED</ProcessingStatus>
        <CustomerOrderId>TnOptionOrder1</CustomerOrderId>
        <TnOptionGroups>
            <TnOptionGroup>
                <CallForward>6042661720</CallForward>
                <PortOutPasscode>a1b2c3</PortOutPasscode>
                <TelephoneNumbers>
                    <TelephoneNumber>2018551020</TelephoneNumber>
                </TelephoneNumbers>
            </TnOptionGroup>
            <TnOptionGroup>
                <CallingNameDisplay>on</CallingNameDisplay>
                <Sms>on</Sms>
                <TelephoneNumbers>
                    <TelephoneNumber>9195551234</TelephoneNumber>
                </TelephoneNumbers>
            </TnOptionGroup>
        </TnOptionGroups>
        <ErrorList/>
    </TnOptionOrder>
</TnOptionOrderResponse>

Calling Name Display Update (LIDB Order)

The LIDB Order 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.

To create a LIDB Order, make a POST request to our Create LIDB Order API endpoint. This can be done through tools like Postman or cURL.

Examples:

Payload

Request URL:

POSThttps://dashboard.bandwidth.com/api/accounts/{accountId}/lidbs

<LidbOrder>
    <CustomerOrderId>[String]</CustomerOrderId>
    <LidbTnGroups>
        <LidbTnGroup>
            <TelephoneNumbers>
                <TelephoneNumber>8045030097</TelephoneNumber>
                <TelephoneNumber>8045030098</TelephoneNumber>
            </TelephoneNumbers>
            <SubscriberInformation>Joes Garage</SubscriberInformation>
            <UseType>RESIDENTIAL</UseType>
            <Visibility>PUBLIC</Visibility>
        </LidbTnGroup>
        <LidbTnGroup>
            <TelephoneNumbers>
                <TelephoneNumber>8888595935</TelephoneNumber>
            </TelephoneNumbers>
            <SubscriberInformation>Joes Storage</SubscriberInformation>
            <UseType>RESIDENTIAL</UseType>
            <Visibility>PRIVATE</Visibility>
        </LidbTnGroup>
    </LidbTnGroups>
</LidbOrder>

cURL

curl -X POST 'https://dashboard.bandwidth.com/api/accounts/{accountId}/lidbs'
-u '{userName}:{password}'
-H 'Content-Type: application/xml'
-d '<LidbOrder>
    <CustomerOrderId>[String]</CustomerOrderId>
        <LidbTnGroups>
            <LidbTnGroup>
                <TelephoneNumbers>
                    <TelephoneNumber>8045030097</TelephoneNumber>
                    <TelephoneNumber>8045030098</TelephoneNumber>
                </TelephoneNumbers>
                <SubscriberInformation>Joes Garage</SubscriberInformation>
                <UseType>RESIDENTIAL</UseType>
                <Visibility>PUBLIC</Visibility>
            </LidbTnGroup>
            <LidbTnGroup>
                <TelephoneNumbers>
                    <TelephoneNumber>8888595935</TelephoneNumber>
                </TelephoneNumbers>
                <SubscriberInformation>Joes Storage</SubscriberInformation>
                <UseType>RESIDENTIAL</UseType>
                <Visibility>PRIVATE</Visibility>
            </LidbTnGroup>
        </LidbTnGroups>
    </LidbOrder>'

Response

<LidbOrderResponse>
    <LidbOrder>
        <orderId>1d863522-c9bf-430c-8e79-cc63cad04a1d</orderId>
        <CustomerOrderId>[String]</CustomerOrderId>
        <ProcessingStatus>RECEIVED</ProcessingStatus>
        <ErrorList>
            <Error>
                <TelephoneNumber>8888595935</TelephoneNumber>
                <Code>11020</Code>
                <Description>Cannot add LIDB to a telephone number that already has LIDB or is in process</Description>
            </Error>
        </ErrorList>
        <LidbTnGroups>
            <LidbTnGroup>
                <TelephoneNumbers>
                    <TelephoneNumber>8045030097</TelephoneNumber>
                    <TelephoneNumber>8045030098</TelephoneNumber>
                </TelephoneNumbers>
                <SubscriberInformation>Joes Garage</SubscriberInformation>
                <UseType>RESIDENTIAL</UseType>
                <Visibility>PUBLIC</Visibility>
            </LidbTnGroup>
            <LidbTnGroup>
                <TelephoneNumbers>
                    <TelephoneNumber>8888595935</TelephoneNumber>
                </TelephoneNumbers>
                <SubscriberInformation>Joes Storage</SubscriberInformation>
                <UseType>RESIDENTIAL</UseType>
                <Visibility>PRIVATE</Visibility>
            </LidbTnGroup>
        </LidbTnGroups>
    </LidbOrder>
</LidbOrderResponse>

Directory Listing and Directory Assistance (DL/DA Order)

The DL/DA API allows a telephone number or group of telephone numbers to be associated with a name and address used for Directory Listing and/or Directory Assistance information.

To create a DL/DA Order, make a POST request to our Create DL/DA Order API endpoint. This can be done through tools like Postman or cURL.

Examples:

Payload

Request URL:

POSThttps://dashboard.bandwidth.com/api/accounts/{accountId}/dlda

<DldaOrder>
    <CustomerOrderId>[String]</CustomerOrderId>
    <DldaTnGroups>
        <DldaTnGroup>
            <TelephoneNumbers>
                <TelephoneNumber>5202217754</TelephoneNumber>
            </TelephoneNumbers>
            <SubscriberType>RESIDENTIAL</SubscriberType>
            <ListingType>LISTED</ListingType>
            <ListingName>
                <FirstName>John</FirstName>
                <FirstName2/>
                <LastName>Smith</LastName>
                <Designation/>
                <TitleOfLineage/>
                <TitleOfAddress/>
                <TitleOfAddress2/>
                <TitleOfLineageName2/>
                <TitleOfAddressName2/>
                <TitleOfAddress2Name2/>
                <PlaceListingAs/>
            </ListingName>
            <ListAddress>true</ListAddress>
            <Address>
                <HousePrefix/>
                <HouseNumber>915</HouseNumber>
                <HouseSuffix/>
                <PreDirectional/>
                <StreetName>Elm</StreetName>
                <StreetSuffix>Ave</StreetSuffix>
                <PostDirectional/>
                <AddressLine2/>
                <City>Carpinteria</City>
                <StateCode>CA</StateCode>
                <Zip>93013</Zip>
                <PlusFour/>
                <County/>
                <AddressType>DLDA</AddressType>
            </Address>
        </DldaTnGroup>
    </DldaTnGroups>
</DldaOrder>

cURL

curl -X POST 'https://dashboard.bandwidth.com/api/accounts/{accountId}/lidbs'
-u '{userName}:{password}'
-H 'Content-Type: application/xml'
-d '<DldaOrder>
    <CustomerOrderId>[String]</CustomerOrderId>
        <DldaTnGroups>
            <DldaTnGroup>
                <TelephoneNumbers>
                    <TelephoneNumber>5202217754</TelephoneNumber>
                </TelephoneNumbers>
                <SubscriberType>RESIDENTIAL</SubscriberType>
                <ListingType>LISTED</ListingType>
                <ListingName>
                    <FirstName>John</FirstName>
                    <FirstName2/>
                    <LastName>Smith</LastName>
                    <Designation/>
                    <TitleOfLineage/>
                    <TitleOfAddress/>
                    <TitleOfAddress2/>
                    <TitleOfLineageName2/>
                    <TitleOfAddressName2/>
                    <TitleOfAddress2Name2/>
                    <PlaceListingAs/>
                </ListingName>
                <ListAddress>true</ListAddress>
                <Address>
                    <HousePrefix/>
                    <HouseNumber>915</HouseNumber>
                    <HouseSuffix/>
                    <PreDirectional/>
                    <StreetName>Elm</StreetName>
                    <StreetSuffix>Ave</StreetSuffix>
                    <PostDirectional/>
                    <AddressLine2/>
                    <City>Carpinteria</City>
                    <StateCode>CA</StateCode>
                    <Zip>93013</Zip>
                    <PlusFour/>
                    <County/>
                    <AddressType>DLDA</AddressType>
                </Address>
            </DldaTnGroup>
        </DldaTnGroups>
    </DldaOrder>'

Response

<DldaOrderResponse>
    <DldaOrder>
        <CustomerOrderId>[String]</CustomerOrderId>
        <OrderCreateDate>2014-07-16T07:59:08.065Z</OrderCreateDate>
        <AccountId>14</AccountId>
        <CreatedByUser>team_ua</CreatedByUser>
        <OrderId>f2ac3343-5bff-424a-b8ca-975f5e7b159e</OrderId>
        <LastModifiedDate>2014-07-16T07:59:08.065Z</LastModifiedDate>
        <ErrorList/>
        <ProcessingStatus>RECEIVED</ProcessingStatus>
        <DldaTnGroups>
            <DldaTnGroup>
                <TelephoneNumbers>
                    <TelephoneNumber>5202217754</TelephoneNumber>
                </TelephoneNumbers>
                <AccountType>RESIDENCE</AccountType>
                <ListingType>LISTED</ListingType>
                <ListingName>
                    <FirstName>John</FirstName>
                    <FirstName2></FirstName2>
                    <LastName>Smith</LastName>
                    <Designation></Designation>
                    <TitleOfLineage></TitleOfLineage>
                    <TitleOfAddress></TitleOfAddress>
                    <TitleOfAddress2></TitleOfAddress2>
                    <TitleOfLineageName2></TitleOfLineageName2>
                    <TitleOfAddressName2></TitleOfAddressName2>
                    <TitleOfAddress2Name2></TitleOfAddress2Name2>
                    <PlaceListingAs></PlaceListingAs>
                </ListingName>
                <ListAddress>true</ListAddress>
                <Address>
                    <HousePrefix></HousePrefix>
                    <HouseNumber>915</HouseNumber>
                    <HouseSuffix></HouseSuffix>
                    <PreDirectional></PreDirectional>
                    <StreetName>Elm</StreetName>
                    <StreetSuffix>Ave</StreetSuffix>
                    <PostDirectional></PostDirectional>
                    <AddressLine2></AddressLine2>
                    <City>Carpinteria</City>
                    <StateCode>CA</StateCode>
                    <Zip>93013</Zip>
                    <PlusFour></PlusFour>
                    <County></County>
                    <Country>United States</Country>
                    <AddressType>Dlda</AddressType>
                </Address>
            </DldaTnGroup>
        </DldaTnGroups>
    </DldaOrder>
</DldaOrderResponse>

Fetch Order Status

Bandwidth recommends configuring your account with a subscription instead of polling the order resource for OrderStatus. Order processing times can vary and are not guaranteed, so bandwidth does not recommend setting a timeout on waiting for an order to show either COMPLETE or FAILED status, but instead relying on a webhook from an orders subscription.

Please follow the How to setup Notification Webhook guide for more information.

TN Options Order

Since the TnOptions order is asynchronous, it is recommended to create a tnoptions subscription to receive order status webhooks. Otherwise, you can make GET request to Fetch TN Option Order status API endpoint to poll the order status.

Calling Name Display Update (LIDB Order)

Since the LIDB order is asynchronous, it is recommended to create a lidbs subscription to receive order status webhooks. Otherwise, you can make GET request to Fetch TN LIDB status API endpoint to poll the order status.

POLL FOR ORDER STATUS

These orders require manual intervention and take over 24 hours to process.

Directory Listing and Directory Assistance (DL/DA Order)

Since the DL/DA order is asynchronous, it is recommended to create a DL/DAs subscription to receive order status webhooks. Otherwise, you can make GET request to Fetch DL/DA Order status API endpoint to poll the order status.

Where to next?

Now that you have learned how to apply options and features to your numbers, check out some of the other available actions in the following guides:

• How to set Failover URI