1. Bandwidth Support Center
  2. 911 Access Support
  3. About 911 / Emergency Services

911 Dashboard - API Guide

Follow

Larry Reeder

Updated

Table of Contents

 
 
 
 
 
 
SOAP
 
REST
 
Figuring out what XML the REST API expects and returns
 
List of SOAP Methods and REST URIs
 
 
Using the documentation for REST GET request URIs
 
 

 

Overview

Bandwidth’s API (Application Programming Interface) is a set of programming instructions and standards for accessing Bandwidth’s web-based application – the Dashboard. The API provides a quick and efficient way to manage endpoint configuration. Please contact Bandwidth Support should you need sample code. The sample code shows how to use our SOAP API’s using a Java and .NET client, as well as shell scripts that demonstrate using the REST API’s.
 
 

Getting Started

To get things moving quickly, take the following steps:
  • Contact Bandwidth Support for a login into our staging environment. This request should be made via the ticketing portal.
  • Log into https://staging-service.dashcs.com/dash-board/login.jsp to make sure your login and password work properly.
  • If you aren’t familiar with web services, get the tooling or libraries you need for your platform. If you don’t know where to start, download SOAPUI to begin working with our API right away.
  • Develop your client code against our staging environment.
  • Contact Bandwidth Support to enable API access on our production environments
 

Environments

Bandwidth maintains a staging environment for customers to integrate with before moving on to production. In each section where URLs are shown, one will be for staging and the other for production. The staging environment has a possible daily outage window between 11 a.m. and 1 p.m. MT.
 
Staging does not maintain the same service levels as production. Bandwidth makes no assurances that data entered into staging is permanently saved; therefore, there should be no dependence on the staging environment from an operational perspective. Your ongoing development efforts (including integration testing and continuous integration) should not depend on the uptime of our staging server. Staging is primarily meant for initial integration and connectivity testing.
 
 

Security

Bandwidth API services are encrypted with TLS. Authentication is handled via HTTP Basic authentication. Basic authentication has popular support among frameworks and since the transport is encrypted by TLS the username and password are encrypted for all exchanges.
 
Too many failed login attempts will cause your account to be disabled. Your account can be re-enabled by your administrator using the Bandwidth dashboard or by contacting the Bandwidth support team. Our system will send out a warning to the email address associated with the user account, so you will need to make sure a valid email address is in the dashboard for the API user.
 
 

Validate Your Credentials

To check if your credentials work for emergency provisioning follow this link in a browser and enter your username and password: https://service.dashcs.com/dash-api/xml/emergencyprovisioning/v1/authenticationcheck
 
Note that you must have the “ API Emergency Access” role to use the Emergency API. You should see XML returned that looks like this: 
<ns1:getAuthenticationCheckResponse xmlns:ns1=”http://dashcs.com/api/v1/emergency”>
 <AuthValid>true</AuthValid>
</ns1:getAuthenticationCheckResponse>
 

Protocols

All API calls are synchronous. Some methods require contacting a handful of external
systems to do complex processing, and it may take some time for a reply.
 
 

SOAP

Simple Object Access Protocol is the industry standard protocol for web services. Tooling (IDE/Frameworks/etc.) support is widespread across platforms. If you are using an environment with exceptional tooling support for SOAP this may be the best choice.
 
It is highly recommended that you use a tool like SOAPUI. With it, you can easily see if you can authenticate correctly. It is helpful for learning the API and it could help diagnose problems. SOAPUI is open source and runs on all operating systems.
 
Note that when you use SOAPUI it creates a default SOAP request. It will contain question mark characters in places where you might want to insert values. While testing our API with SOAPUI you should remove the question marks, otherwise they will be interpreted as actual values. If you have no data for a field, then you can remove the opening and closing XML tags.
 
Do not do the following in a call the API using SOAPUI (i.e., do not leave the question
marks in there for fields you aren’t using).
<address1>1850 Blake Street</address1>
 <address2>?</address2>
<community>Denver</community>
 
Because the WSDL provides detail about specific proprietary capabilities, it is secured like the rest of the API. Once you have your authentication credentials, point your SOAP-based tools to the following WSDLs:
 

 

REST

Representational State Transfer is a popular format for using web services. Any HTTP client that supports TLS and basic authentication is able to use Bandwidth REST services.
 
Even if you plan on only using REST it’s useful to point a tool like SOAPUI to our WSDL. This will show the calls we expose and what data our services expect. The REST call will make an HTTP request while providing values on the URL for an HTTP GET or as XML content in a POST request. An XML response or a simple HTTP code is returned. These are the REST base URIs for staging and production:
For example, to make a call to get a list of your URIs against our staging environment you
 
In testing the REST API you can use one of several available browser plugins (see Resources below), or the cURL utility. This is what a cURL request to the authentication check service would look like going against our staging environment. This example is for a UNIX-like environment such as Linux or MacOS.
 
curl -silent -basic -user <USERNAME>:<PASSWORD> \
https://service.dashcs.com/dash-api/xml/emergencyprovisioning/v1/authenticationcheck | tidy -xml -indent -quiet
 
We provide a sample shell script that uses cURL to access our REST services, along with API examples in Java or .NET frameworks. This is available for download under the dashboard Documents tab. Contact Bandwidth Support if you need help locating it.
 
 

Figuring out what XML the REST API expects and returns

 
Even if you only intend to use our REST interface you should review our SOAP WSDL. Installing SOAPUI, looking at the data structures, methods, and return data structures will give you a quick understanding of how our API works.
 
Our REST API uses the same code base and data structures as our SOAP interface. XML sent in POST requests and XML retrieved from responses are structurally the same in both our REST API and our SOAP API.
 
Given that, here’s an example of how you can figure out what XML to send the validateLocation method in our emergency API:
  

validateLocation SOAP request

If you pull up our emergency WSDL into the SOAPUI tool it will stub out the XML of your SOAP request. From there just fill in the information.
<soapenv:Envelope xmlns:soapenv=”http://schemas.xmlsoap.org/soap/envelope/”
   xmlns:emer=”http://dashcs.com/api/v1/emergency”>
   <soapenv:Header/>
   <soapenv:Body>
    <emer:validateLocation>
    <location>
      <address1>2040 Larimer</address1>
      <community>Denver</community>
      <state>CO</state>
      <postalcode>80205</postalcode>
      <type>ADDRESS</type>
    </location>
   </emer:validateLocation>
 </soapenv:Body>
</soapenv:Envelope>

validateLocation REST request

To create the REST HTTP POST request just copy the same XML, remove the SOAP envelope and the namespace in front of the validateLocation tag. As an aside, our cURL example code uses this exact same XML to send a POST request to the server.
 
<validateLocation>
  <location>
    <address1>2040 Larimer</address1>
    <community>Denver</community>
    <state>CO</state>
    <postalcode>80205</postalcode>
    <type>ADDRESS</type>
</validateLocation>

validateLocation SOAP response

SOAP sends back a result inside of a SOAPenvelope:
<soap:Envelope xmlns:soap=”http://schemas.xmlsoap.org/soap/envelope/”>
  <soap:Body>
    <ns1:validateLocationResponse
    xmlns:ns1=”http://dashcs.com/api/v1/emergency”>
     <Location>
       <address1>2040 Larimer St</address1>
       <community>Denver</community>
       <latitude>39.753439</latitude>
       <legacydata>
         <housenumber>2040</housenumber>
         <streetname>Larimer St</streetname>
       </legacydata>
       <longitude>-104.991949</longitude>
       <plusfour>2015</plusfour>
       <postalcode>80205</postalcode>
  </soap:Body>
</soap:Envelope>
 
validateLocation REST response
 
The response to the REST request looks a lot like the SOAP response, but it doesn’t have any of the SOAP envelope.
<ns1:validateLocationResponse xmlns:ns1=”http://dashcs.com/api/v1/emergency”>
  <Location>
    <address1>2040 Larimer St</address1>
    <community>Denver</community>
    <latitude>39.753439</latitude>
    <legacydata>
    <longitude>-104.991949</longitude>
    <plusfour>2015</plusfour>
    <postalcode>80205</postalcode>
    <state>CO</state>
    <status>
      <code>GEOCODED</code>
      <description>Location is geocoded</description>
    </status>
    <type>ADDRESS</type>
 </Location>
