Skip to main content

Manage LSR orders

The LsrOrders endpoint 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 information, POST for creating a new LSR Order, and PUT for changing the details of an LSR in flight. PUT is also used to cancel an order, by changing the order status field to cancelled. 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.

The payload fields are described below:

FieldDescription
PonThe Pon is customer specified order indentifier field. Allowed alphanumeric and "#","-","_". Up to 25 characters long. (required)
CustomerOrderIdThe CustomerOrderId is customer specified order indentifier field. Allowed alphanumeric, spaces and dashes. Up to 40 characters long. (optional)
SPIDIdentifier 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
BillingTelephoneNumberNon-tollfree 10 digit phone number (optional)
RequestedFocDateoptional (next day if not specified)
SubscriberTypeSubscriber type. BUSINESS
BusinessNameSubscriber business name for BUSINESS SubscriberType. Up to 25 characters long. (required BusinessName or LastName)
LastNameSubscriber last name for RESEDENTIAL SubscriberType. Up to 25 characters long. (required BusinessName or LastName)
FirstNameSubscriber first name for RESEDENTIAL SubscriberType. Up to 25 characters long. (optional)
MiddleInitialSubscriber middle initial for RESEDENTIAL SubscriberType. 1 character (optional)
AccountNumberAccountNumber. Alphanumeric, up to 32 characters. (optional)
PinNumberPinNumber. Alphanumeric, up to 10 characters. (optional)
AuthorizingPersonAuthorizingPerson. Alphanumeric, up to 100 characters (required)
HousePrefixHousePrefix. Alphanumeric, up to 6 characters
HouseNumberHouseNumber. Alphanumeric, up to 45 characters (required)
HouseSuffixHouseSuffix. Alphanumeric, up to 45 characters
PreDirectionalPreDirectional. Alphanumeric, up to 2 characters
StreetNameStreetName. Alphanumeric, up to 200 characters (required)
StreetSuffixStreetSuffix. Alphanumeric, up to 45 characters
PostDirectionalPostDirectional. Alphanumeric, up to 2 characters
AddressLine2AddressLine2. Alphanumeric, up to 200 characters
CountyCounty. Alphanumeric, up to 45 characters
CityCity. Alphanumeric, up to 100 characters (required)
StateCodeStateCode. Alphanumeric, 2 characters (required)
ZipZip code. Allowed formats: 5 numbers, 5+4 or Canadian (required)
ListOfTelephoneNumbersList of tns to be processed (required)

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