911 Dashboard - API Guide

Larry Reeder

Updated May 14, 2020 23:41

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 doesn't 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're using an environment with exceptional tooling support for SOAP this may be the best choice.

It's highly recommended that you use a tool like SOAPUI. With it, you can easily see if you can authenticate correctly. It's 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.

Don't do the following in a call the API using SOAPUI (i.e., don't 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's 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:

Staging URI - https://staging-service.dashcs.com/dash-api/xml/emergencyprovisioning/v1
Production URI - https://service.dashcs.com/dash-api/xml/emergencyprovisioning/v1

For example, to make a call to get a list of your URIs against our staging environment you

would make an HTTP GET request to: https://staging-service.dashcs.com/dash-api/xml/emergencyprovisioning/v1/uris

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>
  </location>
</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:

Status	Description
INVALID	Location is in the system but we were unable to geocode
GEOCODED	We're 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 doesn't 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

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're 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.

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's 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 can't 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

Emergency Provisioning URLs
- SOAP
  - https://staging-service.dashcs.com/dash-api/soap/emergencyprovisioning/v1?wsdl-staging
  - https://service.dashcs.com/dash-api/soap/emergencyprovisioning/v1?wsdl-production
- REST
  - https://staging-service.dashcs.com/dash-api/xml/emergencyprovisioning/v1?wsdl-staging
  - https://service.dashcs.com/dash-api/xml/emergencyprovisioning/v1?wsdl-production
Dashboard: https://dashboard.dashcs.com
Staging dashboard: https://staging-service.dashcs.com/dash-board/login.jsp

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.

Questions? Please open a ticket with your Bandwidth Support Team or hit us up at (855) 864-7776

Was this article helpful?

0 out of 0 found this helpful

Article is closed for comments.