Skip to content

Instantly share code, notes, and snippets.

@dtolb

dtolb/iris.md

Created June 14, 2017 16:40
Show Gist options
  • Save dtolb/7173dba81d63fe88ea8dca87d2ee600c to your computer and use it in GitHub Desktop.
Save dtolb/7173dba81d63fe88ea8dca87d2ee600c to your computer and use it in GitHub Desktop.
Download ZIP
md
Raw
iris.md

Bandwidth Dashboard REST API Documentation API documentation version v1

http://null

/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.
PeerIdThe 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>
ParameterDescription
TelephoneNumberListA list of telephone numbers to order
AreaCodeAllowed ranged: [2-9] for the first digit and [0, 9] for both the second and third digits.
RateCenterA text Rate Center name. Must be combined with State information
StateThe two-letter abbreviation of the state
CityThe name of the city that the Ordered telephone numbers should apply to
ZipA five-digit (XXXXX) or nine-digit (XXXXX-XXXX) format value.
LataA maximum five-digit (XXXXX) numeric format.
EnableLCAIf 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 EnableLCANpaNxx 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.
LocalVanityA text string used to request a regular vanity number. Valid range is between 4 and 7 alphanumeric characters.
EndsInIntended 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.
TollFreeVanityA text string used to request a toll free vanity number. Valid range is between 4 and 7 alphanumeric characters.
TollFreeWildCardPatternA 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.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment