9-1-1 Dashboard - API Guide

Follow

Molly Katolas

Updated

Bandwidth’s API (Application Programming Interface) is a set of programming instructions and standards for accessing Bandwidth’s web-based application for the 9-1-1 Dashboard. The API provides a quick and efficient way to manage endpoint configuration. Scroll to the bottom of this article to find a .pdf version that can be downloaded for easy reference. 

 

Getting Started

To get things moving quickly take the following steps:

  1. Open a support ticket to get a login into our staging environment. 
  2. Log into https://staging-service.dashcs.com/dash-board/login.jsp to make sure your login and password work properly.
  3. 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.
  4. Develop your client code against our staging environment.
  5. Contact us to enable API access to our production environments.

 

Environments & Security

Protocols: SOAP & REST

Emergency Provisioning API

Provisioning Limits

Usage Scenario

SIP URIs in the API

Glossary

Resources

External Tools

 

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.

 

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:

  • 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. Reach out 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 SOAP envelope: 

<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 .99 19 49</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 (http://evs.bandwidth.com) 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 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>1303228888 8</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 us.

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 ParceException

 

You don't have to use the validateLocation method at all. Here's a flowchart that shows provisioning without use of 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 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
TRAILER 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>

Throws NotFoundException, 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>1303228888 8</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 NotFoundException, LockedException, ProvisionException

 

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.

 

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, recommended 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

 

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 multiple 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 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 add Location 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.

 

SIPURIs in the API

Before making calls to test, set up a domain and PSTN fallback number in the dashboard under Emergency > Configure. If this access is not present, please contact Bandwidth Support for assistance in setting up the domain.

The endpoint should be provisioned as follows:

addLocation Sample

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:emer="http://dashcs.com/api/v1/emergency">

<soapenv:Header/>

<soapenv:Body>

<emer:addLocation>

<uri>

<callername>Fred Test</callername>

<uri>fred@example.com</uri>

</uri>

<location>

<address1>1850 Blake St</address1>

<community>Denver</community>

<postalcode>80202</postalcode>

<state>CO</state>

<type>ADDRESS</type>

</location>

</emer:addLocation>

</soapenv: Body>

</soapenv:Envelope>

 

And the endpoint should be removed like this:

removeLocation Sample

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"xmlns:emer="http://dashcs.com/api/v1/emergency">

<soapenv:He ader/>

<soapenv:Body>

<emer:removeURI>

<uri>fred@example.com</uri>

</emer:removeURI>

</soapenv: Body>

</soapenv:Envelope>

 

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

 

Article is closed for comments.