Test MD

test.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/{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.

• 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}/inserviceNumbers

This API call will find the in-service numbers on the indicated account.
The inservicenumbers query will return all of the in-service numbers on the account, filtered with a wide range of search query parameters. Note that many search combinations will not return a meaningful result because the search parameters are mutually exclusive. Since mutually exclusive search criteria result from data that can't satisfy all of the criteria, these are not flagged as errors, and instead simply return an empty result.

• get (secured): Retrieves a list of in-service phone numbers associated with the account ID. There are multiple search parameters for searching for in-service numbers:

• size and page for pagination
• area code
• Npa-Nxx
• LATA
• state
• rate center

/accounts/{accountId}/inserviceNumbers/totals

A GET on this resource returns the total number of in-service numbers for the given account.

• get (secured): Returns the total number of in-service numbers for the given account.

/accounts/{accountId}/inserviceNumbers/{tn}

This resource acts as a verifier for in-service telephone numbers.

• get (secured): A GET on the number desired will return a 200 OK if the number is in service on the account, or a 404 not found.

/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:

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
ReservationIdList	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.
TnAttributes	Attributes to be assigned to the telephone number. Optional parameter. Possible values: "Protected"

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.

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

The /notes resource manages a note or set of notes associated with an order. Notes can only be appended to the collection, and are not individually addressable or modifiable once added.

• post (secured): Updates the Notes resource by adding a note.
• get (secured): Retrieve the set of notes associated with an order.

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

History information is available on orders that have gone through multiple transitions, which is possible in the case that telephone numbers are backordered. In this case the order will have one or more OrderHistory records associated with it, detailing the set of events that have affected the order.

• get (secured): Retrieve the history information associated with an order

/accounts/{accountId}/lnpchecker

The lnpchecker resource performs a portability analysis for a set ot TNs, returning information about the coverage and losing carrier characteristics of the TNs allowing a better assessment of which port requests to submit.

• post (secured): Request portability information on a set of TNs

/accounts/{accountId}/portins

The portins endpoint is used to manage requests to port a number into the Bandwidth Dashboard. Like many other requests, the portins endpoint causes the creation of an order that is used to manage the porting event throughout the lifecycle of the request. The various sub-resources and methods are covered in greater detail below. The elements used or supplied in the payloads are described in the following table...

Parameter	Required	Description
accountid	No	The account ID for porting the numbers.
CustomerOrderId	No	Internal customer order id for tracking the order
RequestedFocDate	No	If not entered, the next available FOC date will be used. It if is entered, order will be rejected if date is earlier than losing carriers minimum number of days to port-out or if date is a weekend or holiday. Format is ISO8601 encoding of ZULU/UTC/GMT such as “2013-05-10T15:14:22Z”. If the port is capable of on demand activation then the time value in the request considered to be the default activation time of the port.
AlternateSpid	No	Unique customer SPID associated with Bandwidth.
BillingTelephoneNumber	Yes	Account or Billing telephone number for order. Porting telephone number for most wireline ports.
SubscriberType	Yes	(BUSINESS, RESIDENTIAL) If residential, order will be rejected if a BusinessName is entered.
BusinessName	No	Subscriber business name.
FirstName	No	Subscriber first name.
MiddleInitial	No	Subscriber middle initial.
LastName	No	Subscriber last name.
HouseNumber	Yes	Street address number.
HousePrefix	No	Street address number prefix
HouseSuffix	No	Street address number suffix.
PreDirectional	No	Street address pre-directional.
StreetName	Yes	Street name.
StreetSuffix	No	Street suffix.
PostDirectional	No	Street address post directional.
AddressLine2	No	Put unit, suite, floor, etc. here.
City	Yes	City.
StateCode	Yes	Two letter state code.
Zip	Yes	Zip code.
PlusFour	No	Zip + 4.
Country	No	Country.
AddressDetail1, AddressValue1, AddressDetail2, AddressValue2, AddressDetail3, AddressValue3	No	Additional details can optionally be added to the address to specify address refinements such as Building, Basement, etc. See the USPS Postal Address Format - pub28 for detail.
LoaAuthorizingPerson	Yes	First and last name of person who authorized LOA.
AccountNumber	No	Account number, typically required for wireless ports.
PinNumber	No	PIN Number, often required for wireless ports.
PhoneNumber	Yes	Ten digit phone number with no dots or dashes. One or more is required. Use a PhoneNumber tag for each phone number in the list.
siteid	Yes	See section on Sites
PeerId	No	See section on SIP Peers
PartialPort	No	By default all portin orders are classified as full ports. If the attribute PartialPort is specified as true, the order will be submitted as a partial port
Triggered	No	(true|false) If present and set to true, this port will be treated as one that will be manually activated. If this value is set it is assumed that the customer will manually activate the port, and that the Bandwidth Dashboard will activate the port at a default activation time if the customer does not manually activate the port. This is not supported for wireless ports, and cannot be changed via a SUPP.

• get (secured): Retrieves the port-in requests for the given account ID.
• post (secured): Creates a port-in request under the given site ID and sippeer ID as specified in the body.
  Upon a successfully-submitted payload, the order will have a status of "PENDING_DOCUMENTS".
  In order to have a successful POST, the payload will need to have a specific site ID and sippeer ID, according to the account.
  
  TnAttributes - attributes to be assigned to the telephone number. Optional parameter. Possible values: "Protected"

/accounts/{accountId}/portins/{orderid}

This resource retrieves information associated with the port-in associated with the ID number specified.

• get (secured): Retrieves the information associated with the specified port-in ID number.

• put (secured): It is possible to change ("SUPP" in LNP terms) an existing LNP order. This is done via a PUT on the existing order-id. Since many of the entries in an LNP Order cannot be changed after the initial order is placed (the list to TNs for example) the PUT on a porting order-id does not require that the full order payload is included.
  

• delete (secured): Cancels the port-in order. This does not remove the order from the system. It simply places the existing order in a canceled state. Note that only a pending port-in order can be canceled; if the order was previously canceled or completed, then a DELETE will not be possible.

/accounts/{accountId}/portins/{orderid}/notes

The /notes resource manages a note or set of notes associated with an order. Notes can only be appended to the collection, and are not individually addressable or modifiable once added.

• post (secured): Updates the Notes resource by adding a note.
• get (secured): Retrieve the set of notes associated with an order.

/accounts/{accountId}/portins/{orderid}/history

This resource retrieves the history of a port-in order.

• get (secured): Retrieves the history of the specified port-in order.

/accounts/{accountId}/portins/{orderid}/activationStatus

• get (secured): Retrieve the currently activated status for customer activated (triggered) portin orders. The payload returns the list of activated TNs associated with the order. It also returns a list of the TNs associated with the order that have not yet been activated
  
  At this time all phone numbers associated with a PON will be activated at the same time, but a change to per-TN activation is coming and will use the same basic payload and activation model.

• put (secured): Sets the activation time for the portin order.
  
  This API call is currently used to set the Activation time of the customer activated (triggered) port.

• If the time is in the past all of the TNs in the portin request will be activated 'immediately'.
• If the time is within the three days after the approved FoC date, the auto-activation time for the port will be set to that time

Activation of individual telephone numbers will be enabled in a future release, but are not currently modifiable via this API

/accounts/{accountId}/portins/{orderid}/loas

The LOAS resource allows the uploading and storage of files that are associated with port-in orders. Port-in uploads use the standard form-data approach for http file upload. Details of the POST API call that drives the file upload are provided below.
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")

The file upload is equivalent of the use of CURL to upload a file...

curl -H 'Content-Type: ' --data-binary "@" –iv /portins//loas

an example for the upload of a pdf file is...

curl -H 'Content-Type: application/pdf' --data-binary "@Test_LOA.pdf" -iv /portins//loas


• get (secured): Retrieves the list of the loa (and other) files associated with the portin order
• post (secured): POSTing to the /loas resource will enable the upload of the file. The key attribute to the POST is ensuring that the headers are correctly set to support the file upload.
  
  Header settings typical of a valid upload are...
  
  

Host: api.inetwork.com
Authorization: Basic xxxxxxxxxxxxxxxxxxxx==
Content-Type: application/pdf
Accept: */*
Accept-Encoding: gzip, deflate
Accept-Language: en-US,en;q=0.8
Cache-Control: no-cache

----WebKitFormBoundaryE19zNvXGzXaLvS5C
Content-Disposition: form-data; name="george"; filename="Bandwidth Dashboard.pdf"
Content-Type: application/pdf


----WebKitFormBoundaryE19zNvXGzXaLvS5C


/accounts/{accountId}/portins/{orderid}/loas/{fileid}

A GET on the loas file resource will cause the downloading of the file in a manner consistent with typical browser file downloads.

• get (secured): Retrieves the list of the loa (and other) files associated with the portin order
• put (secured): A PUT on the filename will update / replace the identified file id. The format of the PUT is identical to that of the POST.
  Header settings typical of a valid upload are...
  

Host: api.inetwork.com
Authorization: Basic xxxxxxxxxxxxxxxxxxxx==
Content-Type: application/pdf
Accept: */*
Accept-Encoding: gzip, deflate
Accept-Language: en-US,en;q=0.8
Cache-Control: no-cache

