Bandwidth Dashboard REST API Documentation API documentation version v1

/accounts

The account is the root resource for many of the operations in the Bandwidth Dashboard API.
The account is represented by an account id, which is the resource that represents a Bandwidth customer, providing a root resource for all of the customer's attributes and services
The API calls that are used to manage the details of a customer account, and to manage the resources that a Bandwidth customer has access to or control over, are accessed through the /accounts resource.

/accounts

post (secured): Create an Account
get (secured): Retrieve information about the an account or set of accounts, as guided by optional search parameters.

/accounts/{accountId}

This API retrieves and updates an account's information as specified by the given account ID. Access to information pertaining to a specific account will require credentials that have been assigned to that account, preserving the security of a customer’s information.
Note that DELETE is currently unsupported.

put (secured): Updates Account. Note that the body is similar in structure to POST for /accounts
get (secured): This API call retrieves information about the account indicated by the Account ID.

/accounts/{accountId}/availableNumbers

The /availableNumbers API call searches for available phone numbers based on one or more of the following criteria:

Area Code
NPA-NXX
NPA-NXX with Local Area Calling
NPA-NXX-X
NPA-NXX-X with Local Area Calling
RateCenter
RateCenter with Local Area Calling
State
City/State
Zip Code
LATA
Local Vanity
TollFree Vanity
TollFree WildCard Pattern

Each choice above has required and optional parameters. Some search parameters can be combined with others. Allowed search criteria are limited in case of search by Local Calling Area (see restrictions below).

Search Criteria	Required Parameters	Combinable Parameters	Optional Parameters
Area Code	areaCode	rateCenter (state required) city (state required) state lata zip	quantity enableTNDetail protected
NPA-NXX	npaNxx	rateCenter (state required) city (state required) state lata zip orderBy	quantity enableTNDetail protected
NPA-NXX with Local Calling Area	npaNxx		quantity LCA enableTNDetail protected
NPA-NXX-X	npaNxxx	rateCenter (state required) city (state required) state lata zip orderBy	quantity enableTNDetail protected
NPA-NXX-X with Local Calling Area	npaNxxx		quantity LCA enableTNDetail protected
RateCenter	rateCenter state	city areaCode/npaNxx/npaNxxx lata zip orderBy	quantity enableTNDetail protected
RateCenter with Local Calling Area	rateCenter state		quantity LCA enableTNDetail protected
State	state	rateCenter city areaCode/npaNxx/npaNxxx lata zip	quantity enableTNDetail protected
City	city state	rateCenter state areaCode/npaNxx/npaNxxx lata zip orderBy	quantity enableTNDetail protected
Zip Code	zip	rateCenter (state required) city (state required) state areaCode/npaNxx/npaNxxx lata orderBy	quantity enableTNDetail protected
LATA	lata	rateCenter (state required) city (state required) state areaCode/npaNxx/npaNxxx zip	quantity enableTNDetail protected
Local Vanity	areaCode localVanity		endsIn quantity protected enableTNdetails
TollFree Vanity	tollFreeVanity	orderBy	quantity
TollFree WildCard	tollFreeWildCardPattern	orderBy	quantity

Parameters

Description

areaCode

The allowed number ranges are [2-9] for the first digit and [0-9] for both the second and third digits.

npaNxx or npaNxxx

NPA NXX combination to be searched.
Valid npa values:[2-9] for the first digit, and [0-9] for both the second and third digits.
Valid Nxx values:[2-9] for the first digit, and [0-9] for both the second and third digits.
Valid x values [0-9].

rateCenter

The abbreviation for the Rate Center

state

The two-letter abbreviation of the state the RateCenter is in.

city

The name of the city.

zip

A five-digit (XXXXX) or nine-digit (XXXXX-XXXX) zip-code value.

lata

A maximum five digit (XXXXX) numeric format.

localVanity

Requested vanity number. Valid range is from 4 to 7 alphanumeric characters

tollFreeVanity

The Toll Free requested vanity number. Valid range is from 4 to 7 alphanumeric characters

tollFreeWildCardPattern

The requested Toll Free 3 digit wild card pattern. Examples: 8**, 80*, 87*, etc.

quantity

The desired quantity of requested numbers. Values range from 1-5000. If no quantity is specified, the default of 5000 is returned.

enableTNDetail

If set to true, a list of details associated with the telephone number (rate center abbreviation, rate center host city, state, and LATA) will be displayed along with the telephone number. This value is set to false by default.

LCA

Local Calling Area. If this parameter is specified then Telephone Numbers that are likely in the Local Calling Area of the stated Rate Center, NPANXX or NPANNXX will be returned, in addition to those that *exactly* match the query will be returned. Since LCA logic is not always symmetric and not always inclusive of RC and NPANXX search criteria, this result reflects somewhat of an approximation. The parameter value is true or false. The default is true

endsIn

Intended to use with localVanity only. The parameter value is true or false. If set to true, the search will look for only numbers which end in specified localVanity, otherwise localVanity sequence can be met anywhere in last 7 number digits. The default is false.

orderBy

The field by which the returned numbers will be sorted. Only supported if at least one of the following search criteria is specified: npaNxx or npaNxxx, rateCenter, city, zip, tollFreeVanity, tollFreeWildCardPattern. Allowed values are fullNumber, npaNxxx, npaNxx, and areaCode>

protected

A query parameter, that governs, how the Protected status of numbers impacts the search results
The overall behavior of the protected search values are described in the table below:

Query Parameter	Description
NONE	The numbers returned in the payload will not contain any numbers that are tagged as Protected
ONLY	The numbers returned in the payload will all be tagged as Protected. No "unProtected" numbers will be returned
MIXED	The protected status of the numbers will be ignored in the search - all types of numbers will be returned

get (secured): Retrieves the phone numbers according to the input parameters

/accounts/{accountId}/orders

An attempt to order Telephone Numbers into an account creates an order record that is maintained by the Bandwidth Dashboard to trace the attempt to order the Telephone Numbers, and provide feedback on the success or failure of that attempt.
The order is identified by an order-id that can be used to uniquely identify the order attempt, and to access a record of the request and the result.
There are a number of independent kinds of new number order, intended to search for and obtain numbers using different search criteria. Some of the applicable search criteria are:

NPA / Area Code
NPA-NXX combination
State
Rate Center and State, with or without a Local Calling Center constraint
City and State
ZIP Code
LATA
Local Vanity
Peer ID

get (secured): GET is used to retrieve order ids and order details for previously attempted Telephone Number orders.
post (secured): A POST creates a request for Telephone Numbers

A POST on the /orders resource is used to request that the system provide one or more TNs for use by the account. The post creates a new number order record to preserve the request, as well as the response of the Bandwidth Dashboard to the request. A well-formed POST on the /orders resource will create an order record, and return an order-id string that can be used to uniquely identify the new number order request. The details of success and failure of the request for TNs will be preserved and linked to the returned order id.

The order-id is returned in the Location Header, allowing the API user immediate access to the order.

There are multiple ways that new telephone numbers can be requested. The various request payloads are documented below.

Common values in all request payloads include:

Parameter	Description
Quantity	The desired quantity of requested numbers. values range from 1-5000. If no quantity is specified, the default of 5000 is returned.
name	The name of the order. Max length restricted to 50 characters.
CustomerOrderId	Optional value for Id set by customer
SiteId	The ID of the Site that the SIP Peer is to be associated with.
PeerId	The ID of the SIP Peer that the telephone numbers are to be assigned to.
PartialAllowed	By default all order submissions are fulfilled partially. Setting the PartialAllowed to false would trigger the entire order to be fulfilled (any error ecnountered such as 1 TN not being available would fail all TNs in the order) By default, this value is set to false
BackOrderRequested	BackOrderRequested will indicate to the system that if the entire quantity of numbers is not available on the first attempt to fill the new number order, the request will be repeated periodically until the request is successful or cancelled. Setting the parameter to true indeicated a desire to backorder numbers if the entire quantity is not available

The following POST payload elements are not common to all orders. They are specific to one or more types of orders:

<tr>
    <td>ReservationIdList</td><td>If a telephone number or numbers have been previously reserved, the ReservationIdList provides the IDs necessary to release the numbers.  This only applies to reserved numbers - if no reservation has been placed on the numbers this list is not required.</td>
</tr>
<tr>
    <td>TnAttributes</td>
    <td>Attributes to be assigned to the telephone number. Optional parameter. Possible values: "Protected"</td>
