Bandwidth branded site for 911 services


Molly Katolas


Click here to find out if your E911 endpoints are compliant with RAY BAUM’s Act

The branded site is a URL redirect initiated from the customer’s portal in order to update a 911 record. This is accomplished by configuring the branded site information on the 911 Access Dashboard, on the customer administration interface, and again on the customer’s website platform as shown in the diagram below.

911 Access Dashboard configuration


A shared HMAC key performs authentication for the branded website. To set this up via your 911 Access Dashboard, perform the following steps:
  1. Log into the 911 Access Dashboard.
  2. In the top navigation bar, select Emergency and click Configure.
  3. Select the key type from the Key type drop-down.
  4. Click Generate new keys.


  1. The keys fields will be populated with the new HMAC keys determined by the selected key type (the default is MD5).

Success/Failure URL Setup

Success and failure URLs are set up so that when the user makes the 911 update in the branded website, the URL will redirect them and indicate whether or not the update was valid and accepted. Here are the success and failure URLs to assist with testing this feature:

After a user successfully performs an update, they'll return to the URL provided in the configuration module using the success URL. Returning via this URL means no error occurred and the user decided to return. Any user-defined data (xd) passed in when redirected to the branded site will be returned via querystring, in a parameter named xd (extra data).

When an error occurs inside the branded site, the user will be directed back to the website provided in the failure URL. In addition to user-defined extra data (xd) in the querystring, there'll be a reason parameter. The possible error codes are listed below. We recommend that if the user receives an error, they should contact the customer’s internal methods for assistance to resolve the failure. Once reported internally, please reach out to your Bandwidth Support team for help with resolving the address issue.

Error Codes

Here's an example of the error URL:

And here are the error values for the return reason:

Error Value Meaning
000 No reason. Contact Bandwidth support for branded website assistance.
001 Unknown reason. Contact Bandwidth support for branded website assistance.
100 General Failure. Contact Bandwidth Support for branded website assistance.
101 Authentication error. Contact Bandwidth Support for branded website assistance.
102 Update failure. A problem occurred while updating the address.
200 Address validation problem. A subscriber could not enter a postal-validated address. 

Logo and CSS Setup

Customization of the branded website is performed by changing the logo file and the CSS of the webpage to match that of an internal customer portal. Once customization is complete, the changes can be configured under the Logo URL and CSS URL sections in the branded website configuration module in the 911 Access Dashboard.

URL Generator

The branded website URL generator is provided to assist you in setting up the branded website. This URL generator utilizes the settings defined above to generate a URL to test against. This is extremely helpful in locating any discrepancies between the URL redirect generated from the customer's end, and the URL generated on the Bandwidth end. It also allows for testing the redirect to ensure the website is responding.

To test using the URL generator, perform the following steps:

  1. Click the Branded Site URL Generator link below the Branded Website section in the 911 Access Dashboard. 


  1. Once you're on the Generate a Branded Site URL page, enter the phone number, select the key type, and specify the key number.
  2. Click Update.


This will return the proper generated URL based on the branded site settings, as shown below. To test the feature all the way through, simply click on the generated link or open it in a new browser window. The branded site that's been customized using all of the aforementioned methods should appear and allow a 911 address update to occur.

To verify that the address was accepted and provisioned in the 911 Access Dashboard, simply search for the phone number in the 911 Access Dashboard:

  1. In the top navigation bar, select Emergency and click Endpoints.
  2. Enter the phone number in the search box, and click Search.
  3. The properly provisioned endpoint should appear in a list. Click on the endpoint to view the endpoint in full, and look to verify any minor discrepancies in provisioning, such as date or CID which are the most common errors.

Customer platform redirect configuration

In order for the branded website to fully function, the URL redirect must originate from the customer's web portal. Since Bandwidth can't authenticate the end subscriber via the URL redirect, we rely on the customer to authenticate the user and tie that user to their phone number before allowing them to update a 911 address.

From the customer web portal, please instruct the end user to click the Update my 911 address link, which will initiate the redirect on the their side and allow them to update the address information associated with the phone number.


In order to create the URL redirect, the following values must be added and then HASHed to provide security for the customer’s 911 information:

Subscriber Telephone Number

  • Name: tn
  • Value: The telephone number of the subscriber as a 10-digit number with no additional characters.


  • Name: date
  • Value: The current date and time, expressed in UTC. The format is “yyyyMMddHHmm”:
