911 Access Dashboard API guide
FollowBandwidth’s API is a set of programming instructions and standards for accessing Bandwidth’s web-based application – the 911 Access Dashboard. The API provides a quick and efficient way to manage endpoint configuration. Please open a ticket with your Bandwidth Support Team should you need a sample code. The sample code shows how to use our SOAP APIs using a Java and .NET client, as well as shell scripts that demonstrate using the REST APIs.
Getting started
- Log into the staging environment to make sure your login and password work properly. If you don't have a login, please open a ticket with your Bandwidth Support Team.
- If you aren’t familiar with web services, be sure to get the tooling or libraries you need for your platform. Not sure where to start? Download SOAPUI to begin working with our API right away.
- Develop your client code against our staging environment.
- Please reach out to your Bandwidth Support Team to enable API access on our production environments.
Environments
Security
Validating your credentials
<ns1:getAuthenticationCheckResponse xmlns:ns1=”http://dashcs.com/api/v1/emergency”>
<AuthValid>true</AuthValid>
</ns1:getAuthenticationCheckResponse>
Protocols
SOAP
<address1>1850 Blake Street</address1>
<address2>?</address2>
<community>Denver</community>
- Staging - https://staging-service.dashcs.com/dash-api/soap/emergencyprovisioning/v1?wsdl
- Production - https://service.dashcs.com/dash-api/soap/emergencyprovisioning/v1?wsdl
REST
-
Production URI - https://service.dashcs.com/dash-api/xml/emergencyprovisioning/v1
curl -silent -basic -user <USERNAME>:<PASSWORD> \
https://service.dashcs.com/dash-api/xml/emergencyprovisioning/v1/authenticationcheck | tidy -xml -indent -quiet
Figuring out what XML the REST API expects and returns
validateLocation SOAP request
<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
<validateLocation>
<location>
<address1>2040 Larimer</address1>
<community>Denver</community>
<state>CO</state>
<postalcode>80205</postalcode>
<type>ADDRESS</type>
</location>
</validateLocation>
validateLocation SOAP response
<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
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
Using the documentation for REST GET request URIs
Location status values

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.
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.
getProvisionedLocationHistoryByURI
Given a URI find the provisioned location and histories.
Sample REST POST request
<getProvisionedLocationHistoryByURI>
<uri>13032288888</uri>
</getProvisionedLocationHistoryByURI>
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.
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.
Sample REST POST request
<validateLocation>
<location>
<address1>2040 Larimer</address1>
<community>Denver</community>
<state>CO</state>
<postalcode>80205</postalcode>
<type>ADDRESS</type>
</location>
</validateLocation>
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
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>
Address Line 2
If you encounter an error due to Address Line 2 being over 60 characters, please edit the address down.
Address Line 2 can be a free form text, although the typical format is:
<unit type> <unit num> <unit type> <unit num>...
To fit more information into a smaller space, we try to abbreviate it. Here are the example Address Line 2 inputs and corresponding abbreviated outputs:
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
|
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 |
removeLocation
<removeLocation>
<locationid>77</locationid>
</removeLocation>
removeURI
Sample REST POST request
<removeURI>
<uri>13032288888</uri>
</removeURI>
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>
Faults
ParseException
NotFoundException
LockedException
ProvisionException
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
- 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
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
External tools
cURL – a flexible command-line tool for making HTTP GET and POST requests. cURL is used as some of our sample code within shell scripts.
SOAPUI – a Java GUI application for consuming WSDL and hitting SOAP services. Not meant for development, but 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?
2 out of 2 found this helpful
Article is closed for comments.