</ns1:validateLocationResponse>
 
 
List of SOAP Methods and REST URIs
 
This is a list of API methods and the associated REST URIs:
 
Soap Method REST URI VERB
getAuthenticationCheck
/authenticationcheck
 GET
getURIs
/uris
 GET
getLocationsByURI
/locationsbyuri/{uri}
 GET
getProvisionedLocationByURI
/provisionedlocationbyuri/{uri}
 GET
getProvisionedLocationHistoryByURI
/provisionedlocationhistorybyuri/{uri}
 POST
validateLocation
/validatelocation
 POST
addLocation
/addlocation
 POST
removeLocation
/removelocation
 POST
removeURI
/removeuri
 POST
provisionLocation
/provisionlocation
 POST

 

Emergency Provisioning API

Whatever account you use to access the emergency API must have the ‘System Role for API Emergency Access’ role assigned to it. This can be done by your administrator or by Bandwidth Support.
 
We track your API requests, and they can be viewed in the Dashboard by going to Emergency > API Statistics.
 
 

Using the documentation for REST GET request URIs

In each of the API sections below, if the call is associated with an HTTP GET and it takes variables we show placeholders for what value goes where on the URI string.
 
 

Location Status Values

A big part of the emergency API is moving your locations through various states. Here are the states you can expect to see:
 
mceclip0.png
 
Status
Description
INVALID
Location is in the system but we were unable to geocode
GEOCODED
We are confident in the correctness of the address
PROVISIONED
Location is currently provisioned for the URI
REMOVED
Location has been removed from the system
ERROR
 There was an error in handling the location
 
 

Methods

getAuthenticationCheck

Convenience method that always returns true. You can use this to make sure your authentication is working. 

 
getURIs
 
Find all of the URIs belonging to the requesting customer that has active emergency services. 
 
 
getLocationsByURI
 
Find all the locations associated with the given URI.
 
Throws ParseException, NotFoundException, LockedException 
 
 
getProvisionedLocationByURI
 
Get the provisioned location associated with a URI. You can have multiple locations associated with a URI but only one can be provisioned at a time.
Throws ParseException, NotFoundException, LockedException
 
 
getProvisionedLocationHistoryByURI
 
Given a URI find the provisioned location and histories.
 
 
Sample REST POST request
<getProvisionedLocationHistoryByURI>
 <uri>13032288888</uri>
</getProvisionedLocationHistoryByURI>
Throws ParseException, NotFoundException, LockedException
 
 
getServiceLocationsByUri
 
Given a URI find the service addresses associated with the URI. This gives you a fine grain view of what emergency information is used for provisioning. Currently our API does not offer a way to change the service address information. If a service address is not correct contact Bandwidth support.
 
Throws ParseException, NotFoundException, LockedException
 
 
validateLocation
 
We validate and correct the location if necessary. You don’t have to use this method but you can call it before addLocation. When you call addLocation we still have checks in place to make sure that we have a high confidence in the address you sent.
 
We check with multiple geocode vendors and internal data sources to understand your location and establish a level of confidence. This will give you a good indication on whether or not emergency provisioning will be successful.
 
The validateLocation might return multiple addresses. Your client code should be prepared to handle this. When this happens it doesn’t mean that your original address is unable to be geocoded. It means that we were able to find similar addresses to the one you provided.
 
One approach is to present these options to your user and ask them if any of the result addresses look correct. Then you could take that data, send it to addLocation and be confident that it will pass our geocoding checks.
 
It’s not necessary or advisable to take the results of validateLocation and send them back to the validateLocation method. When we return a result that says GEOCODED that means that if the result is acceptable to you (meaning it still looks like the address you originally sent) then you can now send the results to addLocation.
 
 
Sample REST POST request
<validateLocation>
 <location>
   <address1>2040 Larimer</address1>
   <community>Denver</community>
   <state>CO</state>
   <postalcode>80205</postalcode>
   <type>ADDRESS</type>
 </location>
</validateLocation>
Throws ParseException
 
You don’t have to use the validateLocation method at all. Here’s a flow chart that
shows provisioning without use of validateLocation.
 
 

Sample Call Flow Without validateLocation

 
mceclip1.png
 

 

addLocation

You call addLocation to associate the location with a URI. On our side we take the location information and run it through various validation steps to make sure it’s a good address.
 
You can add multiple locations to a URI. This is configured in your account settings. The default value is three locations, but you can contact Bandwidth Support if you need more locations per URI.
 
NOTE: Adding a location doesn’t mean that the location is provisioned for emergency service, you still have to make a call to provisionLocation.
 
You should to use the address2 field for information like the suite, floor, apartment and so on. If this information is appended to address1 we may discard this information or give faulty results.
 
 
Sample REST POST request
<addLocation>
 <uri>
   <callername>Bandwidth Support</callername>
   <uri>13032288888</uri>
 </uri>
 <location>
   <address1>2040 Larimer</address1>
   <callername>Bandwidth Support</callername>
   <community>Denver</community>
   <postalcode>80201</postalcode>
   <state>CO</state>
   <type>ADDRESS</type>
 </location>
</addLocation>

 

Address2

We store a maximum of 60 characters worth of information for address line 2. However, different PSAP equipment may reduce the number of characters displayed for the 911 operator. To fit more information into a smaller space, we’ll try to abbreviate the information to maximize the information sent.
 
Address line 2 can be free form text, although the typical format of address2 is:
 
    <unit type> <unit num> <unit type> <unit num>...
 
Here are example address2 entries and their normalized values:
 
Input
Abbreviated Output
suite AA
STE AA
building A floor 3 room 7
BLDG A FL 3 RM 7
wharf 7 pier A
WHARF 7 PIER A
 
A full list of unit type abbreviations is below:
 
Input Unit Type Abbreviated Unit Type
APARTMENT
 APT
BASEMENT
 BSMT
BUILDING
 BLDG
DEPARTMENT
 DEPT
FLOOR
 FL
FRONT
 FRNT
HANGAR
 HNGR
LOBBY
 LBBY
LOT
 LOT
LOWER
 LOWR
OFFICE
 OFC
PENTHOUSE
 PH
PIER
 PIER
REAR
 REAR
ROOM
 RM
SIDE
 SIDE
SLIP
 SLIP
SPACE
 SPC
STOP
 STOP
SUITE
 STE
SUITE
 TRLR
UNIT
 UNIT
UPPER
 UPPR
 
Throws ParseException,LockedException
 
 
removeLocation
 
Given a location ID, remove the location. Sample REST POST request:
<removeLocation>
 <locationid>77</locationid>
</removeLocation>
ThrowsNotFoundException, LockedException
 
 
removeURI
 
You send the URI you would like removed. We remove that URI from the system. We also remove all locations that were associated with the URI. Any provisioned locations are also unprovisioned.
 
 
Sample REST POST request
<removeURI>
  <uri>13032288888</uri>
</removeURI>
Throws ParseException, NotFoundException, LockedException
 
 

provisionLocation

This method activates a specific location for emergency service. The location must be something you have already added and associated with a URI (phone number).
 
If you have multiple locations associated with a URI and you want to switch provisioned locations, calling provisionLocation will automatically unprovision any currently provisioned location and then immediately provision the new location you requested.
 
 
Sample REST POST request
<provisionLocation>
 <locationid>951019</locationid>
</provisionLocation>
Throws ParseException, NotFoundException, LockedException
 
 

Faults

ParseException

An invalid URI was given, the valid format is 1NPANXXZZZZ. 
 
 
NotFoundException
 
We couldn’t retrieve any data based on your criteria.
 
 
LockedException
 
The URI you are attempting to provision is used by another one of your shared accounts. Remove the URI from the other shared account first.
 
 
ProvisionException 
 
Unable to provision DID. Contact Bandwidth Support for assistance.
 
 

Throttling and Request Rate Limitation

We ask our customers to self-limit requests to 3 per second. By default, Bandwidth will automatically limit requests for some resource-intensive API operations to 5 requests per second so that the activities of one customer don't impact other customers. The operations that are throttled are:

  • addLocation
  • provisionLocation
  • removeLocation
  • removeUri
  • validateLocation