----WebKitFormBoundaryE19zNvXGzXaLvS5C
Content-Disposition: form-data; name="george"; filename="Bandwidth Dashboard.pdf"
Content-Type: application/pdf


----WebKitFormBoundaryE19zNvXGzXaLvS5C


• delete (secured): Retrieves the list of the loa (and other) files associated with the portin order

/accounts/{accountId}/portins/{orderid}/loas/{fileid}/metadata

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].
Naming of the existing "loas" API has been preserved to ensure backwards compatibility.

• get (secured): Retrieves the metadata associated with the file.

• put (secured): Associate metadata with the file named in the resource path. This will describe the file, and declare the data that is contained in the file, selected from a list of [LOA | INVOICE | CSR | OTHER].

• delete (secured): Deletes the metadata previously associated with the identified file.

/accounts/{accountId}/portins/{orderid}/areaCodes

Retrieves a list of all area codes of the telephone numbers associated with the specified port-in number.

• get (secured): Retrieves a list of area codes associated with the specified port-in number and displays them in the payload.

/accounts/{accountId}/portins/{orderid}/npaNxx

Retrieves a list of all Npa-Nxx of the telephone numbers associated with the specified port-in number.

• get (secured): Retrieves a list of Npa-Nxx associated with the specified port-in number and displays them in the payload.

/accounts/{accountId}/portins/{orderid}/tns

Retrieves a list of all telephone numbers associated with the specified port-in number.

• get (secured): Retrieves a list of telephone numbers associated with the specified port-in number and displays them in the payload.

/accounts/{accountId}/portins/{orderid}/totals

Retrieves a total count of telephone numbers associated with the specified port-in number.

• get (secured): Retrieves a total count of telephone numbers associated with the specified port-in number and displays them in the payload.

/accounts/{accountId}/portins/totals

This resource interacts with the total number of port-ins associated with an account.

• get (secured): Retrieves the total count of port-ins.

/accounts/{accountId}/disconnects

Use this method to disconnect telephone numbers from the account.
This call creates a disconnects order that can be used to track the disconnection of the numbers.

Parameter	Description
accountid	The numerical Account ID that you will be disconnecting the numbers from.
Name	The name of the order. Max length restricted to 50 characters
TelephoneNumberList	A list of telephone numbers to disconnect.
DisconnectMode	The severity of disconnect order. Optional parameter. Typically normal.
Protected	Change protected status of telephones during disconnection. Optional parameter. Possible values: TRUE, FALSE, UNCHANGED. Typically UNCHANGED.

• get (secured): retrieve a list of disconnect orders that is associated with an account
• post (secured): Create a Disconnect order, and disconnect the numbers listed in the disconnect order.

/accounts/{accountId}/disconnects/{disconnectid}

This method retrieves the information associated with the disconnect order specified.

• get (secured): Retrieves the information associated with the disconnect order specified.

/accounts/{accountId}/disconnects/{disconnectid}/notes

The /notes resource manages a note or set of notes associated with an order. Notes can only be appended to the collection, and are not individually addressable or modifiable once added.

• post (secured): Updates the Notes resource by adding a note.
• get (secured): Retrieve the set of notes associated with an order.

/accounts/{accountId}/discnumbers

This API call provides information on numbers that have been disconnected from an account.

• get (secured): Retrieves a list of disconnected numbers associated with the account. There are optional search parameters to limit the discNumbers payload

/accounts/{accountId}/discnumbers/totals

Retrieves a total number of disconnects for the account within the specified (optional) date range.

• get (secured): Retrieves a total number of disconnects.

/accounts/{accountId}/hosts

• get (secured): Retrieve information about the hosts of account, as guided by optional search parameters.

/accounts/{accountId}/portouts

This resource deals with the port-out requests of the account ID; this resource can retrieve a port-out request .

• get (secured): Retrieves a list of port-out requests for the given account ID.

/accounts/{accountId}/portouts/{orderid}

This resource retrieves information associated with the port-out ID number specified.

• get (secured): Retrieves the information associated with the specified port-out ID number.

/accounts/{accountId}/lsrorders

The lsrorders resource is used to create, modify, and monitor API requests to remove telephone numbers from the Bandwidth network. This API call is intended for use by carriers that want to automate the "Port-out" process with Bandwidth, rather than manually request the removal or "port-out" of each telephone number via a GUI or a Ticket.

This API call uses an asynchronous model that is common in the Bandwidth Dashboard API, where an "order" is created that is then subsequently used to track the progress of the request to completion. This in somewhat analogous to the "laundry ticket" model, where the initial transaction is the submission of the laundry and the receipt of a ticket, and all other steps in the overall transaction use the identifier on the ticket to monitor and manage the transaction.

In this case a POST is made to the /lsrorders resource that describes the request to port out the number. If the POST has no syntactic errors, such as a telephone number with less than 10 digits, an ID will be returned that is used to monitor and manage the port-out request. The POST returns both a descriptive payload that reflects the request and includes the identifier, as well as a Location header that contains a valid GET API call that can be used to retrieve the current state of the LSR / Port-out request. In general the flow of events is much like...

        Carrier   ----->    POST        ----->      Bandwidth - the initial request
                 <-----     200 OK     <-----                 - the response with a payload 
                                                                and a Location header


        -- some subsequent event happens... an error, or the completion of the request --


        Carrier <----- Notification Callback <----- Bandwidth - if configured, Bandwidth 
                                                                notifies the carrier of all
                                                                events that impact the order
                                                              - see the /subscriptions and 
                                                                /callbacks API descriptions
        Carrier   ----->    GET(id)     ----->      Bandwidth - the carrier requests the 
                                                                complete status of the order
                                                                using the ID
                 <-----     200 OK     <-----                 - the response with a descriptive
                                                                payload


The above notifications continue until the LSR is complete or cancelled.

There is a complete list of elements in payload of the POSTed request below in the documentation of the POST, but in summary the LSR request includes

• a list of telephone numbers
• information about the subscriber
• tracking information such as a PON and a Customer Order ID
• winning carrier information such as the SPID
• date information

This API supports GET for retrieving order detail and status informantion, POST for creating a new LSR Order, and PUT for changing the details of an LSR in flight.

Errors

There are a number of errors that can happen at various stages of the process. These are listed here for convenience, and can be found in the error reference documentation here.

Error code	Error message	Appearance
5008	All telephone numbers specified are invalid	POST
7104	Subscriber information is required	POST/PUT
7105	The subscriber name is required	POST/PUT
7107	The service address is required	POST/PUT
7108	The service address house number is required	POST/PUT
7109	The service address street name is required	POST/PUT
7110	The service address city is required	POST/PUT
7111	The service address state code is required	POST/PUT
7112	The service address zip code is required	POST/PUT
7120	The PON is required	POST
7203	The billing telephone number (BTN) is invalid	POST/PUT
7208	The requested FOC date cannot be in the past	POST/PUT
7214	ZIP code is invalid	POST/PUT
7318	Customer order ID is invalid. Only alphanumeric values, dashes and spaces are allowed. Max length is 40 characters.	POST/PUT
7324	The business name is too long. The business name should not be longer than 25 characters.	POST/PUT
7354	Middle initial is too long. Middle initial should not be longer than 1 character.	POST/PUT
7355	First name is too long. First name should not be longer than 25 characters.	POST/PUT
7356	Last name is too long. Last name should not be longer than 25 characters.	POST/PUT
7395	Unsupported state code %s.	POST/PUT
7510	Required Account Code missing	PROCESSING
7511	Invalid Account Code	PROCESSING
7512	Required PIN missing	PROCESSING
7513	PIN Invalid	PROCESSING
7514	Required ZIP Code missing	PROCESSING
7515	Invalid ZIP Code	PROCESSING
7516	Telephone Number not recognized or invalid for this account	PROCESSING
7517	Too many Telephone numbers in this request	PROCESSING
7518	Telephone Number Not Active	PROCESSING
7519	Customer info does not match	PROCESSING
7598	Invalid Request	PROCESSING
7599	Fatal Error in Processing	PROCESSING
7999	An internal error has occurred. Please contact support if this issue is not resolved in 1 business day	PROCESSING
13522	The count of telephone numbers in order exceeds the maximum size of %d	POST
17000	Lsr submission order payload required.	POST/PUT
17002	Order contains invalid tns %s.	POST
17003	Order contains empty tn list or its not present.	POST
17004	Incorrect pon specified. It must be up to 25 character long and could not contain special characters other than -_#	POST
17005	Toll-free telephone numbers can not be present in the LSR order.	POST
17006	Account number is incorrect. It should be alphanumeric and no more than 32 characters long.	POST/PUT
17007	Pin number is incorrect. It should be alphanumeric and no more than 10 characters long.	POST/PUT
17008	An internal error has occurred. Please contact support if this issue is not resolved in 1 business day	PROCESSING
17009	Lsr order contain duplicate telephone numbers %s	POST
17010	Business name is required for business SubscriberType.	POST/PUT
17011	Last name should be empty for business SubscriberType.	POST/PUT
17012	Last name is required for residential SubscriberType.	POST/PUT
17013	Requested date format incorrect. Date should be in yyyy-mm-dd format. (example 2015-03-24).	POST/PUT
17017	Lsr order failed account SPID not configured.	PUT/PROCESSING
17018	Lsr order will be cancelled. All other submitted changes are ignored.	PUT/PROCESSING
17019	Requested FOC date cannot be on holiday or weekend.	POST/PUT
17020	Account SPID [%s] does not match with SPID specified in the Lsr order [%s].	POST/PUT
17021	Incorrect SPID [%s] specified in the order. It should be alphanumeric and no more than 4 characters long.	POST/PUT
17022	Account %d requires a SPID to be provided with each order.	POST/PUT
17023	The authorizing person contact is required for lsr orders.	POST/PUT
17024	The authorizing person contact is too long. It should be not longer than %s characters.	POST/PUT
17025	%s field%s cannot be modified.	PUT
17025	OrderStatus cannot be changed to %s. Only cancelled value allowed.	PUT
17027	Account %d has no configured SPID. Please contact support for further assistance.	POST/PUT
17028	Minimum FOC date for a port of greater than %1$d telephone numbers is %2$d days	POST/PUT
17029	Can't modify LSR order, because it contains ported numbers.	PROCESSING
17030	LSR order completion failed, some numbers are not activated: %s.	PROCESSING
17031	Order was failed, because some telephone numbers have empty SPID [%s]	PROCESSING
17032	The Specified PON is already present in our system. Please provide an alternative.	POST
17033	The PON specified in the LSR order overlaps with existing order. Please resubmit the order with another PON.	POST
17034	OverrideValidation flag can be supped only in EXCEPTION status.	PUT
17035	Supp is not allowed for this LSR. Please contact support if this issue is not resolved in 1 business day.	PUT