</tr>

Parameter	Description
TelephoneNumberList	A list of telephone numbers to order
AreaCode	Allowed ranged: [2-9] for the first digit and [0, 9] for both the second and third digits.
RateCenter	A text Rate Center name. Must be combined with State information
State	The two-letter abbreviation of the state
City	The name of the city that the Ordered telephone numbers should apply to
Zip	A five-digit (XXXXX) or nine-digit (XXXXX-XXXX) format value.
Lata	A maximum five-digit (XXXXX) numeric format.
EnableLCA	If set to true, local calling access numbers will be returned for Rate Center, NPA-NXX and NPANXXX orders if numbers are not available for the given criteria. Default is true.
Npa-Nxx or Npa-Nxxxx with EnableLCA	NpaNxx combination to be searched. Valid Npa values: [2-9] for the first digit, and [0-9] for both the second and third digits. Valid Nxx values: [2-9] for the first digit, and [0-9] for both the second and third digits. Valid Xxvalues [0-9]. if set to true, enables the ability to get local calling access numbers if numbers are not available for the given criteria.
LocalVanity	A text string used to request a regular vanity number. Valid range is between 4 and 7 alphanumeric characters.
EndsIn	Intended to use with LocalVanity only. The parameter value is true or false. If set to true, the search will look for only numbers which end in specified LocalVanity, otherwise LocalVanity sequence can be met anywhere in last 7 number digits. The default is false.
TollFreeVanity	A text string used to request a toll free vanity number. Valid range is between 4 and 7 alphanumeric characters.
TollFreeWildCardPattern	A 3-digit wild card pattern for specifying toll free prefixes, comprised of 8 followed by two stars, a digit and a star or two digits

Putting it all together

The request to order numbers is performed via a POST to the /orders resource. As indicated above, the payload of this POST varies depending on the type of search that is to be performed for the numbers, with a unique payload element used to indicate each different order type.

The unique components of the payload are described in the table below. These are combined with the common payload elements in the first table above to create a full order payload. Some complete payloads are captured in the examples.