yyyy = four-digit year
MM = two-digit month, from 01-12
dd = two-digit day of the month, from 00-32
HH = two-digit hour, from 00-23
mm =  two-digit minute, from 00-59

The date ensures that a URL can't be used outside of a certain window of time (+/- 10 minutes of the current UTC time). This protects against an attacker retrieving a URL from the browser’s history, for example.

Company ID

  • Name: cid
  • Value: The Bandwidth assigned company ID (usually a 5-digit number). This can be retrieved in the 911 Access Dashboard from the main account screen when you first log in, or at the bottom of the page next to the customer's name.

Key Number

  • Name: kn
  • Value: Key number, either 0 or 1, specifies the key to use. Multiple keys are allowed in the database to make routing easier.

Authentication Value

  • Name: auth
  • Value: The HMAC generated has in Base64. This has is computed by using the supported HMAC algorithm. The plaintext-to-hash is the TN as 10 ASCII characters + the datetime. For instance, the HMAC for the TN 5557654321 at 3:40pm UTC on July 28, 2008, would be computed as “5557654321200807281540.”

Note: The date and tn used when calculating the HMAC must be the same as the passed in date and tn parameters of the querystring.

Base URL

The base part of the URL will be:

URL Configuration Example

Given the following information:

  • Key: 0x635329736E495B3867557C2A5D7D5054
  • Key number: 0
  • Company Id: 1000
  • Current UTC Date & Time: 200901200054 (12:54am, January 20, 2009)
  • Telephone Number: 9876543210
  • HMAC Algorithm: HMAC-MD5

Expressed as Base64, the hash is: ZU8aB+YmMHRDend6U+asdA==

To put this into a URL, it must be encoded using the following replacements:

Replacing With
+ %2b
/ %2f
= %3d

The new hash would be: ZU8aB%2BYmMHRDend6U%2BasdA%3D%3D

The complete URL would be (one line): board/UpdateMyAddress.action?tn=9876543210&date=200901200054&cid=1000&kn=0&a uth=ZU8aB%2BYmMHRDend6U%2BasdA%3D%3D

Once this URL is generated, the end user will be redirected to the branded site to begin updating the address. Below is a screenshot of this address update screen with a sample logo and CSS in place.

Sample PHP Code

PHP is the most frequently requested sample code:

function computeHash($tn, $date, $Key)


$auth=hash_hmac("md5",$tn.$date,$Key, TRUE);

return $auth;


function createQueryString($tn, $key, $companyId, $keyNumber)



echo "TN : "; echo $tn;

echo "<br>\n\n"; echo "<br>\n\n";

echo "Key : "; echo $key; echo "<br>\n\n";
echo "<br>\n\n";

echo "CompanyId : "; echo $companyId; echo "<br>\n\n";
echo "<br>\n\n";

echo "Key Number : "; echo $keyNumber; echo "<br>\n\n";
echo "<br>\n\n";

$format = "tn=%s&date=%s&cid=%s&kn=%d&auth=%s"; $date = gmdate('YmdHi');
//$date = "200601201149";
echo "Current Date : " . $date;

echo "<br>\n\n"; echo "<br>\n\n";

$auth = computeHash($tn, $date, $key);

echo "Plaintext to hash on : " . $tn.$date; echo "<br>\n\n";
echo "<br>\n\n";

echo "The hash is as hex : " . bin2hex($auth); echo "<br>\n\n";
echo "<br>\n\n";

echo "The hash is as binary : " . $auth; echo "<br>\n\n";
echo "<br>\n\n";

echo "The hash base 64 is : " . $auth; echo "<br>\n\n";
echo "<br>\n\n";


echo "The hash Url enconded is : " . $auth;

echo "<br>\n\n";

echo "<br>\n\n";

$queryString = sprintf($format,$tn,$date,$companyId,$keyNumber,$auth); return $queryString;


function createUrl($tn, $key, $companyId, $keyNumber)



return $baseUrl.createQueryString($tn, $key, $companyId, $keyNumber);


// Call the function

$testUrl = createUrl("3035551244","].,uWYmv{!5;.~h|","501","0"); echo $testUrl;

echo "<br>\n\n<br>\n\n<a href=\"" . $testUrl . "\">" . $testUrl . "</a>"; //header("Location: $testUrl");

Article is closed for comments.