POST - errors occur during LSR creation.
PUT - errors occur during LSR supp/cancel.
PROCESSING - errors occur while LSR processing. These errors are persistent and can be retrieved using GET requests (ex. by LSR ID).

* Error messages can differ from described depending on context of occurrence.

• get (secured): Retrieves a list of lsrorders. Various query parameters can be used to filter the list of LSR Orders as documented below.

• post (secured): A POST creates a lsrorder request to initiate a port-out action.
  The payload fields are described below...
  

Pon	The Pon is customer specified order indentifier field. Allowed alphanumeric and "#","-","_". Up to 25 characters long. (required).
CustomerOrderId	The CustomerOrderId is customer specified order indentifier field. Allowed alphanumeric, spaces and dashes. Up to 40 characters long. (optional).
SPID	Identifier used in porting process. If account is no multi-SPID option - default with account value, otherwise value is required. Up to 4 characters long. (required)
BillingTelephoneNumber	Non-tollfree 10 digit phone number (optional).
RequestedFocDate	optional (next day if not specified).
SubscriberType	Subscriber type. BUSINESS | RESEDENTIAL (optional) (RESEDENTIAL if not specified).
BusinessName	Subscriber business name for BUSINESS SubscriberType. Up to 25 characters long. (required BusinessName or LastName).
LastName	Subscriber last name for RESEDENTIAL SubscriberType. Up to 25 characters long. (required BusinessName or LastName).
FirstName	Subscriber first name for RESEDENTIAL SubscriberType. Up to 25 characters long. (optional).
MiddleInitial	Subscriber middle initial for RESEDENTIAL SubscriberType. 1 character (optional).
AccountNumber	AccountNumber. Alphanumeric, up to 32 characters. (optional).
PinNumber	PinNumber. Alphanumeric, up to 10 characters. (optional).
AuthorizingPerson	AuthorizingPerson. Alphanumeric, up to 100 characters (required).
HousePrefix	HousePrefix. Alphanumeric, up to 6 characters.
HouseNumber	HouseNumber. Alphanumeric, up to 45 characters (required).
HouseSuffix	HouseSuffix. Alphanumeric, up to 45 characters.
PreDirectional	PreDirectional. Alphanumeric, up to 2 characters.
StreetName	StreetName. Alphanumeric, up to 200 characters (required).
StreetSuffix	StreetSuffix. Alphanumeric, up to 45 characters.
PostDirectional	PostDirectional. Alphanumeric, up to 2 characters.
AddressLine2	AddressLine2. Alphanumeric, up to 200 characters.
County	County. Alphanumeric, up to 45 characters.
City	City. Alphanumeric, up to 100 characters (required).
StateCode	StateCode. Alphanumeric, 2 characters (required).
Zip	Zip code. Allowed formats: 5 numbers, 5+4 or Canadian (required).
ListOfTelephoneNumbers	List of tns to be processed (required).

/accounts/{accountId}/lsrorders/{orderid}

This resource allows retrieval and updating information associated with the lsr by its ID.
Modifiable lsr order fields:

• CustomerOrderId
• SPID
• BillingTelephoneNumber
• AuthorizingPerson
• RequestedFocDate
• SubscriberType
• BusinessName
• LastName
• FirstName
• MiddleInitial
• AccountNumber
• PinNumber
• HousePrefix
• HouseNumber
• HouseSuffix
• PreDirectional
• PostDirectional
• StreetName
• StreetSuffix
• AddressLine2
• County
• City
• StateCode
• OrderStatus*

*OrderStatus field can be modified to CANCELLED value only. This will cancel lsr. All another updates will be ignored in this case.

• get (secured): Retrieves the information associated with the specified lsr ID number.
• put (secured): Updates the information associated with the specified LSR. This is also used to cancel an order, by changing the order status field to canceled. This is the only case where the status can be changed, and when this is done, all other fields are left as they were prior to the cancellation. Please see the example below.

/accounts/{accountId}/lsrorders/{orderid}/history

This resource retrieves the history of a lsr order.

• get (secured): Retrieves the history of the specified lsr order.

/accounts/{accountId}/lsrorders/{orderid}/notes

The /notes resource manages a note or set of notes associated with an order. Notes can only be appended to the collection, and are not individually addressable or modifiable once added.

• post (secured): Updates the Notes resource by adding a note.
• get (secured): Retrieve the set of notes associated with an order.

/accounts/{accountId}/lidbs

The LIDBs Resource represents the requests made to the Bandwidth Dashboard API to add or otherwise manage a request to add Calling Line Information with a telephone number. This API allows the creation and observation of a "Line Information Data Base (LIDB)" work order that causes an update of a person's calling name identification in a network Database. The entry of this information in the network database in turn causes the display of their name on the phone of the people that they call.
This API call supports GET to retrieve information about outstanding LIDBs orders, and POST to create those orders.

• get (secured): Retrieve a list of the LIDB orders that are associated with the account.

• post (secured): Create a LIDB order to associate Calling Name Information with a TN or list of CountOfTNs The key data elements in the submission are -

  TelephoneNumbers	A list of telephone numbers that will all assume the SubscriberInformation that is listed in the payload. In an enterprise context it is not uncommon for all of the served telephone numbers to use the same string for the Subscriber Information.
  SubscriberInformation	This is the field that is displayed to the user receiving the phone call from the Telephone numbers in the TelephoneNumberList
  UseType	Can be RESIDENTIAL or BUSINESS. The element is required.
  Visibility	Can be PRIVATE or PUBLIC. If it is tagged as PRIVATE then the data will be provided, but the display will not be provided on a standard phone call. The element is required
  CustomerOrderId	The Customer Order ID is an ID assigned by the account owner to provide a reference number for the Order. The element is optional.

/accounts/{accountId}/lidbs/{lidbid}

This API returns data about the specific LIDBs Order specified as the resource

• get (secured): Retrieve information about a specific Lidb Order identified as the resource.

/accounts/{accountId}/dldas

The DLDAs Resource represents the requests made to the Bandwidth Dashboard API to add or otherwise manage a request to associate the street address with the telephone number. This API allows the creation and observation of a "Directory Listing and Directory Assistance" work order that causes an update of a address information in a network Database.
This API call supports GET to retrieve information about outstanding DLDAs orders.

• get (secured): Retrieve a list of the DLDA orders that are associated with the account.

• post (secured): Create DLDA order to associate the street address with the telephone number. The key data elements in the submission are -

TelephoneNumbers	A list of telephone numbers you need to bind information from payload.
SubscriberType	Can be RESIDENTIAL or BUSINESS. The element is required.
ListingType	Can be LISTED, NON_LISTED or NON_PUBLISHED. The element is required
ListingName	This field is required. Inner fields: FirstName (this field is required in case RESIDENTIAL SubscriberType is chosen), FirstName2, LastName (this field is required), Designation, TitleOfLineage, TitleOfAddress, TitleOfAddress2, TitleOfLineageName2, TitleOfAddressName2, TitleOfAddress2Name2, and PlaceListingAs are optional Please see the note below on sorting of Business Listings.
ListAddress	Can be true or false. The element is required.
Address	This field is required. Inner fields: HousePrefix, HouseNumber, HouseSuffix, PreDirectional, StreetName, StreetSuffix, PostDirectional, AddressLine2, City, StateCode, Zip, PlusFour and AddressType=DLDA. City, HouseNumber, StreetName, City, State and Zipcode are required fields.

Business Listings...
Business Listings sort differently than Residential Listings, and must be submitted accordingly. Since Business Listings sort starting at the beginning of the name, where Residential Listings sort on Last Name, the parts of the business name that will govern the sorting need to be entered in the LastName field. For example, Joe's Pizza sorts starting with Joe, so the entire business name would be entered in the LastName field, and the Firstname could be left blank. If there was a portion of the name that was not important from a sorting perspective (perhaps "the best pizza in town"), that portion could be placed in the FirstName field.