Payload segment	Description
<ExistingTelephoneNumberOrderType> <TelephoneNumberList> <TelephoneNumber>9193752369</TelephoneNumber> <TelephoneNumber>9193752720</TelephoneNumber> <TelephoneNumber>9193752648</TelephoneNumber> </TelephoneNumberList> <ReservationIdList> <ReservationId>[GUID]</ReservationId> <ReservationId>[GUID]</ReservationId> </ReservationIdList> </ExistingTelephoneNumberOrderType>	Order a set of numbers known to be available. This often results if the numbers have been found using a separate availableNumbers search If the numbers have previously been reserved, a reservation id must be included
<AreaCodeSearchAndOrderType> <AreaCode>617</AreaCode> <Quantity>1</Quantity> </AreaCodeSearchAndOrderType>	Allowed ranges ~ [2-9] for the first digit and [0, 9] for both the second and third digits.
<RateCenterSearchAndOrderType> <RateCenter>RALEIGH</RateCenter> <State>NC</State> <Quantity>1</Quantity> </RateCenterSearchAndOrderType>	Specify the Rate Center and the State
<NPANXXSearchAndOrderType> <NpaNxx>919439</NpaNxx> <EnableTNDetail>true</EnableTNDetail> <EnableLCA>false</EnableLCA> <Quantity>1</Quantity> </NPANXXSearchAndOrderType>	Specify the NpaNxx combination to be ordered. Valid Npa values ~ [2-9] for the first digit, and [0-9] for both the second and third digits. Valid Nxx values ~ [2-9] for the first digit, and [0-9] for both the second and third digits. A similar approach is viable for NPANXXXX. The EnableLCA flag turns LCA search on or off.
<TollFreeVanitySearchAndOrderType> <Quantity>1</Quantity> <TollFreeVanity>newcars</TollFreeVanity> </TollFreeVanitySearchAndOrderType>	Specify a Toll Free Vanity search, where the numbers ordered match a specific alphanumeric pattern between 4 and 7 characters long
<TollFreeWildCharSearchAndOrderType> <Quantity>1</Quantity> <TollFreeWildCardPattern>8**</TollFreeWildCardPattern> </TollFreeWildCharSearchAndOrderType>	Specify the Toll Free wild card pattern. to be ordered, comprised of 3 digits beginning with '8'. Examples are 8*, 87, etc.
<StateSearchAndOrderType> <Quantity>1</Quantity> <State>NC</State> </StateSearchAndOrderType>	Specify the State to be searched for telephone numbers
<CitySearchAndOrderType> <Quantity>1</Quantity> <City>RALEIGH</City> <State>NC</State> </CitySearchAndOrderType>	Specify the City and State to be ordered from.
<ZIPSearchAndOrderType> <Quantity>1</Quantity> <Zip>27606</Zip> </ZIPSearchAndOrderType>	Specify the Zip Code to be ordered from.
<LATASearchAndOrderType> <Quantity>1</Quantity> <Lata>224</Lata> </LATASearchAndOrderType>	Specify the LATA to order telephone numbers from.
<CombinedSearchAndOrderType> <Quantity>1</Quantity> <AreaCode>617</AreaCode> <RateCenter>RALEIGH</RateCenter> <State>NC</State> <NpaNxx>919439</NpaNxx> <NpaNxxX>9194391</NpaNxxX> <Lata>224</Lata> <City>RALEIGH</City> <Zip>27606</Zip> <EnableLCA>false</EnableLCA> </CombinedSearchAndOrderType>	Specify the any combination of: AreaCode RateCenter State NpaNxx NpaNxxX Lata City Zip But with following limitations: Parameters AreaCode, NpaNxx and NpaNxxX are mutually exclusive LCA search is supported only for one of the following criteria: NpaNxx NpaNxxX RateCenter and State If City or RateCenter is specified then State is required
<CombinedSearchAndOrderType> <Quantity>1</Quantity> <AreaCode>617</AreaCode> <LocalVanity>newcars</LocalVanity> <EndsIn>false</EndsIn> </CombinedSearchAndOrderType>	Specify AreaCode and LocalVanity to order telephone numbers matching a specific alphanumeric pattern between 4 and 7 characters long. Limitations: AreaCode is always required No parameter combinations are allowed here This order type is unsupported with BackOrderRequested=true
<TnAttributes> <TnAttribute>Protected</TnAttribute> </TnAttributes>	Specify TnAttribute to be assigned to the ordered telephone numbers.

Some examples of POST payloads for some orders are below...

/accounts/{accountId}/orders/{orderid}

The orderid is an explicit link to a single new number order in the Bandwidth Dashboard, and can be used to retrieve information about that new number order including:

Order status information
Order outcome
order created and modified dates
The telephone numbers that were successfully ordered
The details of the order request

get (secured): GET all of the details associated with an identified order
put (secured): With the introduction of Backorder capabilities, new number orders may stay in backordered state 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. The fields that can be updated are...

The order name
The customer order id
The backordered state.

Specifying a <CloseOrder> value of true will cancel the backorder request, leaving the currently ordered numbers on the account. No further numbers will be added to the account as a result of the order.

/accounts/{accountId}/orders/{orderid}/areaCodes

Retrieves the area codes of the phone numbers from the specified order.

get (secured): Retrieves the area codes of the phone numbers from the specified order.

/accounts/{accountId}/orders/{orderid}/npaNxx

Retrieves the Npa-Nxx of the phone numbers from the specified order.

get (secured): Retrieves the Npa-Nxx of the phone numbers from the specified order.

/accounts/{accountId}/orders/{orderid}/totals

Retrieves the total quantity of phone numbers from the specified order.

get (secured): Retrieves the total quantity of phone numbers from the specified order.

/accounts/{accountId}/orders/{orderid}/tns

The TNs resource accesses the Telephone Numbers associated with the given order ID of the given site ID of the given account.

get (secured): returns a list of phone numbers associated with the ID of a given account.

dtolb/iris.md

Bandwidth Dashboard REST API Documentation API documentation version v1

/accounts

/accounts

/accounts/{accountId}

/accounts/{accountId}/availableNumbers

/accounts/{accountId}/orders

/accounts/{accountId}/orders/{orderid}

/accounts/{accountId}/orders/{orderid}/areaCodes

/accounts/{accountId}/orders/{orderid}/npaNxx

/accounts/{accountId}/orders/{orderid}/totals

/accounts/{accountId}/orders/{orderid}/tns