Set Final Destination URI

In this guide, we will show you how to set Final Destination URI on your locations or telephone numbers.

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.

More detailed information on setting a Final Destination URI can be found here.

Set a Failover URI

Setup Failover on a Location (Sip-Peer)

To setup a failover for a location (sip-peer), make a PUT request to our Update SipPeer API endpoint. This can be done through tools like Postman or cURL.

danger

This PUT request is idempotent - it will overwrite the existing location (sip-peer) settings when made so be sure to include any previous settings that must persist on the location or you risk replacing them with their default null values

• Sip URI Format: sip:{address}@{host}
• PSTN Format: +13332221111@PSTN

Examples:

Payload

Request URL:

PUT

https://dashboard.bandwidth.com/api/accounts/{accountId}/sites/{siteId} /sippeers/{sippeerId}

<SipPeer>
    <PeerName>location_name</PeerName>
    <FinalDestinationUri>sip:+12345678901@1.2.3.4:5060</FinalDestinationUri>
    <IsDefaultPeer>true</IsDefaultPeer>
</SipPeer>

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 '<SipPeer>
        <PeerName>location_name</PeerName>
        <FinalDestinationUri>sip:+12345678901@1.2.3.4:5060</FinalDestinationUri>
        <IsDefaultPeer>true</IsDefaultPeer>
    </SipPeer>'

Response

HTTP 200 OK

Setup Failover on a Single Number/Group of Numbers

To setup a failover for a Single Number/Group of Numbers, make a POST request to our Create TN Option Order API endpoint. This can be done through tools like Postman or cURL.

• Sip URI Format: name@ip-address:port
• PSTN Format: 3332221111

Examples:

Payload

Request URL:

POST

https://dashboard.bandwidth.com/api/accounts/{accountId}/tnoptions

<TnOptionOrder>
    <TnOptionGroups>
        <TnOptionGroup>
            <FinalDestinationURI>sip:+12345678901@1.2.3.4:5060</FinalDestinationURI>
            <TelephoneNumbers>
                <TelephoneNumber>2013452345</TelephoneNumber>
                <TelephoneNumber>2013452346</TelephoneNumber>
            </TelephoneNumbers>
        </TnOptionGroup>
    </TnOptionGroups>
</TnOptionOrder>

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 '<TnOptionOrder>
        <TnOptionGroups>
            <TnOptionGroup>
                <FinalDestinationURI>sip:+12345678901@1.2.3.4:5060</FinalDestinationURI>
                <TelephoneNumbers>
                    <TelephoneNumber>2013452345</TelephoneNumber>
                    <TelephoneNumber>2013452346</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>
            <FinalDestinationURI>sip:+12345678901@1.2.3.4:5060</FinalDestinationURI>
            <TelephoneNumbers>
                <TelephoneNumber>2013452345</TelephoneNumber>
                <TelephoneNumber>2013452346</TelephoneNumber>
            </TelephoneNumbers>
        </TnOptionGroup>
    </TnOptionGroups>
    <ErrorList/>
</TnOptionOrder>
</TnOptionOrderResponse>

Where to next?

Now that you have learned how to manage number inventory in your Bandwidth accounts, check out some of the other available actions in our guides:

• How to disconnect numbers