/accounts/{accountId}/dldas/{orderid}

This API returns data about the specific DLDAs Order specified as the resource

• get (secured): Retrieve information about a DLDA Order with specified ID.

• put (secured): Update DLDA order to associate the street address with the telephone number. The key data elements in the submission are -

  TelephoneNumbers	A list of telephone numbers you need to bind information from payload.
  AccountType	Can be RESIDENTIAL or BUSINESS. The element is required.
  ListingType	Can be LISTED, NON_LISTED or NON_PUBLISHED. The element is required
  ListingName	Inner fields: FirstName, FirstName2, LastName, Designation, TitleOfLineage, TitleOfAddress, TitleOfAddress2, TitleOfLineageName2, TitleOfAddressName2, TitleOfAddress2Name2, PlaceListingAs.
  ListAddress	Can be true or false. The element is required.
  Address	This field is required. Inner fields: HousePrefix, HouseNumber, HouseSuffix, PreDirectional, StreetName, StreetSuffix, PostDirectional, AddressLine2, City, StateCode, Zip, PlusFour, AddressType

/accounts/{accountId}/dldas/{orderid}/history

The history API returns the various events that have impacted the specified DLDA order.

• get (secured): Retrieve the history information associated with a named DLDA order. This indicates the various states that the order has passed through, as well as the current state of the order as the last entry.

/accounts/{accountId}/e911s

The E911s Resource represents the requests made to the Bandwidth Dashboard API to add or otherwise manage a request to associate the street address with the telephone number.This API allows the creation and observation of a "E911" work order that causes an update of a address information in a network Database.

The E911 order processing model is consistent with the overall model of creating an order or request with the initial POST, and then checking on the status of that order using callbacks and / or GET while that order progresses through the various steps in the process.

In the case of an E911s order, the states that the order may reside in are...
RECEIVED, PROCESSING, COMPLETE, PARTIAL, FAILED, ADJUSTED_COMPLETE, and ADJUSTED_PARTIAL
where the "ADJUSTED" indicates that the provisioning was successful, but that the street address was subtly changed to reflect a geocodable address. As in other order-types, PARTIAL indicates that there were some errors detected, but that all elements of the order that could be processed were processed. In this case the order record will need to be examined to determine the items that failed.

• get (secured): Retrieve a list of the E911 orders that are associated with the account.

• post (secured): Create E911 order to associate the address with the telephone number. The key data elements in the submission are -

TelephoneNumbers	A list of telephone numbers you need link to the street address.
CallerName	CallerName that will be linked to TNs. This field is required in the case of a new address assignment.
Address	This field is required in the case of a new address assignment. Inner fields: HousePrefix, HouseNumber, HouseSuffix, PreDirectional, StreetName, StreetSuffix, PostDirectional, AddressLine2, City, StateCode, Zip, PlusFour. Streetname, City, and State are required. House Number is currently required, although this enforcement may be relaxed in the future.
DeleteTNSpecificE911Address	Can be true or false. If value is true then Address and CallerName should not be specified.

/accounts/{accountId}/e911s/{orderid}

This API returns data about the specific E911s Order specified as the resource

• get (secured): Retrieve information about a E911 Order with specified ID.

/accounts/{accountId}/e911s/{orderid}/history

The history API returns the various events that have impacted the specified E911 order.

• get (secured): Retrieve the history information associated with an order

/accounts/{accountId}/tnoptions

The tnoptions Resource represents the requests made to the Bandwidth Dashboard API to add or otherwise manage a request to assign line features to the telephone number.This API allows the creation and observation of a "TN Option" work order that causes an update of a address information in a network Database.

• get (secured): Retrieve a list of the TN Option orders that are associated with the account.

• post (secured): Create TN Option order to assign line features to the telephone number. The key data elements in the submission are -

TnOptionGroups	A list of TnOptionGroups.
TnOptionGroup	Contains list of telephone numbers and set of TN options you want to assign to all TNs in the list.

There are TN Option values:

• TelephoneNumber - [ 10digit ]
• CallingNameDisplay - [ on | off | unchanged | systemdefault ]
• NumberFormat - [ 10digit | 11digit | e164 | unchanged | systemdefault ]
• RPIDFormat - [ 10digit | 11digit | e164 | unchanged | systemdefault ]
• RewriteUser - [ string | unchanged | systemdefault]
• CallForward - [ 10digit | unchanged | systemdefault]
• Protected - [ true | false | unchanged | systemdefault]
• Sms - [ on | off | unchanged]
• FinalDestinationURI - [ string | unchanged | systemdefault]
• a 10 digit telephone number, or
• a SIP URI ( without the sip: prefix )
  • in the form address-string@host IP:port, where
  • the host IP is an IPv4 address in the standard numerical n.n.n.n. form, and
  • the port is numeric, and optional
  • containing [a-z,A-Z,0-9], with ':', '.' and '@' to delimit the components of the overall string, and
  • less than 60 characters long.

Where:

• systemdefault - implies that the element profile value should be removed so that the TN changes back to the default system behavior;
• unchanged - the value should remain unchanged - implies a read before write model.
• Leaving the element out of the payload is equivalent to unchanged.

/accounts/{accountId}/tnoptions/{orderid}

This API returns data about the specific TN Option Order specified as the resource

• get (secured): Retrieve information about a TN Option Order with specified ID.

/accounts/{accountId}/tnoptions/{orderid}/history

The history API returns the various events that have impacted the specified TN Option order.

• get (secured): Retrieve the history information associated with an order

/accounts/{accountId}/lineOptionOrders

The LineOptionsOrder endpoint will be deprecated Dec. 31 2016. It has been replaced with the tnOptions order which provides the same functionality, with an improved level of tracking and management.

• post (secured): This link is used for configuring multiple telephone numbers with specific attributes:
  CNAM, NumberFormat, RPIDFormat, RewriteUser, CallForward, Protected and Sms.
  There are some possible attribute values:

• TelephoneNumber - [ 10digit ]
• CallingNameDisplay - [ on | off | unchanged | systemdefault ]
• NumberFormat - [ 10digit | 11digit | e164 | unchanged | systemdefault ]
• RPIDFormat - [ 10digit | 11digit | e164 | unchanged | systemdefault ]
• RewriteUser - [ string | unchanged | systemdefault]
• CallForward - [ 10digit | unchanged | systemdefault]
• Protected - [ true | false | unchanged | systemdefault]
• Sms - [ on | off | unchanged]

Where:

• systemdefault - implies that the element profile value should be removed so that the TN changes back to the default system behavior;
• unchanged - the value should remain unchanged - implies a read before write model.
• Leaving the element out of the payload is equivalent to unchanged.

/accounts/{accountId}/subscriptions

The +subscriptions+ resource is used to create e-mail or callback subscriptions. The subscriptions will notify the user about events concerning specific orders or orders of a specific type.
E-mail subscriptions can be configured to sent emails immediately after an event occurred or on daily basis as a digest with all events of the previous day. Callback notifications will always be send immediately.

• get (secured): GET is used to retrieve all subscriptions for the account (including email and callback subscriptions). The returned information reflects the subscription as it has been defined, and for callback subscriptions will reflect the status of the latest attempt to place the callback. The element will indicate if an error is being encountered when the Bandwidth Dashboard attempts to place the callback.

• post (secured): A POST on the /subscriptions resource is used to request a new subscription for an account.
  The POST creates a new e-mail or callback subscription. A well-formed POST will create a subscription resource, and return a subscription ID as part of the location header. The ID is used to uniquely identify the subscription. The user should submit the desired e-mail address for notifications and the frequency with which he wants to get the updates: DAILY (for daily digests) or NONE (immediately after events). OrderId is optional. If OrderId is specified only notifications will be sent for events related to that order. If OrderId is omitted, notifications will be sent related to events of all orders of the specified type.
  For email subscriptions use a body like this:
  

<Subscription>
    <OrderType> [ portins | portouts | orders | disconnects | dldas | lsrorders | e911s | tnoptions | externalTns] </OrderType> <!-- required -->
    <OrderId> [ UUID ] </OrderId> <!-- optional, if provided notifications will only be sent for events regarding this specific order, if omitted notifications regarding events for all orders of the specified type will be sent -->
    <EmailSubscription>
        <Email> [ email address] </Email>
        <DigestRequested> [ NONE | DAILY ] </DigestRequested> <!-- required -->
    </EmailSubscription>
</Subscription>

For callback subscriptions use a body like this:

<Subscription>
    <OrderType> [portins | portouts | orders | disconnects | dldas | lsrorders | e911s | tnoptions | externalTns] </OrderType> <!-- same rules and values as above -->
    <OrderId> [UUID]</OrderId> <!-- same rules and value as above -->
    <CallbackSubscription>
        <URL> [valid publically addressable URL] </URL> <!-- the URL that notifications should get POSTed to, HTTPS is highly recommended -->
        <Expiry> [time in seconds] </Expiry> <!-- the number of seconds after which to expire this subscription -->
        <CallbackCredentials> <!-- optional, but recommended; these credentials will be used to when authenticating with the notification receiving server -->
            <BasicAuthentication> <!-- optional, the endpoint may be secured with BASIC auth -->
                <Username> [username] </Username> <!-- max 100 characters -->
                <Password> [password] </Password> <!-- the password will be stored encrypted and never returned via the API -->
            </BasicAuthentication>
            <!-- optional, a BASE64 encoded public key matching the notification receiving server -->
            <PublicKey>LS0tLS1CRUdJTiBDRVJUSUZJ [...] kQgQ0VSVElGSUNBVEUtLS0tLQ0K</PublicKey>
        </CallbackCredentials>
    </CallbackSubscription>
</Subscription>

The credentials used to impose security on the callbacks are defined in the element. The Basic authentication is straightforward, but the requires a little more explanation. Please see the document to the left on Mutual Authentication for CallBacks.

When an event happens that had been subscribed to with a callback subscription (order update, note added to order), the following payload will be POSTed to the URL of the callback subscription.
More detail can be found in the API documentation for the fictitious endpoint /callbacks

<Notification>
    <SubscriptionId>...</SubscriptionId>
    <OrderType>portins | portouts | orders | disconnects | dldas | lsrorders | e911s| tnoptions | externalTns</OrderType>
    <OrderId>...</OrderId>
    <!-- for order update events -->
    <Status>COMPLETE | FAILED | PARTIAL | EXCEPTION ... </Status>
    <!-- for order update events -->
    <Message>...</Message>
    <!-- for note events -->
    <Note>...</Note>
    <!-- for portins/portouts/orders/disconnects OrderTypes -->
    <CompletedTelephoneNumbers>
        <TelephoneNumber> ... </TelephoneNumber>
        <!-- ... -->
    </CompletedTelephoneNumbers>
</Notification>

/accounts/{accountId}/subscriptions/{subscriptionid}

Allows to retrieve information about the specific subscription or delete the subscription.

• get (secured): Retrieves the information associated with the subscription ID. The returned information reflects the subscription as it has been defined, and for callback subscriptions will reflect the status of the latest attempt to place the callback. The element will indicate if an error is being encountered when the Bandwidth Dashboard attempts to place the callback.

• put (secured): Updates the subscription. This can be be used to update various values (expiry, email address, url, credentials...). 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.
  The same rules around valid or possible values as for POSTs apply.

• delete (secured): Deletes the specified subscription. Note that deleting subscriptions is only supported on a one-by-one basis. Deleting all subscriptions associated with an order requires GETting all of those subscriptions, then deleting them one by one.

/accounts/{accountId}/availableNpaNxx

Retrieves the quantity of available phone numbers in the given area code. The numbers are grouped by alike Npa-Nxx.

• get (secured): Retrieves a list of available Npa-Nxx telephone numbers.

/accounts/{accountId}/reports

Bandwidth provides a reporting infrastructure that will allow the creation of pre-defined reports, and the subsequent API-based exposure of those reports to our customers to assist them in management of their business.

The reports exposed via the reporting API are defined by the Bandwidth staff, and will grow and adapt over time to meet our customers changing needs. The basic structure of the resources in the reporting API reflects three levels of information:

1. Reports: pre-defined templates for information that include:
   • a name
   • a description of the report in general terms
   • a set of parameters that are used to provide boundaries on the information that is provided.  These parameters contain
   • • The parameter name,
     • a description of the parameter,
     • a declaration of whether it is required or not, and 
     • the type of the parameter.
     • a declaration of whether multi-selection is allowed or not.
2. Instances: the result of executing a report - a parameterized set of data that results from the creation of a report with a set of parameters.
   • They reflect the meta-data associated with actually creating a report from a set of data.  The instance is used in managing the actual  report that is made available for download.
   • Instances contain:
   • • An ID
     • The ID of the Report that was used to generate the Instance
     • An output format (currently PDF, XLS, or CSV)
     • Data about the user that requested the report.
     • A list of parameter values that was used to create the report
     • An expiration date of the report.
     • A status, indicating whether the report data is still being assembled, ready for download, or expired.
   • Instances are specific to a report.
3. Files: the actual data associated with a Report Instance.
   • Files are the items that are actually retrieved from the server and delivered to the user on demand.  The file is a logical resource that reflects the downloadable data that is described by the Instance

The report resource of the API allow the management of reports in the Bandwidth Dashboard.

• get (secured): GET Retrieves a list of the report templates available for use within the Iris application. This list contains the basic description of the reports, including a report ID that can be used to access further details about the report, and thus facilitating the subsequent choice and creation of an instance of the report.

/accounts/{accountId}/reports/{reportid}

