bandwidth dashboard api principles version 2015 · pdf filecustomer experience &...

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

http://www.bandwidth.com/


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





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.





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.


http://en.wikipedia.org/wiki/Representational_state_transfer

http://hc.apache.org/httpcomponents-client-ga/examples.html

http://hc.apache.org/httpcomponents-client-ga/examples.html




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


https://test.dashboard.bandwidth.com/

https://dashboard.bandwidth.com/




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.





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.





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.





5.1 Example Configuration of Sites and SIP Peers





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





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.





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.





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





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





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.


https://baseurl/accounts/%3caccountid%3e/orders/%3corder-id




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


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.


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


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.





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.





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:





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.





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:





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.





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.





11 Disconnecting Phone Numbers

A POST to the /disconnects resource is used to disconnect telephone numbers from the account.





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





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>





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





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”.





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.





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





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





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.





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.


bandwidth dashboard api principles version 2015 · pdf filecustomer experience &...

Documents