Upload
leque
View
235
Download
1
Embed Size (px)
Citation preview
Customer Experience & Operations Bandwidth Dashboard API Principles
Version 2015.2 - February 2015
www.bandwidth.com/support p: (855) 864.7776
Bandwidth Dashboard
API Principles
Version 2015.4
Customer Experience & Operations Bandwidth Dashboard API Principles
Version 2015.2 – February 2015
www.bandwidth.com/support pg.2 p: (855) 864.7776
1 Table of Contents
1 TABLE OF CONTENTS ............................................................................................................. 2
2 OVERVIEW ................................................................................................................................. 3
3 GETTING STARTED .................................................................................................................. 4
4 THE ACCOUNT CONFIGURATION MODEL ............................................................................. 7
5 MANAGING SITES ..................................................................................................................... 9
6 MANAGING SIP PEERS .......................................................................................................... 11
7 SEARCHING FOR PHONE NUMBERS ................................................................................... 13
8 ORDERING PHONE NUMBERS .............................................................................................. 14
9 RESERVING PHONE NUMBERS ............................................................................................ 18
10 PORTING-IN PHONE NUMBERS ............................................................................................ 19
11 DISCONNECTING PHONE NUMBERS ................................................................................... 24
12 MANAGING LINE OPTIONS AND FEATURES ....................................................................... 25
13 MANAGING ORDERS .............................................................................................................. 29
14 REPORTING ............................................................................................................................. 31
15 ADMINISTRATIVE FUNCTIONS .............................................................................................. 33
Customer Experience & Operations Bandwidth Dashboard API Principles
Version 2015.2 – February 2015
www.bandwidth.com/support pg.3 p: (855) 864.7776
2 Overview
The Bandwidth Dashboard's API provides a set of programmable interfaces for customers to easily configure their services, search for phone numbers, order phone numbers, and provision phone numbers on Bandwidth's network. The API is designed to provide customer's applications with fast and simple access to the services provided by Bandwidth, and is designed to provide a fast response times at high volumes in order to support our customer's needs.
The Bandwidth Dashboard API provides a basic suite of capabilities that are included with the Bandwidth CLEC product offerings, and an enhanced suite of capabilities that are included with the Bandwidth Web Services Amendment commercial agreement. This enhanced collection of capabilities will allow our customers unsurpassed access and control of all aspects of the Bandwidth CLEC network, through advanced provisioning and management APIs, providing support for dynamic and responsive management and customization of our customer’s business initiatives.
Customer Experience & Operations Bandwidth Dashboard API Principles
Version 2015.2 – February 2015
www.bandwidth.com/support pg.4 p: (855) 864.7776
3 Getting Started
Request log in credentials for our test environment by going to the Bandwidth Support Help Center. To verify your login credentials, point a web browser to the URL of a service for which you've been
enabled, and provide your credentials when queried by the web browser. If you are unable to access the WADL, please contact the customer experience team. Reference URL in Section 5.
Test your application against the new API. Contact the customer experience team for access to the production environment.
3.1 API Methods – REST
Bandwidth API’s support REST web service technologies.
The Bandwidth API’s are designed to provide customers with a simple way of interfacing with the number intelligence platform following standard industry practices. Wikipedia (reference http://en.wikipedia.org/wiki/Representational_state_transfer) defines REST as:
A RESTful web service (also called a RESTful web API) is a simple web service implemented using HTTP and the principles of REST. It is a collection of resources, with four defined aspects:
A base URI for the web service, such as http://example.com/resources/ An Internet media type of the data supported by the web service. This is often JSON, XML or YAML but
can be any other valid Internet media type. A set of operations supported by the web service using HTTP methods (e.g., GET, PUT, POST, or
DELETE). The API must be hypertext driven.
3.2 Security
The Bandwidth API methods are accessed through HTTPS to protect sensitive customer data against eavesdropping and man-in-the-middle attacks. Basic HTTP authentication is used with encryption via TLS. Basic HTTP authentication is supported by all browsers commonly in use, and the HTTP clients of most programming languages, and is straightforward to implement.
For examples on client authentication, please review information at: http://hc.apache.org/httpcomponents-client-ga/examples.html
Contact the Bandwidth Customer Experience Team for new credentials, password resets or access to additional purchased features.
The bandwidth dashboard requires the use of one of the versions of TLS: as of the appearance of the POODLE SSL vulnerability the support for SSL has been discontinued.
Customer Experience & Operations Bandwidth Dashboard API Principles
Version 2015.2 – February 2015
www.bandwidth.com/support pg.5 p: (855) 864.7776
3.3 Usage of REST in the Bandwidth Dashboard
Usage of the REST model for APIs involves using the tools provided by the REST model to create a consistent API experience. Bandwidth’s Dashboard APIs use:
GET for querying static resources, often paginating the results to manage large result sets that arise from dealing with large data sets such as Telephone Numbers
Search available number inventory o REST HTTP GET
Reporting o REST HTTP GET
POST for creating resources, and PUT for updating resources. In many cases POST results in the return of an identifier that is used in the subsequent management of that resource.
Ordering numbers o REST HTTP POST
SIP Peer Management o REST HTTP POST and PUT
DELETE is seldom used. In most cases, resources are persisted as history records and cannot be deleted.
3.4 The Asynchronous Order Model
Many system requests require the interaction of multiple “back-end” systems, and cannot be guaranteed to complete within a short time interval. Additionally, for many of these requests it is valuable to retain a persistent record of the transaction or series of transactions. Ordering Features and Services, and requesting number Porting, both fit into this class of activity. In these cases the Bandwidth Dashboard APIs use an Asynchronous model, where the initial request results in the creation of a unique “order”, which is identified by an order-id which is typically returned in the Location header of a POST request. This order-id is then subsequently used to monitor and update the initial request. In general these order-ids are represented by a UUID, and will be preserved at least for the length of time required to fully complete the request. Their status can be requested at any time, and in cases the request can be modified
3.5 BASE URLs and Environments
All resources are located at:
Base URL for Interop – https://test.dashboard.bandwidth.com/api
Base URL for Production – https://dashboard.bandwidth.com/api
Customer Experience & Operations Bandwidth Dashboard API Principles
Version 2015.2 – February 2015
www.bandwidth.com/support pg.6 p: (855) 864.7776
The payload/content of the REST messages is encoded in XML. To provide information to the endpoints on how to interpret the content, a HTTP Header value is used to identify the content as XML content. To achieve this the header “Content-Type” must be set as “application/xml” for all messages. The “Authorization” header is used to include the Basic-encoded credentials.
API Calls to the Base URL will return an empty document (no content), and not perform any authentication or other processing. A REST resource is required for any action on the part of the server.
3.6 REST URLs and Parameters
Bandwidth attempts to maintain syntactic consistency in the specification and execution of the Bandwidth
Dashboard API. Some of the guidelines that serve as goals are:
Backwards compatibility – Bandwidth remains committed to backwards compatibility in it’s API
implementation, occasionally at the expense of API complexity or additional query parameters.
Date flexibility – for most API calls that have dates as query parameters, the format yyyy-mm-dd or yy-
mm-dd will be supported
Case insensitivity – in many but not all cases elements of the REST URI are case insensitive. Some
resource names and identifiers are case sensitive by their nature, and some have not yet been
converted to case insensitive parsing.
Providing generic, robust resource descriptors for URIs remains a focus of the ongoing development, and will
be attempted wherever changes can be made that do not violate our commitment to backwards compatibility.
Customer Experience & Operations Bandwidth Dashboard API Principles
Version 2015.2 – February 2015
www.bandwidth.com/support pg.7 p: (855) 864.7776
4 The Account Configuration Model The basic work-flow for configuring an account, and subsequently managing numbers on that account is diagrammed below. This involves first defining the logical and physical infrastructure, and subsequently adding and managing Telephone Numbers via ordering and Porting.
Customer Experience & Operations Bandwidth Dashboard API Principles
Version 2015.2 – February 2015
www.bandwidth.com/support pg.8 p: (855) 864.7776
Customer Experience & Operations Bandwidth Dashboard API Principles
Version 2015.2 – February 2015
www.bandwidth.com/support pg.9 p: (855) 864.7776
5 Managing Sites Each account may have one or more Sites defined. Each Site may have one or more SIP Peers defined, which are the objects that contain the endpoints used to send and receive voice and data traffic. Most customers may only need a single Site and SIP Peer, but this structure allows customers with multiple products, channels, customers and physical locations to easily model their endpoints. In the Bandwidth Dashboard UI, "Sites" are referred to as "Sub-account", which is their most frequent use. SIP Peers are referred to as "Locations" as they are most frequently used to model customer's physical locations. Telephone numbers are associated with a single SIP Peer within a Site. These same rules are applied in the Bandwidth Dashboard UI's account structure.
Please note that both the Sites(SubAccounts) and SIP Peers(Locations) are not intended to grow in an unbounded manner. If you are finding the need to establish more than 50 Sites(SubAccounts), or 250 total SIP Peers(Locations) in order to address your business needs, please consult with your Bandwidth representative before moving beyond these thresholds. System responsiveness and / or network issues may result if these thresholds are exceeded.
Customer Experience & Operations Bandwidth Dashboard API Principles
Version 2015.2 – February 2015
www.bandwidth.com/support pg.10 p: (855) 864.7776
5.1 Example Configuration of Sites and SIP Peers
Customer Experience & Operations Bandwidth Dashboard API Principles
Version 2015.2 – February 2015
www.bandwidth.com/support pg.11 p: (855) 864.7776
6 Managing SIP Peers
SIP Peer Management enables customers to configure and manage IP addresses and other attributes for their network connections to Bandwidth. Per section 9, the SIP Peer(s) are set up on the Site to manage the numbers assigned to the account. In the User Interface, the SIP Peer is referenced as a Location instead of a SIP Peer just as a Site is referenced as a Sub Account.
A SIP Peer is a gateway that sends or receives voice and data traffic to or from Bandwidth’s network. Customer must configure a default SIP Peer on the Site within an Account. Before you can create a SIP Peer, a Site (location) must be created. You can have multiple SIP Peers on a Site. Only one default SIP Peer is allowed per Site.
Aside for being an administration point for IP addresses for network ingress and egress, SIP Peers are also used to associate Telephone Numbers with a Site/Location and Account. For a Site to order any Telephone Numbers, at least one SIP Peer must be created for the Site, and one of the SIP Peers needs to be designated as the “Default” SIP Peer with which to associate numbers.
6.1 Voice/Data Traffic
There are three different types of customer calls and messages to and from Bandwidth:
1. Origination - Voice calls from PSTN phone numbers that are delivered to customer-owned telephone numbers.
2. Termination - Voice calls from customer-owned telephone numbers that are delivered to PSTN or other on-net telephone numbers.
3. SMS - Inbound text messages that are delivered to customer-owned telephone numbers and outbound text messages that are delivered to PSTN or other on-net telephone numbers
These services can be used independently. The following sections outline how SIP Peers should be configured when different combinations of these services are used.
6.2 SIP Peer configuration for use of Origination service
Each SIP Peer can be configured with multiple IP addresses that will be used in managing traffic presentation to the Customer.
The traffic can be presented to the customer IP endpoints using one of two models – either as a Random distribution across the available voice host IP endpoints, or using a sequential failover model where traffic is preferentially presented to the first IP address until an endpoint failure is detected.
6.3 SIP Peer configuration for use of Origination and SMS services
This section provides information on defining a SIP Peer for receiving inbound calls (from Bandwidth to customer) and text messages. In the example below, the same host is used for receiving and SMS messages. If there is a different host for origination and SMS, that fact can be identified in the tags. Multiple SMS Hosts and Voice Hosts are allowed as required. The Termination Hosts field is identified with the DataAllowed
Customer Experience & Operations Bandwidth Dashboard API Principles
Version 2015.2 – February 2015
www.bandwidth.com/support pg.12 p: (855) 864.7776
element to permit SMS Data to flow in to the Bandwidth network. The optional Port element is permitted if required.
Note: In spite of the Termination Hosts data, this configuration can be blocked from Termination traffic with account level constraints
6.4 SIP Peer configuration for use of Termination service
To define a SIP Peer for sending outbound calls (from customer to Bandwidt, the configuration includes parameters called TerminationHosts, specifiying the IP address from which IP voice packets will be presented to the Bandwidth network.
6.5 SIP Peer configuration for use of Origination, Termination and SMS services
A SIP Peer can also be configured for all services, namely the ability to send and receive boith voice and text messages.
6.6 SIP Peer settings for Calling Name and other SIP Peer wide features
A number of features can be established at the SIP Peer level, including Calling Name Display and Final
Destination URI.
6.6.1 Calling Name display
Enabling Calling Name display (CNAM) for all TNs subtending a SIP Peer is done by configuring the
CallingName feature for the SIP Peer. This involves setting the CNAM Display default behavior on or off (true
or false) and then declaring whether that default behavior needs to be enforced or can be overridden at the TN
level.
6.6.2 Final Destination URI
The network configuration of a SIP Peer includes an optional attribute called finaldestinationuri. This is used when network connectivity to all previously provided hosts/IPs fails. Request format for the configuration of the SIP Peer, using this attribute, is:
6.7 Deleting a SIP Peer
A SIP peer can be deleted using the DELETE method.
Note: A SIP peer can be deleted only if there are no TNs.
6.8 Moving TNs between SIP Peers
A POST to the SIP Peer resource can be used to move Telephone Numbers between SIP Peers.
Customer Experience & Operations Bandwidth Dashboard API Principles
Version 2015.2 – February 2015
www.bandwidth.com/support pg.13 p: (855) 864.7776
7 Searching for Phone Numbers
There are a number of different resource paths for querying available telephone numbers in the Bandwidth Dashboard number inventory. These are:
1. Area Code or NPA 2. AvailableNpaNxx (List of NPA NXX quantities) 3. NPA-NXX with Local Calling Area 4. NPA-NXX-X with Local Calling Area 5. Rate Center 6. Toll Free Vanity 7. Toll Free Wild Card 8. State 9. City, State 10. Zip code 11. Lata (Telecom terminology)
7.1 Search HTTP GET Request Format
Bandwidth dashboard allows the overall Bandwidth number inventory to be searched using a variety of approaches. Our customers can use these searches to guide attempts to order numbers. The various types of avail able searches are:
Area Code / NPA searches
NPA-XXX, and NPA-NXX-X searches
Rate Center searches
State, and City/State searches
ZIP Code searches
LATA searches
Toll free number searches
These different search types have different query parameters that guide the required searches. The search requests are commuiciated via a GET API call where the type of search, the search filters, and controlling parameters such as limits on quantity and payload detail are specified as query parameters in the URL.
The response to the search request provides a list of available numbers, and if requested some details such as Rate Center and Lata, about the numbers that have been returned.
Customer Experience & Operations Bandwidth Dashboard API Principles
Version 2015.2 – February 2015
www.bandwidth.com/support pg.14 p: (855) 864.7776
8 Ordering Phone Numbers
8.1 Overview of Ordering
Orders placed with the Bandwidth Dashboard API are processed as a single-step activity when inventory is
available to fulfuill the request. The numbers will be searched for according to the indicated criteria, and, if
found, will be activated in the network without intermediate confirmation with the requestor. Under most
conditions, the time between the request for numbers, and the selection and activation of those numbers in the
bandwidth network, happens in less than a second. There are cases in the ordering of numbers where the
completion and activation of the telephone numbers in the network is not near-real-time, such as in the case
where the numbers are backordered for later completion. These facts, coupled with the need to persist an
order record beyond the activation period of the telephone numbers has motivated the use of an asynchronous
model, where the response to the request is an interim response, and the final completion of the order
happens at some later time.
In light of the fact that these interactions are handled in a machine-to-machine manner, coupled with the
considerations of our asynchronous model, has motivated us to ensure that an order always has a state, and
that state is always available vial the API. The State Transition Diagram describing these states is below.
Any attempt to query an order will indicate one of these states.
The meaning of the states is provided in the following table.
State Meaning
Received A transitional state indicating that the order has been received by the system, and is in
Customer Experience & Operations Bandwidth Dashboard API Principles
Version 2015.2 – February 2015
www.bandwidth.com/support pg.15 p: (855) 864.7776
the process of being implemented.
Complete All numbers in the request have been activated in the network. This is a final state.
Partial Some of the numbers needed to fulfill the request have been activated in the network, and no more numbers will be activated as part of this order. This is a final state. See the <PartialAllowed> element described below.
Failed None of the numbers needed to fulfill the request have been activated in the network, and no more numbers will be activated as part of this order. This is a final state. See the <PartialAllowed> element described below.
Backorderd The Bandwidth Dashboard may have activated some of the requested numbers in the network, but it is continuting to find and activate more numbers. An order may remain in this state for a number of days.
8.2 Creating an Order
The user can order numbers to their account using the HTTP POST Request Format method. This can be done either through a search for available numbers or by passing a description of the specific numbers to be ordered.
As in other asynchronous workflows, the request to order a new telephone number is created by a POST to a resource dedicated to the purpose ot tracking new number requests – the accounts/<account-id>/orders resource
If the request is valid the Bandwidth Dashboard will create an order resource, and will return an order ID which should be used in querying for the status for an order. Success will be indicated by a 201 Created return code, and will include a link to the Order resource in the Location header of the response.
8.3 New Number Order Request Format
All New Number orders are sent to the Bandwidth Dashboard as requests to create a new number order record. That new number order record is used to report the results of the order, as well as to track the status of the order if it remains open as a back-order for the numbers.
There are a number of different ways of ordering numbers using the Bandwidth Dashboard APIs, reflecting various approaches that can be used to search the available number inventory. In summary, the various types are:
Existing Number orders, used if the numbers are known to be available based on a prior search.
Area Code / NPA search based orders
NPA-XXX, and NPA-NXX-X search based orders
Rate Center search based orders
Customer Experience & Operations Bandwidth Dashboard API Principles
Version 2015.2 – February 2015
www.bandwidth.com/support pg.16 p: (855) 864.7776
State, and City/State search based orders
ZIP Code search based orders
LATA search based orders
Toll free number orders
These different order types have different parameters that guide the ordering process, and thus have different parameters as part of their order requests.
The order requests are commuiciated via a POST API call with a payload that describes the order parameters.
8.4 New Number Order Response Format
The network APIs return an XML payload in response to a request. In addition, an HTTP 201 location header message is returned for all requests. Sample is shown here:
Location: https://BASEURL/accounts/<accountid>/orders/<order-id>
The Location header represents the URL that can be fetched representing the current status of a new number order.
8.5 Backordering Numbers
If not all of the requested telephone numbers are available at the time that the order is placed, the order can
optionally be placed in a “Backordered” state, for subsequent completion by the Bandwidth Dashboard. The
order will remain in this state until the order is filled, or until the order is closed. (See section Error! Reference
source not found., Error! Reference source not found., Error! Reference source not found.)
An order will be a candidate for backordering if the <BackOrderRequested> element is included in the
request payload, with a value of “true”.
8.5.1 New Number Order States
Orders placed for new numbers usually complete rapidly, returning either all, some or none of the numbers
requested, based on the availability of numbers in the Bandwidth available inventory. The final disposition of
the order is reflected in the <OrderStatus> element; indicating FAILED (no telephone numbers available),
PARTIAL (some but not all of the requested telephone numbers were available and provided) of COMPLETED
(all of the requested telephone numbers were provided).
If a new number order has been tagged to indicate that telephone numbers are to be backordered and the
indicated quantity is not immediately available, then the order will remain active, and the interim status of
BACKORDERED will be indicated in the <OrderStatus> element when the order is examined with a GET
referencing the order-id.
8.5.2 Requesting a backorder via the API
If the API call has the <BackOrderRequested> element set to true, then the order will be retained by the
Bandwidth Dashboard until it can be filled or until it is closed via an API call or GUI status update.
Customer Experience & Operations Bandwidth Dashboard API Principles
Version 2015.2 – February 2015
www.bandwidth.com/support pg.17 p: (855) 864.7776
The <BackOrderRequested> element and the < PartialAllowed> element interact in the completion of the
order. The interaction is described in the following table:
Condition Backorder Requested
Partial Allowed
Outcome
Requested number of Telephone Numbers is found
n/a n/a User gets their TNs
Less than the requested quantity is found
true true Available TNs are ordered and the Order is placed into Backordered status for subsequent fulfillment and notification
Less than the requested quantity is found
true false The order is placed into Backordered status for subsequent fulfillment and notification, which will occur only on 100% availability. No numbers will be allocated to the order until the full request can be completely satisfied.
Less than the requested quantity is found
false true Available TNs are ordered, and the order is completed and transisitioned to the terminal "PARTIAL" state indicating that the order was partially filled
Less than the requested quantity is found
false false Order Fails. Not enough numbers are available.
None Found see above see above Same as for "Less Than", except that the entire order goes into BackOrder status immediately
8.5.3 Usage Recommendations:
Although there are no restrictions on the order-types for which backorder requests can be submitted via the
API, it is recommended to avoid submitting backorders for zipcode, npanxx and npanxxx order types, largely
because of the difficulty of filling requests of those types if the inventory is not immediately available. In the
case of npanxx and npanxxx order types, the specific dial plan elements are often no longer available, and in
the case of zipcode orders there cases where the relationship between zipcode and dialplan is not represented
in the available data.
8.6 Updating a new-number order
With the introduction of Backorder capabilities, new number orders may stay in backordered state for a period while the order is filled. While in this state it is possible to update the modifiable fields in the record, as well as to request that backorder processing of the order be ended.
Those updates to incomplete orders are facilitated by a PUT on the order id.
Closing a backordered order retains any telephone numbers that have already been assigned to the account,
and will order will typically convert its status to PARTIAL state, indicating that some requested numbers were
not provided. If no numbers were provided the final state will be FAILED.
Customer Experience & Operations Bandwidth Dashboard API Principles
Version 2015.2 – February 2015
www.bandwidth.com/support pg.18 p: (855) 864.7776
9 Reserving Phone Numbers
This API permits a TN wanted by an end user to be placed in a “Reserved” state for a limited period of
time. While in the “Reserved” state the TN will not show up in searches, and cannot be ordered by any other
party than the one that placed the TN into the “Reserved” state. This allows an End User to find a TN that they
want to purchase, and be assured that the TN will still be available once the rest of the commercial transaction
is complete. If the TN is not ordered within a timeout period the “Reserved” state is removed and the TN can
once again be ordered.
In addition to the normal work-flow, the API permits the cancellation of a reservation, reporting on outstanding
reservations, and provides the mechanism to control access to the capability at the account level.
There is a small gap in the work-flow that will prevent two parties to compete for a TN. If two searches are run
that find the same number, only the first one to place a reservation on that number will be able to order it. The
alternative to this approach, essentially auto-reserving numbers that are searched, would cause too large an
impact to the TN inventory.
The following API calls are used to manage the Reservation of TNs as part of the Ordering
process. Reservation is not enabled on all accounts. If reservation is allowed for an account, the customer
can reserve an available TN using a POST that will return a reservation ID that can be used to manage the
reservation.
An API user can cancel a Reservation that is no longer required the DELETE method.
User without Admin privileges can retrieve reservations only by using the Reservation ID:
Ordering a TN that has been reserved is done using the <ExistingTelephoneNumberOrderType> order type,
and requires that the order contains the ReservationID for any numbers that have been previously reserved. If
the Reservation ID is not included with the order, a Reserved TN will not be successfully ordered.
It is also possible to discover reservations pending against a specific TN by interrogating the TNReservation
resource associated with a TN. This query is restricted to providing information that does not cross account
boundaries.
Customer Experience & Operations Bandwidth Dashboard API Principles
Version 2015.2 – February 2015
www.bandwidth.com/support pg.19 p: (855) 864.7776
10 Porting-in Phone Numbers The Bandwidth Dashboard provides an API that can be used to submit Port-In requests. These requests to move phone numbers from a "losing carrier" to Bandwidth are part of the Local Number Portability (LNP) process. These LNP requests are automatically validated and processed. If the order fails during processing, it will be held for exception processing. Customer's can catch and fix exceptions 2 different ways:
The customer's application can check the status of port-in orders, and re-submit or cancel them through the API.
The customer's LNP team can check the status of port-in orders, and re-submit or cancel them through the Bandwidth Dashboard UI.
10.1 Overview of the Port-in Process
The external events in the porting process are documented in the diagram below.
NOTE: Exceptions are outlined as synchronous and asynchronous in the Appendix A: LNP Exception Codes.
The Orders that are managed by IRIS to implement the above workflow are reported in the order records that are reported through the API calls below. These “order states” comply with the state transitions captured in the following diagram:
Customer Experience & Operations Bandwidth Dashboard API Principles
Version 2015.2 – February 2015
www.bandwidth.com/support pg.20 p: (855) 864.7776
10.2 Checking LNP Availability
A number or numbers can be checked to see if they can be ported into the Bandwidth Network using an LNPChecker API call.
The fullcheck query parameter values control the components of the response payload that is returned:
Parameter value
Description
false (default) return only rate center information
true additional information will be provided on the losing carriers associated with the listed numbers
onnetportability Provides ratecenter and losing carrier information for onnet tiers only
offnetportabilty In addition to on-net information return off-net port information in <PartnerSupportedRateCenters> element with Partner/Vendor that the port will be supported on. Contains a list of the TNs that are supported in partner rate centers, and for which we will manually execute a port if requested for help.
Some of the key components in the response to the /lnpChecker API call are…
Element Description
SupportedRateCenters, PartnerSupportedRateCenters, and UnsupportedRateCenters
Rate Center information for the indicated set of ratecenters, containing City, State, LATA and the list of TNs for which that Rate Center applies.
The Tier information is provided fpr offnet rate centers.
SupportedLosingCarriers and UnsupportedLosingCarriers
Details on the Losing Carrier including name, SPID, whether or not the carrier is a wireless carrier, whether or not account number is required as part of the CSR check, and the anticipated minimum number of days before a FoC date will be granted.
Customer Experience & Operations Bandwidth Dashboard API Principles
Version 2015.2 – February 2015
www.bandwidth.com/support pg.21 p: (855) 864.7776
10.3 Creating an LNP Order
The API allows a user to create a new LNP order. An order number will be auto-generated and provided to the
customer. The order must pass synchronous and asynchronous validation. Synchronous validation will return
validation failures immediately in the response. If synchronous validation passes, but asynchronous validation
fails, the customer will not receive the error response until they check the order status.
As in other asynchronous workflows, the request to port in a number is created by a POST to a resource dedicated to the purpose ot tracking requests – the accounts/<account-id>/portins resource
10.4 LOA Upload
After successfully submitting the Create LNP Order request, an LOA may be uploaded using our LOA API.
10.4.1 Supported File Types
The following MIME types are supported for the LOA upload file:
PDF(“application/pdf”) PLAIN(“text/plain”) JPG(“image/jpeg”) TIFF(“image/tiff”) CSV(“text/csv”) XML(“application/xml”) WAV(“audio/x-wav”) ZIP(“application/zip”)
10.4.2 Example using CURL
Example using CURL command:
Use the order-id returned in the Create LNP Order response.
curl -H 'Content-Type: <MIME Type>' --data-binary "@<Filename>" –iv <Base URL>/portins/<order-id>/loas Example:
curl -H 'Content-Type: application/pdf' --data-binary "@Test_LOA.pdf" -iv <BASE URL>/portins/<order-id>/loas
Refer to the correct name for <BASE URL>.
An example text capture from a REST tool demonstrates a different perspective:
Customer Experience & Operations Bandwidth Dashboard API Principles
Version 2015.2 – February 2015
www.bandwidth.com/support pg.22 p: (855) 864.7776
10.4.3 File Meta-Data
It is often useful to attach additional data to an order in the form of an attached file, and so the existing LOA
capability has been extended to optionally allow different file information to be included with a file, to describe
type and purpose information. The MetaData associated with a file includes a file document name and a
document type, which is one of [LOA | INVOICE | CSR | OTHER].
10.5 Modifying an LNP Order (Supp LNP Order)
The API allows a user to modify an existing LNP order. The order number that was generated in the create LNP order request must be provided. Modifications are only allowed for orders that are not yet complete or cancelled. After the FOC date has been received, the billing telephone number and subscriber information cannot be modified, only the FOC date/time can be updated.
10.6 Canceling LNP Order
The API allows a user to cancel an existing LNP order. The order number that was generated in the create request must be provided. The status of the order shall not be marked as “COMPLETE” i.e. you cannot cancel a completed order. The DELETE method is used for this purpose.
10.7 Activating Ported Numbers
The by default the Bandwidth Dashboard will activate ported wireline numbers shortly after 11:30 am on the FOC date.
The Bandwidth Dashboard will also support customer “on demand” activation of numbers on the FOC date, if the intent to use the “on demand” activation is declared when the Port Order is created. This declaration is done by including a <Triggered> element in the /portin order request, as described in sectionError! Reference source not found. Error! Reference source not found. Error! Reference source not found..
If on demand activation is indicated, then the customer will specify a default activation time in the initial port request, and can request activation of the port at any time up until that default activation time. If a port has not been activated by the default activation time, the Bandwidth dashboard will activate the port.
Customer Experience & Operations Bandwidth Dashboard API Principles
Version 2015.2 – February 2015
www.bandwidth.com/support pg.23 p: (855) 864.7776
If activation by the default activation time on the FOC date is not achievable it is possible to delay activation for up to the third day after the FOC date, acknowledging that the losing carrier may have removed service from TN on the FOC date.
Activation and management of on-demand ports is done via the activationStatus resource. The activationStatus resource is created by the system when activation is available for the port request, and can be modified by PUT to activate the port, or to delay the activation in the case that the manual activation cannot be completed on time.
Payload Parameters:
Parameter Required Type Description
AutoActivationDate Yes Date This date controls both the activation of the Port, and delays in activation of the port.
If AutoActivationDate is in the past then the port will be activated
If AutoActivationDate is in the future then the port will be delayed until the specified time, as long as that new time does not validate other restrictions on the activation of the port. The typical guard time applied to this capabilities is 3 business days.
Customer Experience & Operations Bandwidth Dashboard API Principles
Version 2015.2 – February 2015
www.bandwidth.com/support pg.24 p: (855) 864.7776
11 Disconnecting Phone Numbers
A POST to the /disconnects resource is used to disconnect telephone numbers from the account.
Customer Experience & Operations Bandwidth Dashboard API Principles
Version 2015.2 – February 2015
www.bandwidth.com/support pg.25 p: (855) 864.7776
12 Managing Line Options and Features The Bandwidth Dashboard allows the association of a number of “Option” or “Feature” characteristics with a
Telephone Number.
Initially this capability is restricted to the management of Calling Name Display and Call Forwarding for the TN,
but will be expanded to additional “Line Features” with subsequent releases.
In addition to the configuration of Calling Name information, other per-TN capabilities already supported by the
API will be addressed in this new document section.
12.1 Single TN Option Assignment
There are a number of TN capabilities that can be easily assigned directly to the Telephone Number(TN) on a
per-TN basis. This set of Per-TN Options includes:
Call Forwarding
Rewrite User
Inbound Calls Number Format
Remote Party ID Format
The path for managing these options is: /accounts/<accountid>/sites/<site-id>/sippeers/<sippeer-id>/tns/<tn#>
12.2 Calling Name Display
In addition to setting Calling name Display information on a per-TN basis as described above, the Bandwidth
dashboard API allows the establishment of Calling Name Display settings for a collection of TNs at a time.
Bandwidth provides this API as a convenience to enable provisioning collections of TNs. It can support the
configuration of up to 1000 TNs in a single call.
The Calling Line Display is associated with TNs using a POST to the lineOptionOrders resource with a payload
that describes the option and its disposition.
The key elements of the XML payload are:
Telephone Number: The TN that Calling Name Display will be activated on
CallingNameDisplay: [on | off | systemdefault] where systemdefault will result in causing the TN to
display the network default behavior.
12.3 Calling Name Display Update (LIDB)
The Bandwidth Dashboard API allows the updating of CNAM Display (LIDB) information in the network for
Bandwidth TNs managed within the customer’s account. This capability works within the same asynchronous
Customer Experience & Operations Bandwidth Dashboard API Principles
Version 2015.2 – February 2015
www.bandwidth.com/support pg.26 p: (855) 864.7776
work-order mechanism as is used for managing other delay-prone system interactions, where a “work-order” is
created by the initial API call, and used as a reference for tracking and confirming the subsequent states, and
the ultimate success and failure of the result.
12.3.1 Creating a CNAM Update (LIDB) order
The Request to add LIDB information to the TNs in an account is made by POSTing a request to the /lidbs
resource associated with an account. This request contains a set of requests, each one specific to an
individual TN on the account.
12.4 Directory Listing and Directory Assistance (DLDA)
12.4.1 DLDA Overview
The DLDA service allows the association of a name and address listing with a Telephone Number or
Telephone Numbers in the Bandwidth Dashboard system. The DLDA API follows the asynchronous order
processing request model described elsewhere in this document, where a request is submitted, an order ID is
returned as an ID of that request or order, and then the request is fulfilled in the background. The status of the
request is reflected in the status of the order, and can be queried at any time.
There are a number of fields involved in submitting a DLDA order, summarized in the table below:
Field Name
Field Meaning and Values
API Element
required
Listed Telephone Number 10 Digit US Number <TelephoneNumber> y
Listing Type Listed (in DA & Dir) NonListed (in DA Only), NonPublished (No DA & No Dir)
<ListingType> y
Type of Account Residential or Business
<SubscriberType> y
Listed Name Last Last Name or First Name of Business <LastName> y
Listed Name First First Name or Remaining Name of Business
<FirstName>
Listed Name First 2 First name of Second Party. It will be appended to the First Name with an "&"
<FirstName2>
Designation Atty, Plmbr, etc… <Designation>
Title of Lineage Jr, Sr, III, IV, etc… <TitleOfLineage>
Title of Address Rev, Sgt, etc… <TitleOfAddress>
Title of Address2 Dr, etc.. <TitleOfAddress2>
Title of Lineage for Dual Name
Jr, Sr, III, IV, etc… <TitleOfLineageName2>
Customer Experience & Operations Bandwidth Dashboard API Principles
Version 2015.2 – February 2015
www.bandwidth.com/support pg.27 p: (855) 864.7776
Title of Address 1 for Dual Name
Rev, Sgt, etc… <TitleOfAddressName2>
Title of Address 2 for Dual Name
Dr, etc.. <TitleOfAddress2Name2>
Place Listing As Business Name Sorting String. This will be used as a string to control the sorting of the Listing if the Business Name above would not yield the correct results. For example, if 1040 Tax was the listed name; the PLA would be populated as either One Zero Forty Tax, Ten Forty Tax, or One Zero Four Zero Tax. The words within the PLA field will tell the publishers how to alphabetize the listed name.
<PlaceListingAs>
Address Indicator Used to control whether the address is listed or not.
<ListAddress> y
Listed Address House Number Prefix
Valid USPS Prefix <HousePrefix>
Listed Address House Number
Valid USPS House Number <HouseNumber>
Listed Address Street No Suffix
Valid USPS Street Number Suffix <HouseSuffix>
Listed Address Street Directional
N = North, S = South, E = East, W = West, NE = Northeast, NW = Northwest, SE = Southeast, SW = Southwest
<PreDirectional>
Listed Address Street Name
Valid USPS Street Name <StreetName>
Listed Address Street Thoroughfare
St, Rd, Ct, Dr, etc… <StreetSuffix>
Listed Address Street Directional Suffix
N = North, S = South, E = East, W = West, NE = Northeast, NW = Northwest, SE = Southeast, SW = Southwest
<PostDirectional>
Listed Address Location Suite 320, Apartment 104A, 2nd Floor, 3rd Level, etc.
<AddressLine2>
Listed Address City Valid USPS Community <City> y
Listed Address State Valid USPS State <StateCode> y
Listed Address Zip Code Valid USPS Zip Code, zip plus code or international zip code
<Zip> y
Customer Experience & Operations Bandwidth Dashboard API Principles
Version 2015.2 – February 2015
www.bandwidth.com/support pg.28 p: (855) 864.7776
12.4.2 Creating and Managing a DLDA Order
A DLDA order is created with a POST to the /dldas resource of the account. The dldas resource represents the
requests made to the Bandwidth Dashboard API to add or otherwise manage a request to associate a name
and street address with the telephone number. This API allows the creation and observation of a DLDA work
order that causes the update of name and address information in a network Database.
12.4.3 Retrieving the history of a DLDA order
The history of a DLDA order can be retrieved with a GET on the /history resource, using the API signature:
/accounts/{accountId}/dldas/{orderid}/history
12.4.4 Checking DLDA information associated with a TN
The GET method retrieves detailed information about the phone number.
GET /tns/{tn}/tndetails retrieves detailed information about the phone number.
In addition to the name and address information inherent in a DLDA update, the DLDA information associated
with the TN includes a <Status> value that indicates whether the DLDA information has been successfully
registered with the Listing provider, or is in some other state. Valid values for the <Status> element are:
Success – The information reported in the payload is the information that has been successfully
registered with the Listing Provider. If a subsequent attempt has been made and failed the original
successful status and information will be retained. The failure can be interpreted based on the order
state.
Failed – the only attempt to update DLDA information for this TN has failed, and there is no DLDA
information associated with the TN with the Listing Provider.
Pending-Editable – an attempt to update DLDA information with the Listing Provider is in progress, but
can be altered.
Pending-Locked– an attempt to update DLDA information with the Listing Provider is in progress, but
cannot be changed at this time. A new order will be required once thecurrent attempt succeeds or fails.
If the <Status> of the DLDA order impacting the TN is transient, indicating that there is an order in process and
the outcome is inconclusive, the DLDA information will be replaced with a link to the order currently processing
a DLDA change for that TN. This will be the case if the status is “Pending-Editable” or “Pending-Locked”.
Customer Experience & Operations Bandwidth Dashboard API Principles
Version 2015.2 – February 2015
www.bandwidth.com/support pg.29 p: (855) 864.7776
13 Managing Orders The Bandwidth Dashboard uses an “order” model for tracking the changes requested to the provisioned
information that controls our customer and end-user experiences. Major changes to the configuration of the
network such as Ordering numbers, Porting in numbers, Porting numbers out, Disconnecting numbers are
tracked with work-orders that record the changes and track them through the related work-flow.
This section discusses the APIs used to manage and monitor work orders.
13.1 Associating Notes with Work Orders
The following API calls are used to add notes to various types of work-orders, allowing events that involve the
work-order to be tracked and reviewed. The API can be used with users that have credentials to manage and
modify the account that owns the work-order(s).
13.2 Order Change Notifications
The Bandwidth Dashboard has the capability to monitor portins and other work-order types for meaningful
events and status changes, and notify one or more email addresses of those events. The events that cause
notification emails are state changes for all viable states for the applicable order-types, as well as for all events
that add a Note to the order in question. The applicable state changes are any changes to…
For port-ins: PENDING_DOCUMENTS, SUBMITTED, REQUESTED_SUPP, FOC,
COMPLETE, EXCEPTION, SNAPBACK, REQUESTED_CANCEL, CANCELLED
o Note that the PENDING_DOCUMENTS status is transient, and will be typically be followed
immediately by SUBMITTED or CANCELLED. It remains as part of the work-flow for backwards
compatibility reasons.
For orders: SUBMITTED, PARTIAL, COMPLETE
For portouts: COMPLETE
For disconnects: COMPLETE
13.2.1 Email Notifications
The email notification capability enables a user with permissions on an account to configure any email address
for notifications. This level of freedom was provided to allow credentialed users the flexibility to control the
destination of the notifications, even if the destination does not share an email address with the account or
user.
The email notification capability also processes responses (replies) to notifications, inserting the reply text into
the Notes field of a work order. This allows the work order to retain a record of the correspondence applicable
to the evolution of that order.
A subscription is a request to be notified by email of events that happen to outstanding work orders.
Subscriptions are associated with accounts, and apply to some or all of the work orders managed by that
account. The API for the notification framework is dedicated to the management of these subscriptions.
Customer Experience & Operations Bandwidth Dashboard API Principles
Version 2015.2 – February 2015
www.bandwidth.com/support pg.30 p: (855) 864.7776
Subscriptions can apply to a specific order-id, or to all order-ids of a certain type. If the order-id is omitted in
the subscription request it means that the subscription request is applicable to all orders of that type.
Deletion of subscriptions is supported on a one-by-one basis. Deleting all subscriptions associated with an
order requires GETting all of those Subscriptions, and deleting them one by one.
13.2.2 Callback URL Notifications:
The Bandwidth dashboard API also allows the establishment of a “callback” URL that can be used to monitor
work-orders or changes. Rather than receiving an email, the callback URL is invoked, allowing the monitoring
system to be notified about the order changes in a machine-to-machine manner.
To create a Notifications Callback Subscription the customer POSTs to the item being monitored (typically a
Order or Port-in ) the user POSTs to the subscriptions resource associates with the account.
If the OrderId field is omitted then the subscription will apply to all orders of the indicated OrderType.
The <Expiry> value can be very large (100 years in seconds), or set to infinite (-1) if required. Note that even
in the case of a long or infinite expiry, the subscription will be removed once the order (if specified) reaches a
final state.
Updating a subscription is done via a PUT to the subscription. This can be used to update the expiry request.
Requests to update the expiry are at the whim of the Bandwidth Dashboard.
Note that the initial state changes for an order may happen very quickly, so subscribing to an order once the
system creates it needs to account for the fact that the initial state may be different based on timing factors. It
is recommended that the application creating the subscription check the order status after the subscription is
created to ensure the correct initial condition.
It is possible to remove specific subscriptions by ID.
Once a subscription with a callback URL is active, changes to the works-orders that are part of the active
subscription will notified by a POST to the provided URL
Customer Experience & Operations Bandwidth Dashboard API Principles
Version 2015.2 – February 2015
www.bandwidth.com/support pg.31 p: (855) 864.7776
14 Reporting
14.1 Fetching Information – in general
Retrieving information from the Bandwidth Dashboard is typically achieved by issuing an HTTP GET against
an identifiable resource. Rather than repeat all of the resource names in this section, simply suffice it to say
that with a few exceptions, a GET on a resource will yield the available information about that resource.
Query parameters are used to filter or restrict the information returned to the caller.
14.2 Pagination
Since an account may have a very large number of orders or TNs, the system uses the pagination mechanism to control the number of results that are returned.
When a query is issued and no pagination parameters are specified, the system returns the http status code of 404 (Not found) with a link in the body of the message that indicates how to specify the pagination parameters.
14.3 Available Inventory: Rate Centers and Cities
The Rate Centers and Cities API Calls return information about the Bandwidth CLEC Network, including
coverage data, indicating both the extent of on-net and off-net coverage, as well as number availability, again
from an on-net and off-net perspective.
The rules are as follows:
If supported=true is specified, then the coverage or availability is reported for the Bandwidth CLEC
only.
If supported=true is omitted, then the coverage or availability is reported for the combination of the
Bandwidth CLEC and our partners
If available=true is applied, then only Rate Centers in which we have available numbers are reported.
If available is omitted then all Rate Centers within the scope defined by supported will be returned.
These rules apply for both the /rateCenters and /cities API calls.
Supported = true Supported is missing
available = true Available numbers within the Bandwidth CLEC network
Available numbers within the Bandwidth CLEC network combined with our partner networks
available is missing Coverage in the Bandwidth CLEC
Coverage of the combined Bandwidth CLEC + Partner networks
Customer Experience & Operations Bandwidth Dashboard API Principles
Version 2015.2 – February 2015
www.bandwidth.com/support pg.32 p: (855) 864.7776
14.4 Cities
The “supported” and “available” query parameters used above in the /rateCenters API call operate in an identical manner for the /cities API.
14.5 Available Inventory: NPA NXX combinations
The API supports discovering available inventory per NPA-NXX for a user supplied area code and state.
14.6 Billing Data Records REST APIs for Retrieving zipped files
This API call allows the user to retrieve Billing Data Records (BDRs) for an account from the network for all billing records created during a specified date range.
14.6.1 POST a BDR zipped file request
The POST to request the retrieval is formatted to indicate the start and end date of the range. Both dates are required for a valid request.
A successful response to the POST also returns a link containing a BDR ID, included in the Location header. This is the Identifier of the successful request, not the identifier of the file containing the BDRs. This link will be used to fetch the zipped file of billing records once the file is ready.
14.6.2 Retrieving a BDR zipped file record
To retrieve the zipped file with the BDR records, a GET is issued on the path returned in the location header.
If the zip file containing the BDR data is ready, this request will return “303 See Other” with a Location Header redirecting the request to the BDR zip file content.
Customer Experience & Operations Bandwidth Dashboard API Principles
Version 2015.2 – February 2015
www.bandwidth.com/support pg.33 p: (855) 864.7776
15 Administrative Functions
15.1 Users
The users that have access for an account are accessable via a request to the users resource on the account.
15.2 Managing User Passwords
Although at this time the set of users that can access an account is managed directly by Bandwidth Personnel,
it is possible to manage the password for a user. This function is constrained so that a user may only reset
their own password, and must place the API call using those credentials.
The password has a minimum length of 6 characters and a maximum length of 20.
In the case of a lost password Bandwidth support personnel can provide a password reset.