• get (secured): A GET issued on a specific report (as identified by it's ID) will return all of the details of that report, allowing the API user to create an instance of that report. Those details include:
  • The report name
  • a description of the report in general terms
  • a set of parameters that are used to provide boundaries on the information that is provided.  These parameters contain
  • The parameter name,
  • a description of the parameter,
  • a declaration of whether it is required or not,
  • is multiple vales allowed or not,
  • the type of the parameter, which can be one of
  • Account ID (autofilled)
  • Site ID
  • SipPeer ID
  • String
  • Integer
  • Boolean
  • Enum, with a list of possible values.

/accounts/{accountId}/reports/{reportid}/instances

The report instance endpoints of the Iris API allow users to view and manage report instances for a specific report. Report instances capture invocations of a report, including the specific set of parameters provided and any output generated as a result.

• get (secured): Retrieve report instances associated with a specific report, including the up-to-date report generation status.

• post (secured): POSTing to the instances resource of a specific report will create an instance of that report that pulls from data that is filtered by the supplied parameters. Those parameter values must match the parameters that are required as defined by the report, as provided by issuing a GET on the report.
  
  The sequence of events is essentially to...

1. issue a GET on the desired report/report-id to retrieve the parameter and other details of the report
2. issue a POST on the /report/report-id/instances resource, using the parameter information retrieved in the initial call to define the data that is needed

The Location header will provide a link to the created report instance. Note that the report instance itself contains only the metadata describing the instance. A subsequent call to /report/report-id/instances/instance-id/file must be made to actually download the file.

/accounts/{accountId}/reports/{reportid}/instances/{instanceId}

Retrieve information on a specific instance of a specific report.

• get (secured): A GET on the specific instance will retrieve report instance details, including the current report instance status. All of the information required to understand the nature and limits of the reported data are contained in the payload, including the general description information as well as the list of parameters and the values assigned to those parameters.

/accounts/{accountId}/reports/{reportid}/instances/{instanceId}/file

The file resource reflects the actual downloadable information described by the Instance metadata. Invoking an API call on the file resource will result in a download of the file containing the information, as long as the file is finished preparation and ready for download.

• get (secured): Retrieve report instance output file, if output is available.

/accounts/{accountId}/reports/instances

The report instance endpoints of the Iris API allow users to view and manage report instances for a specific account. Report instances capture invocations of a report, including the specific set of parameters provided and any output generated as a result.

• get (secured): Retrieve report instances within the account scope, regardless of the report of which the instance is an instance of, including the up-to-date report generation status. This is a convenience API call to make it easier to examine all Instances in scope.

/accounts/{accountId}/tnreservation

Reserves a telephone number .

• post (secured): Reserves a telephone number or a set of telephone numbers for a default time of 4 hours. A successful reservation returns a location header that can be used to retrieve the reservation at a later time.

/accounts/{accountId}/tnreservation/{reservationid}

Retrieves a TN reservation's information and deletes an existing reservation.

• get (secured): Retrieves a TN reservation's information.
• delete (secured): Deletes a TN reservation.

/accounts/{accountId}/billingreports

This API allows the retrieval of a zip file containing billing report for a specified date range and type. This billing report is delivered as a zip compressed comma separated values (CSV) file.
The general flow of the API calls required to retrieve these records is

1. POST a request to the /billingreports resource, describing the report date range and type for which the billing report is wished. This will initiate the construction of the zip file.
2. Examine the response from the POST. If the payload is understandable and valid then a 201 response will be returned, indicating that the response file is currently being constructed.
3. Retrieve the Location Header from the response to the POST. This Location response-header field will contain the complete URI-reference to newly created resource. Each report has it's own resource ID.
4. Interrogate the resource ID to check the status of the report. If a 200 OK is returned then the resource ID is considered valid and corresponding status will describe the readiness of zip file.
5. Fetching the file can be done by issuing a GET request to the resource path in the Location Header mentioned above.

• post (secured): The payload for the POST declares the date range and type for the desired reports. The valid Types are...
  • BDR - Billing Detail Records - per call information
  • MDR - Message Detail Records - per messagin information
  • INVOICE - A copy of the invoice file or files for the specified date range
  • STATEMENT_BDR - BDR records that are aligned with the invoice
  • DID_SNAPSHOT - a list of telephone numbers aligned as closely as we can with the billing window

/accounts/{accountId}/billingreports/{reportid}

The resource will query the status of the report that is being generated.

• get (secured):

/accounts/{accountId}/billingreports/{reportid}/file

The file resource is an explicit reference to the zip file that has been created.

• get (secured): A GET on the /file resource subtending a report ID will cause the download of the file. Executing this resource path within a browser will cause the download of the file.

/accounts/{accountId}/bdrs

Note - this API is being replaced with the /billingreports API - we strongly recommend that you use that endpoint
This API allows the retrieval of a ZIP file containing BDR records for a specified date range. These BDR records are delivered as a ZIP compressed comma separated values (CSV) file.
The general flow of the API calls required to retrieve these records is

1. POST a request to the /bdrs resource, describing the date range for which the BDR records are wished. This will initiate the construction of the zip file.
2. Examine the response from the POST. If the payload is understandable and valid then a 202 accepted HTTP result code will be returned indicating that the response file is being created.
3. Retrieve the Location Header from the Response to the POST. This location header will contain the resource ID for the collection of BDRs that will be returned once complete. Note that the fact that the ID has been issued does not mean that the ZIP file is complete.
4. interrogate the resource ID to check the status of the request. If a 303 See Other response is received then the Location Header will contain the resource path to the file. A typical browser response will be to download the file. If a 200 OK is returned then the request is considered valid, but the file is not ready for distribution.
5. fetching the file can be done by issuing a GET to the resources path in the Location Header mentioned above.

• post (secured): Request a collection of BDRs be aggregated and ZIPped ready for distribution. The payload for the POST declares the date range for the request.

/accounts/{accountId}/bdrs/{bdrid}

The bdrid resource will query the status of the bdr file that is being generated. There are essentially two responses...

• not yet ready
• ready, in which case the request is redirected to the URL to actually download the file.

• get (secured): A GET on the BDR ID will return a "still processing" indication if the file creation has not completed, or will redirect to the file to be downloaded.

/accounts/{accountId}/bdrs/{bdrid}/file

The file resource is an explicit reference to the zip file that has been created with the selected BDR records.

• get (secured): A GET on the /file resource subtending a BDR ID will cause the download of the file. Executing this resource path within a browser will cause the download of the file.

/accounts/{accountId}/users

• get (secured): Retrieves a list of users as specified by the account ID.

/accounts/{accountId}/sites

Use this method to add or update a site to an existing account.
Each site creation or update must have the following input parameters:

Parameter	Description
accountid	The numerical Account ID that you will be adding the site to.
Name	The name of the site. Max length restricted to 10 characters.
Description	Customer provided description of the site.
Address	Service Address for the site.
CustomerProvidedID	Customer can provide an optional id (max 10 digits). Note that the customer can use the same id across multiple orders.
CustomerName	Customer can provide an optional name
UcTrunkingConfiguration	For UC Trunking accounts the UcTrunkingConfiguration element describes the kind of UC trunking that is provided. The Type parameter is one of Seats, Premise, or Cloud, and the UsageCategory parameter is one of UC250, UC500 or UC1000.

• get (secured): retrieve a list of all the sites associated with the account
• post (secured): Add a site to the account

/accounts/{accountId}/sites/{siteId}

This method updates or deletes a site based on the id, as well as adds a SIP Peer to the given site.

• get (secured): retrieves the information associated with the site id
• put (secured): updates the contents of a site id
• delete (secured): deletes the site - sites can only be deleted if there are no SIP Peers attached to it

/accounts/{accountId}/sites/{siteId}/sippeers

The SIP Peer API is used to display and configure SIP Peers The values for this payload are as follows:

Element	Description	Example
SiteId	The internally allocated SIP Peer ID	12345
PeerName	Mandatory name for the SIP Peer (Max 10 chars)	Downtown Branch
Description	Optional description for the SIP Peer
IsDefaultPeer	Value is True or False. The Default SIP Peer is the default "destination" for any Telephone Numbers that are ordered for the Site in which the SIP Peer resides.  Each site can have only 1 default SIP Peer. You can configure multiple SIP Peers on a Site
ShortMessagingProtocol	Used to specify the protocol used by the endpoints for exchanging SMS messages: allowed values are SIP and SMPP.  The element is optional, with a default of SMPP.  This element can be updated if SMS is enabled on the Account and SIP Peer.
HostName	The IP Address or Host Name of the address to be used for the SmsHosts, VoiceHosts or VoiceHostGroups addresses.
Port	Optional Port Number for Voice and Termination hosts. This is an optional parameter that has default values that are dependent on the Application.  It is not valid for SMS.
VoiceHosts	These addresses, comprised of HostName and optional Port, are used by the Bandwidth network to send calls to for Origination services. The VoiceHosts list of IP addresses used for an active/standby address selection mechanism, where the first address is attempted, followed by the second address and so on. Except under failure situations the first address in the list is preferred. Maximum of 10 hosts - can be IP address or Fully Qualified Domain Name
VoiceHostGroups	The VoiceHostGroups element is comprised of a list of up to five VoiceHostGroup elements, each of which is used to randomly distribute traffic amongst up to 10 IP addresses. One of the VoiceHostGroups elements in the group is chosen at random to receive traffic, and then the calls are placed at random amongst the addresses in the group. Once a group is chose, failover behavior is retained within the group.
VoiceHostGroup	A VoiceHostGroup is a list of IP Addresses (the Host element). This traffic distribution model distributes traffic in a Random manner amongst the addresses in the group.
SmsHosts	Used for SMS traffic only – can be IP address of Fully Qualified Domain Name
TerminationHosts	These addresses, comprised of IP or Subnet(CIDR format) and optional Port, are used by the Bandwidth network to send calls to for Termination services. Maximum of 10 hosts - can be IP address or subnets. In case of subnet you should specify NetworkAddress of subnet as IP.	135.23.78.145 or 12.45.67.48/29
CustomerTrafficAllowed	A TerminationHost can be configured to allow different customer traffic types.  Allowed values are LITE, DOMESTIC and ALL. This is an optional parameter.
DataAllowed	True or False (Enables or Disables SMS messaging for a TerminationHost). Optional parameter.
Address	Billing or Service Address for the SIP Peer.  This element is optional for accounts except for accounts with the UC Trunking Product.  If the address element is provided the following fields can be provided, some of which are Mandatory:     HouseNumber - MANDATORY     HouseSuffix - OPTIONAL     PreDirectional - OPTIONAL     StreetName - MANDATORY     StreetSuffix - OPTIONAL     PostDirectional- OPTIONAL     AddressLine2- OPTIONAL     City - MANDATORY     StateCode - MANDATORY     Zip - MANDATORY     PlusFour - OPTIONAL     County - OPTIONAL     Country - OPTIONAL (Defaults to 'US')     AddressType - MANDATORY (Billing or Service)
CallingName	Determines whether the Calling Name Displayl service is applied to the Telephone Numbers associates with the SIP Peer
Display	Controls the Display of Calling Name information. If <true> then the calling name information is displayed by default for all calls,
Enforced	Determines whether the Default Display behavior (Display) is enforced for all TNs associated with the SIP Peer. If <true> then no TN-level overrde is possible
FinalDestinationURI	Last attempt for routing of calls

• get (secured): Retrieve information about a Sip Peer or set of Sip Peers
• post (secured): Create a Sip Peer

/accounts/{accountId}/sites/{siteId}/sippeers/{sippeerId}

The SIPpeerID Resource deals with retrieving or updating a specific identified SIP Peer, identified by the SIP Peer ID. The elements of the payload are described in the /sippeers resource.

• get (secured): Retrieve a the data associated with a Sip Peer

• put (secured): Update a Sip Peer There are a few rules used to eliminate IP address collisions. The primary restriction is on the ability to share Term IP addresses across IRIS structural elements. Essentially...

• Term Addresses cannot be shared anywhere
• SMS addresses can be shared, and can be different than Term IP Addresses
• VoiceHost and VoiceHostGroup addresses can be shared between SIP Peers, and can be different than or the same as Term IP Addresses

• delete (secured): Delete a Sip Peer

/accounts/{accountId}/sites/{siteId}/sippeers/{sippeerId}/tns

• get (secured): Retrieve information about a Telephone number or set of Telephone numbers

/accounts/{accountId}/sites/{siteId}/sippeers/{sippeerId}/tns/{tn}

• get (secured): Link for receiving information about telephone number. CallForward - Does this telephone number have call forwarding or not. CallingNameDisplay - Calling Name of the caller is available to the user or not on incoming calls. TnAttributes - Is this telephone number protected or not. MessagingSettings - Does this telephone number have any messaging system configured.

• put (secured): This API can be used by the Bandwidth Dashboard or general API users to update the settings for TNs allocated to their account.

/accounts/{accountId}/sites/{siteId}/sippeers/{sippeerId}/totaltns

• get (secured): Retrieve count of Telephone numbers for Sip Peer

/accounts/{accountId}/sites/{siteId}/sippeers/{sippeerId}/movetns

This method moves desired Telephone Numbers to the given SIP peer.

• post (secured): The POST method moves all telephone numbers specified in the body to the given SIP peer.
  The source SIP peer is determined by the Telephone Number, i.e. the PUT method can move multiple numbers from different source SIP peers.
  The destination SIP peer is specified in the URL.
  NOTE: only a maximum of 5000 Telephone Numbers can be moved in one operation.

/accounts/{accountId}/sites/{siteId}/inserviceNumbers

Retrieves all the telephone numbers currently in service for the given site.

• get (secured): Retrieves all the telephone numbers currently in service for the given site.
  There are multiple parameters to search and sort the in-service numbers:

• LATA
• Tier
• Rate center
• Area code
• Npa-Nxx
• State
• City
• Start Date
• End date

/accounts/{accountId}/sites/{siteId}/orders

The "orders" resource interacts with the orders assigned to a particular site of a particular account.

• get (secured): The GET method retrieves all the orders associated with the given site.

/accounts/{accountId}/sites/{siteId}/orders/{orderid}

The "order id" resource interacts with specific orders from an account's site.

• get (secured):

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

Retrieves the Telephone Numbers associated by the given order ID

• get (secured): Retrieves the Telephone Numbers associated by the given order ID

/accounts/{accountId}/sites/{siteId}/portins

Retrieves the port-in requests for the given site ID.

• get (secured): Retrieves the port-in requests for the given site ID.

/accounts/{accountId}/sites/{siteId}/totaltns

• get (secured): Retrieve count of Telephone numbers for the indicated site

/accounts/{accountId}/products

• get (secured): discover what is currently enabled on the account

/accounts/{accountId}/sipcredentials

This resource is used to manage SIP credentials for subscriber provisioning. SIP Credentials allow for the Authentication of SIP Messages presented to the Bandwidth Network. These values are provisioned to the Network to allow the endpoints to participate in an Authentication Challenge (RFC 3261). These values are compared (after processing) with a value received in the Authorization header of the SIP INVITE to determine whether the call will be allowed to proceed. The user is authenticated for access to the network using a composite-username, which is either a username string or a combination of a username and a domain separated with an '@'. The other components of the authentication are MD5 hash values that are hashes of the composite username, the password, and either one or two instances of the Realm, to allow the network to recognize the two prevelent mechanisms for generating MD5 hashes. There are 4 components to the SIP Credentials payload...

1. The UserName (required) - a string identifying the user.
2. The Domain (optional) - a string refining the identity of the user. The Domain will be joined to the UserName with an '@' to create a composite username. For example, the UserName 'bob' could be combined with the domain 'somewhere.com' to create a composite username '[email protected]'
3. Hash1 (required) - a string representing a potential Hash values used to authenticate the client. It is anticipated that the value will be computed from an MD5 Hash of 'composite-username:Realm:Password'. The makeup of this hash is however transparent to the network. It must align with a hash that the client is capable of creating
4. Hash1 (optional)- a string representing a potential Hash value used to authenticate the client. It is anticipated that the value will be computed from an MD5 Hash of 'composite-username:Realm:Realm:Password'. The makeup of this hash is however transparent to the network. It must align with a hash that the client is capable of creating.

If the Domain is not specified the Hash1b is not required.

• get (secured): GET is used to retrieve all SIP credentials for the account.

• post (secured): POST is used to create SIP credentials and associate its with the account. The key data elements in the submission are -

UserName	This is subscriber name or aggregated name and domain value(ex: [email protected]). Field is required. Max length - 32 characters.
Domain	This is subscriber domain. Domain is optional and if present will be appended to the UserName with an '@'. Max length - 32 characters.
Hash1	This is hash value #1 in MD5 representation. Field is required. Max length - 64 characters.
Hash1b	This is hash value #2 in MD5 representation. Field is optional. Max length - 64 characters.

/accounts/{accountId}/sipcredentials/{userName}

This resource is used to manage single SIP credential for subscribers provisioning.

• get (secured): GET is used to retrieve SIP credential for the account by unique combination of user name and domain.

• put (secured): PUT is used to change single SIP credential.
  It is not possible to change the UserName or the Domain associated with the Hash Values. To do so requires deletion of one set of credentials and addition of a new set of credentials.
  The key data elements in the submission are -

Hash1	This is hash value #1 in MD5 representation. Field is required. Max length - 64 characters.
Hash1b	This is hash value #2 in MD5 representation. Field is optional. Max length - 64 characters.

• delete (secured): DELETE is used to delete SIP credential.

/accounts/{accountId}/externalTns

The externalTns order resource represents the requests made to the Bandwidth Dashboard API to add or remove customer owned or managed telephone numbers into or from the Bandwidth Dashboard. This API request will create an order record specific to the request that can be used to understand and track the outcome of the request once complete

The information below captures the REST endpoint URL and Payloads that are used to install or remove customer provided external telephone numbers from the Bandwidth Dashboard.

This API has been developed based on similar existing functionality available in the Bandwidth Dashboard, but has been refined to focus purely on the task of managing numbers that have been provided to Bandwidth by our customers, allowing the Dashboard business logic to be specific and focused with respect to managing these telephone numbers.

The API follows the Bandwidth Dashboard order model, where an order-id is created to track the interaction and refer back to it as needed. This record will also be persisted to enable examination of past events.


This single API controls both the installation and removal of telephone numbers. The action is controlled by the use of an element in the payload, allowing a simple model for managing both addition and removal of telephone numbers. Additionally, if the status of an existing telephone number needs to be reset within the Bandwidth Dashboard, possibly as the result of an ownership change (port) of the telephone number, the API can be called to re-add the number to the Bandwidth Dashboard, which will perform a reset on that number without removing it from service first.

The externalTns order tracks the orders related to customer-provided numbers into the customer's account.

This Import/Delete request reflects a customer-executed import or removal of numbers that they own and/or control. The telephone numbers in question cannot be Bandwidth CLEC numbers, and are not subject to the normal telephone number life-cycle.

• get (secured): Retrieve a list of the externalTns orders that are associated with the account.

• post (secured): Create a externalTns order to add or remove telephone numbers provided by the customer from the Bandwidth network. Note: the attempt to import a telephone number that is already present in the account will not create an error, but will reset all of the attributes of that telephone number in the Dashboard system as if the telephone number was being imported for the first time The key data elements in the submission are -

CustomerOrderID	An order ID created by the customer for their tracking purposes
SiteId	(Required) The ID of the Site that the Telephone Numbers are to be provisioned to.
SipPeerId	(Optional) The ID of the SIP Peer that the Telephone Numbers are to be provisioned to.
Action	(Required) Indentify the action on external TNs. Allowed values... IMPORT or REMOVE.

/accounts/{accountId}/externalTns/{orderid}

This API returns data about the specific externalTns order specified as the resource

• get (secured): Retrieve information about a externalTns order with specified ID.

/tns

Telephone Numbers (TNs) are similarly central to Bandwidth Dashboard provisioning. TNs can be queried on a system-wide basis, returning information based on a wide range of search parameters.
The results will be restricted to the account(s) that the requesting user has access to.

/tns

• get (secured): Retrieve information about one or more Telephone Numbers (TNs), where the TNs are chosen based on the search parameters provided in the API Call.

/tns/{tn}

Retrieves information about the specified telephone number. The information returned provides status and historic information about the Telephone Number, including the status, the order id and date assocated with the last modification, and the account and site information associated with the TN.
The request for more information can be made by requesting a number of specific derived sub-resources.

• get (secured): Retrieves the telephone number's information.

/tns/{tn}/tndetails

The get method retrieves detailed information about the phone number.

• get (secured): Retrieves detailed information about the phone number. TnAttributes - Does this telephone number is protected or not.

/tns/{tn}/sites

The get method retrieves the sites associated with that telephone number.

• get (secured): Retrieves the sites associated with that telephone number.

/tns/{tn}/sippeers

The get method retrieves the sippeers associated with that telephone number.

• get (secured): Retrieves the sippeers associated with that telephone number.

/tns/{tn}/ratecenter

The get method retrieves the rate centers associated with that telephone number.

• get (secured): Retrieves the rate centers associated with that telephone number.

/tns/{tn}/lca

Retrieves the LCA information associated with that telephone number.
This call will return the NPA-NXX pairs and the Rate Centers that are in the Local Calling Area of the Telephone Number in the API call.
Due to the fact that not all LCA relationships are symmetrical, the telephone number may not be part of the LCAs centered on the provided NPA-NXX or Rate Center values.

• get (secured): Retrieves the LCAs associated with that telephone number.

/tns/{tn}/lata

Retrieves the lata that contains the telephone number.

• get (secured): Retrieves the lata associated with that telephone number.

/tns/{tn}/history

The history call returns a number of payload elements, each representing an event in the lifecycle of the Telephone Number.
Information returned includes the Order details that prompted the change in the TN status, including dates, order IDs and order types.

• get (secured): Retrieves the history associated with that telephone number.

/tns/{tn}/tnreservation

This API call retrieves any current reservation information associated with the Telephone Number, if a reservation is currently active on the indicated Telephone Number. The query is restricted to calls that do not exceed the account privileges of the calling user.

• get (secured): Retrieves reservation information associated with the Telephone Number.

/users

The /users API also enables resetting but not retrieving credential information

/users/{userid}

reference a specific user in the Bandwidth Dashboard

• get (secured): Retrieve the information (except the password) for a specific user id

/users/{userid}/password

Allows the manipulation of a user's password.

• put (secured): Update a user's password. Security is maintained by requiring the user's existing password as part of the authentication for the API call.

/cities

The +cities+ resource returns all of the Cities in the indicated State that are supported from a coverage perspective, and, if requested, that contain orderable inventory. The values returned indicate the names of the Cities and, if available is specified, returns the available inventory by City. Note that the mapping between Rate Center and City is not completely predictable because multiple cities can be served by a single Rate Center and it may take multiple Rate Centers to serve a city. The Rate Centers results are more predictable because they are defined strictly in telecommunication terms.

/cities

• get (secured): 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 is omitted or false, then the coverage or availability is reported for the combination of the Bandwidth CLEC and our partners
  • If available=true is specified, then only Rate Centers in which we have available numbers are reported.
  • If available is omitted or false, 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

/rateCenters

The rateCenters resource returns all of the Rate Centers in the indicated State that are supported from a coverage perspective, and, if requested, that contain orderable inventory. The values returned indicate the names of the Rate Centers and, if the query parameter available is specified, the available inventory by Rate Center.

/rateCenters

• get (secured): The Rate Centers API Call returns 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 or false, then the coverage or availability is reported for the combination of the Bandwidth CLEC and our partners
  • If available=true is specified, then only Rate Centers in which we have available numbers are reported.
  • If available is omitted or false 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

/coveredRateCenters

The coveredRateCenters resource returns all of the Covered Rate Centers. Each rate center resource contains state, abbreviation, name, LATA, list of tiers, number of available TNs and optional zip codes, cities, vendors, NPA-NXX-Xs information.

/coveredRateCenters

• get (secured): The Covered Rate Centers API Call 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. The various query parameters are summarized in the following table ...

  Query Parameter	Description
  page	The starting value for a paginated response. The default is ‘1’ indicating the first page of results.
  size	The number of rate centers to include in a paginated result payload.
  state	A 2 character State code
  abbreviation	A rate center abbreviation
  name	A rate center name
  zip	A 5 digit zip code
  city	A City name
  lata	A 3 or 5 digit LATA
  tier	A bandwidth coverage tier; a value from 0 to 5.
  npa	A 3 digit NPA or Area Code
  npaNxx	6 digits NPA and NXX values
  npaNxxX	7 digits of NPA, NXX and thousands block values.
  embed	One of the values [ZipCodes, Cities, NpaNxxX, AvailableNumberCount, LocalRateCenters]. This repeatable query parameter will force a list (or multiple lists) of the indicated data to be provided in the response. For example if the payload should contain a list of the Cities covered by the Rate Centers then embed=cities would be included as a query parameter. No filter parameters are supported if LocalRateCenters is specified. In this case only size, page and any other embed parameters are supported.

/coveredRateCenters/{rateCenterId}

The "rateCenterId" resource refers to a specific element of the covered rate centers collection. A lists of zip codes, cities, NPA-NXX-Xs, local rate center IDs and vendors (for admin users only) are included into response.

• get (secured): Retrieve information about a specific covered rate center identified as the resource.

/callbacks

The callbacks group of API calls does not reflect API Call signatures of the Bandwidth Dashboard API.
The API documentation captured in this group is intended to capture payload and response expectation of callback endpoints provided by our customers.

The API endpoints (like https://customer.com/the\_resource\_that\_bandwidth\_calls\_to\_notify\_my\_app\_of\_something) will be provided by our customers (you), and we will invoke those endpoints with the described payloads, and respond appropriately to the described responses.
The URLs are provided by you; we call them with the payloads, and process the responses.

Don't plan on placing a call to "/callbacks /portOutValidationCallbackApi" or "/callbacks /notificationCallbackApi", these are simply here to provide some structure to the documentation.   We will place a call to the URL that you provide us, and we will expect a response to that API call as described below.

The Callback APIs documented in this group of API signatures includes...

Name	Description
Port-Out Validation	This Callback API will be used with select pre-qualified customers to confirm the validity of a port-out request when it is submitted by the winning carrier. The API call will define the end user owner of the Telephone Number in terms of FCC-approved information to aid in assessing the validity of the request
Order state change notification Callback API	This Callback API will be used to notify customers of events and changes that occur with various feature and service orders that are being processed by the Bandwidth Dashboard on their behalf. In general this notification callback will be called whenever an order that is in-scope changes state or has a note added to it.

If the customer's endpoint is unavailable, the Bandwidth Dashboard callback service will retry the customer's endpoint 8 times over a period of 40 minutes.

The API payloads are described below...

/callbacks/portOutValidationCallbackApi

The port out validation API is used for portout management purposes and gives the losing side customer the possibility to validate the portout process.

Summary

Validation of a Port-out request will begin with a submission from Bandwidth to our customer including information used to validate the correctness of the port-out request. The included information may include:

• a list of telephone numbers to be ported out
• a subscriber name for information purposes
• a zip code associated with the subscriber, presumably relating to a billing or service address
• an account code, presumably related to an account used to reflect  the commercial or billing relationship with the subscriber
• a PIN established by the end user that helps to identify that end user / subscriber

One of two responses are valid:

1. a positive validation of the port-out request. In this case no additional information is required
2. a negative response indicating that the port-out request is considered to be invalid, based on the information received.
   • the response must contain error response codes that will support updating of the request with valid data.
     
   • this information will be passed back to the requesting party to allow them to attempt to improve the request.
   • In this case the response should contain data that would have allowed to port-out to be considered valid,
     • this data is intended for dispute resolution, and for review by Bandwidth to see if the port appears to be valid based on the available data.
     • all fields are considered optional.
     • failure to return any data may  be considered to be equivalent to approving the port-out request.
     • subsequent submission of the data provided in the response should cause acceptance of the port-out request.
     • this information will not be passed directly on to the requesting party

The above exchange of information is intended to support best faith resolution of port-requests within the constraints imposed by the FCC. The objective is consistent achievement of the middle ground between slamming and unjustified blocking of valid requests.  Information returned to Bandwidth is to aid in dispute resolution, and is considered to be covered by CPNI limitations and thereby not intended for distribution to any third parties. Note that failure of the winning carrier to match the values exchanged by the API may not prevent porting-out of the number. FCC guidelines must still be followed in dispute resolution.

This exchange of information is synchronous in nature, and will not permit extensive delays in response, and will not create a series of linked transactions for resolving a dispute, or in attempting the port-out with different information. Updated submissions will be treated as new requests. Responses to the API call are expected within 30 seconds.

The error codes and error explanation payloads below are the ones that we expect to see in response to the port-out validation callback. This uniform set of responses allows a consistent and clear dialog with the prospective winning carrier about the nature of the validation failure.

Code	Meaning
7510	Required Account Code missing
7511	Invalid Account Code
7512	Required PIN missing
7513	PIN Invalid
7514	Required ZIP Code missing
7515	Invalid ZIP Code
7516	Telephone Number not recognized or invalid for this account
7517	Too many Telephone numbers in this request
7518	Telephone Number Not Active
7519	Customer info does not match
7598	Invalid Request -
7599	Fatal Error in Processing

Configuration

The configuration of the call-back API used for port-out validation is done by Bandwidth development staff.  Configuration of this service is performed on the submission of a Ticket, and on completion of the required contract extensions.

• the configured URL provided by the customer that will be invoked by Bandwidth in order to validate a port-out request.
• the suecurity of the exchange can be protected within an https exchange, and can be authenticated with userid / password credentials, or with certificates. The setup of the callback will be covered in the ticketing process.

Responsibilities

Accounts using the Poprt-out verification API will likely be required to extend the contractual relationship with Bandwidth to ensure clarity around the responsibilities of our customers in the use of the API, and the rights of Bandwidth to withhold this capability if we believe that the capability is being used in contravention of FCC best practices, guidelines and recommendations. Please review these requirements with your Bandwidth representative.

• post (secured): The initial request for validation is a post to the pre-configured URL defined by the customer. This request contains optional elements for:

• PIN (optional) ( 10 digits )
• Account Number (optional) ( 25 digits )
• zipcode (optional) ( 15 characters )
• a list of one or more telephone numbers (at least one telephone number must be provided) ( 10 digits )
• Subscriber name for information purposes. (optional)( 93 characters )
• PON for information and correlation purposes. (optional)( 25 characters )

/callbacks/notificationCallbackApi

The notification callback API is used notify customers of events and changes that occur with various feature and service orders that are being processed by the Bandwidth Dashboard on their behalf. In general this notification callback will be called whenever an order that is in-scope changes state or has a note added to it.

When an order changes the Bandwidth Dashboard will POST a pre-defined payload to our customer at the URL that they have defined by use of the /accounts//subscriptions API call. Please see the documentation on that API call to understand how to register the notification callback API with the Bandwidth Dashboard.

• post (secured): The POST to the callback API contains a summary of the order that is independent of the type of the order that caused the event that in turn caused the notification callback. This requires that the customer's end system place an API call to the Bandwidth Dashboard to gather additional details on the change to the order if that is important.
  
  This approach was taken for two reasons:

• some (or many) of the notifications might not require action.
• since orders contain different information, providing order-specific information would cause an undesirable tight linkage between notifications and every type of order, mandating API changes whenever the data associated with an order changed.

The payload of the POST contains:

• the Subscription ID that the notification is in response to.
• the type of order that the notification applies to.
• the order ID of the order that has changed
• the new state of the order
• a message if one was attached as part of the state change. This will often be present in error cases.
• the body of any note that was attached to the order, if applicable
• list of the completed telephone numbers for Port-in/Port-out/New Number/Disconnect orders in terminal state

The Payload follows