Both SOAP and REST versions of these operations are rate-limited.

We may throttle other operations if we identify traffic that appears to be abusive. Requests that violate the rate limits will receive an HTTP 429 response. Please open a ticket with your Bandwidth Support Team if you believe you need a higher rate limit.

 

Provisioning Limits

Field
Restriction
uri
11 digit NANPA-valid phone number, with “1” as the country code.
callername
up to 75 characters
address1
up to 150 characters
address2
up to 60 characters supported, recommend 20 or less due to display
limitations at some PSAPs. Our system will automatically abbreviate
some common terms like “APARTMENT” or “FLOOR”
community
up to 50 characters
state
2-character valid state or province code
postalcode
up to 10 characters. Valid Canadian postal code or US zip code.
Remove spaces and hyphens from Canadian postal codes.
 
 

Usage Scenario

Add emergency service for a customer

The sequence diagram below shows a hypothetical usage scenario.
  •  Add some locations by calling the addLocation method. You can have multipl locations for one URI. The maximum number of locations for one URI is configured in the system. Contact Bandwidth Support if you need to add more locations than the default three. Each call to addLocation returns a Location that has status information so you can see if the location was GEOCODED, and an ID (locationId) that can be used later to uniquely provision or remove the location.
  • After calling addLocation a few times, use provisionLocation to set the active location. Send in the locationId to specify what location to provision out of the locations added to the URI. The provisionLocation call will return another status. A successful call will return PROVISIONED status.
  • From this point, at any time you can ask the system what locations are associated with a URI, and the API will send back a collection of locations. If one of them is provisioned, it will have the status of PROVISIONED.
  • In this example, we remove a location by sending the locationId to removeLocation. The results will come back with a status of REMOVED.
  • Next another location is provisioned. If the locationId is different than what was used before then the system automatically handles unprovisioning the original location.
  • Finally, if the number is no longer used, call removeURI to unprovision any active location that is associated with the URI. The method will remove all the locations and the URI from the system.

mceclip2.png

Preserving Manual Overrides

The address you submit is the Location. The modifications we do are in the Service Location. To see the actual geocoded, parsed and possibly modified information you can make a call to getServiceLocationsByUri. You don’t normally have to call getServiceLocationsByUri to provision emergency service.
 
We work to make the complexities of emergency provisioning as simple as possible to our API users. When you submit an address we go through multiple steps to turn that into information that we can provision for emergency service. That involves geocoding your input, parsing it into more detailed fields, and on rare occasions doing manual work to modify the address so that it can be provisioned for emergency service.
 
It is very important for you to understand that after this manual work is done, the address you submitted serves as the key for all the override. For example, if you make a call to addLocation with slight changes to the address then all the original override work will be lost until the original work is repeated.
 
Your subscriber calls will still route to the emergency call center but this incurs additional fees and no location information can be sent to operators handling the emergency call.
 
For example, if the submitted location cannot be provisioned due to lack of geocode information, Bandwidth Support will assist you in verifying address information. If Bandwidth confirms address information via an LOA (letter of authorization) or other verification method, then Bandwidth will manually provision the service location. You may elect to provision the original submitted location to receive confirmation via API. The dashboard will map the original invalid location to the manually updated service location.
 
 

Glossary

Term
Definition
URI
A phone number that you want to add emergency service to. For example:
15553211234.
Location
Address information you provide to associate with a URI that will
potentially be provisioned for emergency service. There can be many
locations for a URI.
Service
Location
More detailed location information you can view to see how we
interpreted your location.
Provisioned
Location
One of your locations associated with your URI that you have designated as the
active location

 

Resources

 

External Tools

  • cURL - http://curl.haxx.se/download.html: Flexible command-line tool for making HTTP GET and POST requests. cURL is used as some of our sample code within shell scripts.
  • SOAPUI - http://soapui.com: A Java GUI application for consuming WSDL and hitting SOAP services. Not meant for development, very useful for understanding API and proving services work.

Article is closed for comments.