Skip to main content

Porting Numbers

The Bandwidth Phone Number API is used to submit Port-In requests. These requests to move phone numbers from a “losing carrier” to Bandwidth are part of the Local Number Portability (LNP) process. These LNP requests are automatically validated and processed.

Bandwidth supports two APIs for porting numbers to Bandwidth:

  • /portins
  • /bulkPortins

The /portins API allows a set of TNs to be ported in, provided that the set of TNs meets the criteria below. TNs can be ported in a single /portins request if all of the following are true:

  1. They all have the same Port Type
  2. They all have the same losing carrier
  3. They are all associated with the same billing TN and Service Address

There are also a number of reasons why a TN may not be able to be ported in:

  • The TN is in a rate center that is not supported by Bandwidth or any of Bandwidth's partners.
  • The TN is an off-net TN and the account is configured to support tier zero (on-net) only.
  • The TN belongs to a losing carrier that Bandwidth does not have a Trading Partner Agreement with.
  • The TN is already being processed in another active port-in order.
  • The Bandwidth account has not been enabled for porting. Otherwise the user must separate the TNs into individual /portins requests.

The /lnpchecker API is used to determine the Port Type(s) and losing carrier(s) for a set of TNs. The /bulkPortins API eliminates the need for the /lnpchecker API by sorting the list of TNs automatically into a set of port-in requests by Port Type. The set of port-ins associated with the bulk port-in remain in a DRAFT state until you've had a chance to examine the breakdown. From that point, you can decide to submit all of the port-ins together under the umbrella of the bulk port-in, or you can separate out individual port-ins to submit by themselves. Terminology

TermDescription
Port TypeA categorization of how the TNs submitted to the /lnpchecker API will be handled by Bandwidth. See the POST operation for more information
On-NetTNs that belong to a rate center covered by Bandwidth are referred to as on-net TNs
Off-NetTNs that belong to a rate center covered by a Bandwidth partner are refered to as off-net TNs
AutomatedIf the TNs are on-net, or off-net and covered by a Bandwidth partner that supports automated ports, then the port-in of these TNs will be handled with no human intervention
ManualIf the TNs cannot be ported automatically, the Bandwidth LNP team will work with the appropriate porting vendor or losing carrier to ensure completion of the port-in. The /portins API can be used to submit manual port-ins, which will be identified as such, and a Zendesk ticket will be automatically created to notify the Bandwidth LNP team
InternalTNs that are being moved from one Bandwidth account to another Bandwidth account are referred to as internal ports. Internal ports are handled automatically
Losing carrierThe carrier from which the TN(s) is being ported

Checking for Portability#

A number or set of numbers can be checked to see if they can be ported into the Bandwidth Network using the /accounts/{accountId}/lnpChecker API endpoint.

The fullcheck query parameter values control the components of the response payload that is returned.

Request URL#

POST https://dashboard.bandwidth.com/api/accounts/{accountId}/lnpChecker

Request Query Parameter#

fullcheck valueDescription
false (default)Return only rate center information
trueAdditional information will be provided on the losing carriers associated with the listed numbers
onnetportabilityProvides rate center and losing carrier information for onnet tiers only
offnetportabiltyIn addition to on-net information return off-net port information in <PartnerSupportedRateCenters> element with Partner/Vendor that the port will be supported on. Contains a list of the TNs that are supported in partner rate centers, and for which we will manually execute a port if requested for help.

Response Parameters#

ElementDescription
SupportedRateCenters
PartnerSupportedRateCenters
UnsupportedRateCenters
Rate Center information for the indicated set of ratecenters, containing City, State, LATA and the list of TNs for which that Rate Center applies.
The Tier information is provided for offnet rate centers.
SupportedLosingCarriers
UnsupportedLosingCarriers
Details on the Losing Carrier including name, SPID, whether or not the carrier is a wireless carrier, whether or not account number is required as part of the CSR check, and the anticipated minimum number of days before a FoC date will be granted.

Examples#

Request

POST https://dashboard.bandwidth.com/api/accounts/{accountId}/lnpChecker?fullcheck=true HTTP/1.1
Content-Type: application/xml; charset=utf-8
Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=
<NumberPortabilityRequest>
<TnList>
<Tn>9195551234</Tn>
<Tn>9198675309</Tn>
</TnList>
</NumberPortabilityRequest>

Response

HTTP 200 OK
Content-Type: application/xml; charset=utf-8
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<NumberPortabilityResponse>
<PortType>MIXED</PortType>
<PortableNumbers>
<Tn>9198675309</Tn>
</PortableNumbers>
<SupportedRateCenters>
<RateCenterGroup>
<RateCenter>RALEIGH</RateCenter>
<City>RALEIGH</City>
<State>NC</State>
<LATA>426</LATA>
<Tiers>
<Tier>0</Tier>
</Tiers>
<TnList>
<Tn>9198675309</Tn>
</TnList>
</RateCenterGroup>
</SupportedRateCenters>
<UnsupportedRateCenters>
<RateCenterGroup>
<RateCenter>DIR ASST</RateCenter>
<City>CUSTOMER DIRECTORY ASSISTANCE </City>
<State>NC</State>
<LATA>99999</LATA>
<TnList>
<Tn>9195551234</Tn>
</TnList>
</RateCenterGroup>
</UnsupportedRateCenters>
<SupportedLosingCarriers>
<LosingCarrierTnList>
<LosingCarrierSPID>979E</LosingCarrierSPID>
<LosingCarrierName>BANDWIDTH.COM:979E -NSR/1</LosingCarrierName>
<LosingCarrierIsWireless>false</LosingCarrierIsWireless>
<LosingCarrierAccountNumberRequired>false</LosingCarrierAccountNumberRequired>
<LosingCarrierMinimumPortingInterval>3</LosingCarrierMinimumPortingInterval>
<TnList>
<Tn>9198675309</Tn>
</TnList>
</LosingCarrierTnList>
<LosingCarrierTnList>
<LosingCarrierSPID></LosingCarrierSPID>
<LosingCarrierName>Unknown</LosingCarrierName>
<LosingCarrierIsWireless>false</LosingCarrierIsWireless>
<LosingCarrierAccountNumberRequired>false</LosingCarrierAccountNumberRequired>
<LosingCarrierMinimumPortingInterval>10</LosingCarrierMinimumPortingInterval>
<TnList>
<Tn>9195551234</Tn>
</TnList>
</LosingCarrierTnList>
</SupportedLosingCarriers>
</NumberPortabilityResponse>

Create a Portin Order#

The API allows a user to create a new LNP order. An order number will be auto-generated and provided to the customer. The order must pass synchronous and asynchronous validation. Synchronous validation will return validation failures immediately in the response. If synchronous validation passes, but asynchronous validation fails, the customer will not receive the error response until they check the order status.

As in other asynchronous workflows, the request to port in a number is created by a POST to a resource dedicated to the purpose to tracking requests – the accounts/{accountId}/portins resource.

The portins endpoint is used to manage requests to port both toll free and non-toll free telephone numbers into Bandwidth. 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. When a port-in is created, a port-type is assigned based on the telephone numbers provided. A lot of the conditional payload elements are conditional on the basis of the port-type. Port-type can take on the following values:

  • MANUALOFFNET - Manual indicates that the port-in will be processed manually by Bandwidth’s Local Number Portability team. Off-net means that the telephone numbers in the port-in exist in a rate center supported by one of Bandwidth’s partners. Off-net port-ins are processed manually when the Bandwidth partner does not have APIs by which the port-in can be automated, or Bandwidth has not implemented those APIs. Orders may also be processed manually if there are more numbers in the port-in than the partner’s interface supports.
  • MANUALONNET - Manual indicates that the port-in will be processed manually by Bandwidth’s Local Number Portability team. On-net means that the telephone numbers in the port-in exist in a rate center supported by Bandwidth. On-net port-ins are processed manually only when there are more numbers in the port-in than the porting vendor’s interface supports.
  • MANUALTOLLFREE - Manual indicates that the port-in will be processed manually by Bandwidth’s Local Number Portability team. Currently all toll free port-ins are handled manually by Bandwidth’s Local Number Portability team. But Bandwidth is in the process of automating portions of toll free porting, with a goal of eventually automating the entire process.
  • AUTOMATED - Automated means that the port-in will be processed automatically using interfaces to our porting vendors. There are several sub-types of AUTOMATED as follows:
  • ON-NET - On-net means that the telephone numbers in the port-in exist in a rate center supported by Bandwidth. There are differences in on-net port-in rules depending on whether the order is for wireless to wireless vs. one of the other 3 combinations.
  • OFF-NET - Off-net means that the telephone numbers in the port-in exist in a rate center supported by one of Bandwidth’s partners. Currently only numbers in the U.S. are automated. There are differences in port-in rules depending on whether the order has achieved FOC status.
  • INTERNAL - Internal means that the telephone number is being moved from one Bandwidth account to another Bandwidth account. Internal port-in may involve on-net, off-net, or toll free telephone numbers.

Polling vs. Webhooks#

Porting numbers in the Bandwidth Dashboard is asynchronous when creating an LNP "order". The orders are then processed and the order status is updated asynchronously. Bandwidth recommends configuring your account with a subscription instead of polling the order resource for <OrderStatus>.

Order processing times can vary and are not guaranteed, so bandwidth recommends relying on a webhook update from an portins subscription.

Request URL#

POST https://dashboard.bandwidth.com/api/accounts/{accountId}/portins

Request Parameters#

The table column labeled M/O/C is used to indicate if the element is Mandatory, Optional, or Conditional. Conditional elements are mandatory under certain conditions described in the Description column for that element. Mandatory elements are mandatory for all port-types and conditions, and Optional elements are optional for all port-types and conditions.

ParameterM/O/CDescription
AlternateSpidOEven though the telephone numbers are being ported into Bandwidth’s SPID, some of Bandwidth’s wholesale customers have an alternate SPID that is used to identify the telephone number with that customer. This element is not applicable for toll free port-ins.
BillingTelephoneNumberCThe BillingTelephoneNumber is the primary telephone number associated with the invoice that the subscriber gets from the losing carrier. For wireline port-in, the BillingTelephoneNumber is typically the telephone number being ported in. This element is not applicable for toll free port-ins, but mandatory for non-toll free port-ins.
BusinessNameCThe BusinessName is mandatory for non-toll free port-ins for which the SubscriberType is set to BUSINESS. The BusinessName may be up to 25 characters in length. This element is not applicable for toll free port-ins.
CustomerOrderIdOThe CustomerOrderId is an optional field that may be provided by the customer and will remain with the order.

Only alphanumeric values, dashes and spaces are allowed. Max length is 40 characters. The value is opaque to Bandwidth.
ImmediatelyOIncluding Immediately with a value of true will cause an Internal port-in to complete as soon as possible, without requiring a scheduled activation time.

Immediately has no meaning for port types other than Internal.
LoaAuthorizingPersonMThe LoaAuthorizingPerson is mandatory for all port-types. This is the first and last names of the person that has authorized the port. The LoaAuthorizingPerson value may be up to 15 characters in length.
ListOfPhoneNumbersMListOfPhoneNumbers is an array of PhoneNumber. At least one PhoneNumber must be provided for all port-types.
ListOfPhoneNumbers.PhoneNumberMTen digit phone number with no dots or dashes. One or more is required.
Use a <PhoneNumber> tag for each phone number in the <ListOfPhoneNumbers> list.
NewBillingTelephoneNumberOThis field is used to specify a new billing telephone number on the losing carrier account.

Cannot be the same as BillingTelephoneNumber or be present in the list of ported numbers. This element is not applicable to toll free or off-net port-in orders.
PartialPortOThe PartialPort must be set to true if the intent is to NOT port all of the telephone numbers associated with the BillingTelephoneNumber.

If PartialPort is omitted or false, and the ListOfPhoneNumbers does not include all of the telephone numbers associated with the BillingTelephoneNumber, the port-in will be rejected.

PartialPort is applicable only to on-net port-types. This element is not applicable to toll free or off-net port-in orders.
PeerIdOPeerId specifies the numeric identifier of the SIP-peer (Location) that the telephone numbers will be ported into.

You can find the identifier for a SIP-peer (location) by using GET /accounts/id/sites/id/sippeers, or by clicking on 'Accounts' on the upper right of the Bandwidth Dashboard, then clicking 'Locations' on the navigation bar. The SIP-peer (location) identifiers are listed next to each location name. If PeerId is omitted, the SIP-peer (location) designated as the 'default location' for that site (sub-account) will be used.
ProcessingStatusOIncluding ProcessingStatus with a value of DRAFT allows you to create a port-in request, but not process the request. Omitting ProcessingStatus causes the port-in to be validated and, if correct, processed right away.

Be aware, however, that validation of the port-in payload occurs when the request is actually submitted by performing a PUT on the order with ProcessingStatus set to SUBMITTED.
RequestedFocDateOFormat: ISO8601 encoding such as “2013-05-10T15:14:22Z”, or "2019-10-31T17:15:00+04:00".

For all ports, if RequestedFocDate is specified, the date portion must be:
- in the future
- after the losing carrier's minimum number of days to port-out
- not on a weekend or U.S. holiday

If RequestedFocDate is not specified, the next available FOC date meeting the criteria above will be used. If the Time portion of the RequestedFocDate is omitted the port-in order will be activated at the default activation time of 11:30 AM ET. If an activation time other than 11:30 AM ET is desired, that activation time should be included in the RequestedFocDate.
ResetAddressFieldsOThe ResetAddressFields may be specified in a PUT request for a non-toll free port-in order if you would like to remove ServiceAddress elements that are not specified in the PUT payload. Default value is false.
ServiceAddressCThe ServiceAddress is mandatory for all non-toll free port-ins. See sub-fields for additional details.
ServiceAddress.AddressDetail1 - 3OAddressDetail1 may be used to specify Secondary Address Unit Designators, as defined by the Postal Addressing Standards, Publication 28. Generally, AddressDetail1 would be accompanied by AddressValue1.

AddressDetail1, AddressDetail2, and AddressDetail3 are all available parameters.
ServiceAddress.AddressLine2OAddressLine2 is used to specify Unit, Suite, Floor, etc. in the Service Address. AddressLine2 is optional when not needed to fully specify the ServiceAddress.
ServiceAddress.AddressValue1 - 3OAddressValue1 may be used to specify Secondary Address Unit Designators, as defined by the Postal Addressing Standards, Publication 28. Generally, AddressDetail1 would be accompanied by AddressValue1

AddressValue1, AddressValue2, and AddressValue3 are all available parameters.
ServiceAddress.CityCCity is mandatory in cases where the ServiceAddress is mandatory.
ServiceAddress.CountryOCountry is the country of the ServiceAddress. This value will be derived from the StateCode, so it should generally be omitted.
ServiceAddress.HouseNumberCThe HouseNumber is the street address number of the ServiceAddress. HouseNumber is mandatory for port-in orders in which the ServiceAddress is mandatory.
ServiceAddress.HousePrefixOThe HouseSuffix is the non-numeric address number suffix of the ServiceAddress. This element is optional when not needed to fully specify the ServiceAddress.
ServiceAddress.HouseSuffixOThe HouseSuffix is the non-numeric address number suffix of the ServiceAddress. This element is optional when not needed to fully specify the ServiceAddress.
ServiceAddress.PlusFourOPlusFour is the 4 digits that are sometimes suffixed to the Zip Code.
ServiceAddress.PostDirectionalOThe PostDirectional is the street name post directional of the ServiceAddress. This element is optional when not needed to fully specify the ServiceAddress.
ServiceAddress.PreDirectionalOThe PreDirectional is the non-numeric street name prefix of the ServiceAddress. This element is optional when not needed to fully specify the ServiceAddress.
ServiceAddress.StateCodeCStateCode is the 2-letter abbreviation of the state of the ServiceAddress. StateCode is mandatory in cases where the ServiceAddress is mandatory. ex: NC, NY, or AK
ServiceAddress.StreetNameCThe StreetName is mandatory in cases where the ServiceAddress is mandatory.
ServiceAddress.StreetSuffixOThe StreetSuffix is the street suffix of the ServiceAddress. This element is optional when not needed to fully specify the ServiceAddress.
SiteIdMSiteId is mandatory for all port-types. It specifies the identifier of the site (sub-account) that the telephone numbers will be ported into.

You can find the identifier for a site (sub-account) by using GET /accounts/id/sites, or by clicking on 'Manage sub-account' for the desired sub-account on the main page of the Bandwidth Dashboard.
SubscriberCThe Subscriber is mandatory for all non-toll free port-in orders. See sub-fields for details.
Subscriber.FirstNameOThe FirstName value is applicable to non-toll free port-in orders in which the SubscriberType is set to RESIDENTIAL. The FirstName is always optional. The FirstName may be up to 25 characters in length.
Subscriber.LastNameCThe LastName value is mandatory for non-toll free port-in orders in which the SubscriberType is set to RESIDENTIAL. The LastName may be up to 25 characters in length.
Subscriber.MiddleInitialOThe MiddleInitial value is applicable to non-toll free port-in orders in which the SubscriberType is set to RESIDENTIAL. The MiddleInitial is always optional. The MiddleInitial is 1 character in length.
Subscriber.SubscriberTypeCThe SubscriberType is mandatory for all non-toll free port-in orders.

The SubscriberType field may have values: BUSINESS or RESIDENTIAL.
TnAttributesOThe TnAttributes field specifies line attributes that will apply to the ported in telephone numbers. If present, TnAttributes may have a value of PROTECTED. This element is not applicable for off-net or toll free port-types.
TriggeredOThe Triggered field must be set to true if you want an activation time other than the 11:30 AM ET default. The desired activation time can then be specified in the time portion of the RequestedFocDate. Triggered activation is not yet supported for toll free port-in orders.
WirelessInfoOMost common for telephone numbers that were formerly wireless. This element is not applicable for toll free port-ins.
WirelessInfo.AccountNumberOThe AccountNumber is sometimes required to authorize the port-out from the losing carrier. This is most common for telephone numbers that were formerly wireless.
WirelessInfo.PinNumberOThe PinNumber is sometimes required to authorize the port-out from the losing carrier. This is most common for telephone numbers that were formerly wireless.
ZipCZip is the Zip Code of the ServiceAddress. Zip is mandatory in cases where the ServiceAddress is mandatory.

Examples#

Request

POST https://dashboard.bandwidth.com/api/accounts/{accountId}/portins HTTP/1.1
Content-Type: application/xml; charset=utf-8
Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=
<LnpOrder>
<RequestedFocDate>2016-03-25T21:15:00.000Z</RequestedFocDate>
<AlternateSpid>X455</AlternateSpid>
<BillingTelephoneNumber>9195551234</BillingTelephoneNumber>
<NewBillingTelephoneNumber>9175131245</NewBillingTelephoneNumber>
<SiteId>12345</SiteId>
<PeerId>660123</PeerId>
<Subscriber>
<SubscriberType>BUSINESS</SubscriberType>
<FirstName>First</FirstName>
<LastName>Last</LastName>
<ServiceAddress>
<HouseNumber>11235</HouseNumber>
<StreetName>Back</StreetName>
<City>Denver</City>
<StateCode>CO</StateCode>
<Zip>27541</Zip>
<County>Canyon</County>
</ServiceAddress>
</Subscriber>
<LoaAuthorizingPerson>The Authguy</LoaAuthorizingPerson>
<WirelessInfo>
<AccountNumber>771297665AABC</AccountNumber>
<PinNumber>1234</PinNumber>
</WirelessInfo>
<ListOfPhoneNumbers>
<PhoneNumber>9195551234</PhoneNumber>
<PhoneNumber>9195554321</PhoneNumber>
</ListOfPhoneNumbers>
<Triggered>true</Triggered>
</LnpOrder>

Response

HTTP 201 Created
Content-Type: application/xml; charset=utf-8
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<LnpOrderResponse>
<OrderId>03f194d5-3932-4e9f-8ba1-03ef767985e5</OrderId>
<Status>
<Code>201</Code>
<Description>Order request received. Please use the order id to check the status of your order later.</Description>
</Status>
<ProcessingStatus>PENDING_DOCUMENTS</ProcessingStatus>
<RequestedFocDate>2016-03-25T21:15:00.000Z</RequestedFocDate>
<LoaAuthorizingPerson>The Authguy</LoaAuthorizingPerson>
<Subscriber>
<SubscriberType>BUSINESS</SubscriberType>
<FirstName>First</FirstName>
<LastName>Last</LastName>
<ServiceAddress>
<HouseNumber>11235</HouseNumber>
<StreetName>Back</StreetName>
<City>Denver</City>
<StateCode>CO</StateCode>
<Zip>27541</Zip>
<County>Canyon</County>
<Country>United States</Country>
</ServiceAddress>
</Subscriber>
<WirelessInfo>
<AccountNumber>771297665AABC</AccountNumber>
<PinNumber>1234</PinNumber>
</WirelessInfo>
<BillingTelephoneNumber>9195551234</BillingTelephoneNumber>
<NewBillingTelephoneNumber>9175131245</NewBillingTelephoneNumber>
<ListOfPhoneNumbers>
<PhoneNumber>9195551234</PhoneNumber>
<PhoneNumber>9195554321</PhoneNumber>
</ListOfPhoneNumbers>
<Triggered>true</Triggered>
</LnpOrderResponse>

Upload Letter of Authorization (LOA)#

After successfully submitting the Create LNP Order request, an LOA may be uploaded using our LOA API.

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

Request URL#

POST https://dashboard.bandwidth.com/api/accounts/{accountId}/portins/{orderId}/loas

Examples#

Request

POST /api/accounts/9900778/portins/{orderId}/loas HTTP/1.1
Host: dashboard.bandwidth.com
Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=
Content-Type: application/pdf
documentType: LOA
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

Response

HTTP 201 Created
Content-Type: application/xml; charset=utf-8
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<fileUploadResponse>
<filename>63097af1-37ae-432f-8a0d-9b0e6517a35b-1429550165581.pdf</filename>
<resultCode>0</resultCode>
<resultMessage>LOA file uploaded successfully for order 63097af1-37ae-432f-8a0d-9b0e6517a35b</resultMessage>
</fileUploadResponse>

Modify a Portin Order#

The API allows a user to modify an existing LNP order, called a SUPP request. Modifications are only allowed for orders that are not yet complete or cancelled. LNP orders can be modified with a PUT to accounts/{accountId}/portins/{orderId}. Since many of the entries in an LNP Order cannot be changed after the initial order is placed, the PUT on a porting order-id does not require that the full order payload is included.

Items that can be included in a SUPP request include:

  • CustomerOrderId
  • RequestedFocDate
  • BillingTelephoneNumber
  • NewBillingTelephoneNumber
  • AccountNumber
  • PinNumber
  • TnAttributes elements
  • Subscriber elements
  • SiteId
  • PeerId
  • PartialPort
  • LoaAuthorizingPerson
  • ListOfPhoneNumbers
  • Triggered
  • Immediately

If the order ProcessingStatus is DRAFT, the rules about what can be changed are much more relaxed. Validation is performed when the ProcessingStatus is changed from DRAFT to SUBMITTED. The AltSpid element can be modified if it is not configured at the system level.

ProcessingStatus - you can only provide this field with a value of SUBMITTED if the current ProcessingStatus of the port-in is DRAFT.

When a port-in is being processed by off-net partner Level 3 (you can retrieve this information using a GET request to /portins/{orderId} indicates a Port Type of AUTOMATEDOFFNET and a VendorName of "Level 3"), the rules for what can be changed in a SUPP operation are more restrictive. If the order has NOT yet received FOC, you may change the following:

  • RequestedFocDate
  • BillingTelephoneNumber
  • SubscriberType
  • Subscriber name elements or BusinessName, provided that SubscriberType is provided

After the FOC date has been received, the billing telephone number and subscriber information cannot be modified, only the FOC date/time can be updated.

The general approach to handling this API call is to replace the elements included in the request body, and leave other preexisting elements in an unmodified condition. This is typical of a PATCH method, but because of our commitment to backwards compatibility we have elected not to "Fix" this behavior. As a result, there are some elements that cannot be modified using the PUT method. The elements affected vary by Port-In Order type, which can be determined using a GET request to the /portins/{orderId} endpoint. Please refer to the matrix below to see which elements can be modified and replaced.

Payload FieldManual Off-NetManual On-NetManual Toll FreeAutomated On-NetAutomated Off-Net Pre FOCAutomated Off-Net Post FOCInternal
billingTelephoneNumberEditableEditableDisabledEditableEditableDisabledEditable
newBillingTelephoneNumberEditableEditableDisabledEditableDisabledDisabledEditable
partialPortEditableEditableDisabledEditableDisabledDisabledEditable
subscriber.subscriberTypeEditableEditableEditableEditableEditableDisabledEditable
subscriber.businessName/firstName/middleInitial/lastNameEditableEditableEditableEditableEditableDisabledEditable
loaAuthorizingPersonEditableEditableEditableEditableDisabledDisabledEditable
wirelessInfo.accountNumberEditableEditableEditableEditableDisabledDisabledEditable
wirelessInfo.pinNumberEditableEditableDisabledEditableDisabledDisabledEditable
subscriber.serviceAddressEditableEditableEditableEditableDisabledDisabledEditable
requestedFocDateEditableEditableEditableEditableEditableEditableEditable
listOfPhoneNumbersDisabledDisabledDisabledEditableDisabledDisabledDisabled
siteIdEditableEditableEditableEditableEditableEditableEditable
peerIdEditableEditableEditableEditableEditableEditableEditable
customerOrderIdEditableEditableEditableEditableEditableEditableEditable
TnAttributes elementsEditableEditableEditableEditableEditableEditableEditable
ImmediatelyDisabledDisabledDisabledDisabledDisabledDisabledEditable

SUPP Order Field Notes#

  • AccountNumber - Element of WirelessInfo. Not applicable to toll free port-ins. Cannot be SUPPed for Automated off-net port-ins. If you want to SUPP WirelessInfo, you must include both AccountNumber and PinNumber in the payload, even if you are not changing both.
  • AlternateSpid - Not applicable to toll free port-ins. Can only be modified in DRAFT state. Can only be modified if it is not configured at the system level.
  • BillingTelephoneNumber - Not applicable to toll free port-ins. Cannot be SUPPed for Automated on-net wireless to wireless port-ins or Automated off-net port-ins after FOC received.
  • BusinessName - Element of Subscriber. Cannot be SUPPed for Automated on-net wireless to wireless port-ins or Automated off-net port-ins after FOC received.
  • CustomerOrderId - Can always be updated. This field is removed from the order if not provided in the PUT payload.
  • Immediately - Only applicable to Internal port-in orders. May be included in the PUT payload, but cannot be changed in a SUPP.
  • ListOfPhoneNumbers - Can be SUPPed only for Automated on-net port-ins and toll free port-ins. For toll free port-ins, may be SUPPed only in draft states (i.e. DRAFT, VALIDATE_DRAFT_TFNS, VALID_DRAFT_TFNS, or INVALID_DRAFT_TFNS).
  • LoaAuthorizingPerson - Cannot be SUPPed for Automated on-net wireless to wireless port-ins or Automated off-net port-ins.
  • NewBillingTelephoneNumber - Not applicable to toll free port-ins or Automated off-net port-ins. Cannot be SUPPed for Automated on-net wireless to wireless port-ins.
  • OverrideValidation - Applies only to internal ports. This Bandwidth internal flag forces port-out to bypass validity checking (if there are no terminal errors). This flag can be SUPPed only for orders in EXCEPTION status.
  • PartialPort - Not applicable to toll free port-ins. Cannot be SUPPed for Automated on-net wireless to wireless port-ins or Automated off-net port-ins.
  • PeerId - Can always be updated.
  • PinNumber - Element of WirelessInfo. Not applicable to toll free port-ins. Cannot be SUPPed for Automated off-net port-ins. If you want to SUPP WirelessInfo, you must include both AccountNumber and PinNumber in the payload, even if you are not changing both.
  • ProcessingStatus - May only be SUPPed for port-in orders in draft state. The only valid value is “SUBMITTED” (not case sensitive).
  • RequestedFocDate - Can always be updated, but subject to blackout windows if the current date is too close to an assigned FOC date.
  • ResetAddressFields - Not applicable to toll free port-ins. If included with a value of true, any Subscriber elements, including subscriber type, subscriber/business name elements, and service address elements, NOT included in the PUT payload will be removed from the order.
  • ServiceAddress - Element of Subscriber. Includes all address fields. ServiceAddress elements cannot be SUPPed for Automated on-net wireless to wireless port-ins or Automated off-net port-ins. See also, ResetAddressFields.
  • SiteId - Can always be updated.
  • SubscriberName - Element of Subscriber. Includes FirstName, MiddleInitial, and LastName. Cannot be SUPPed for Automated on-net wireless to wireless port-ins or Automated off-net port-ins after FOC received.
  • SubscriberType - Element of Subscriber. Cannot be SUPPed for Automated on-net wireless to wireless port-ins or Automated off-net port-ins after FOC received. If SubscriberType is set to BUSINESS, a BusinessName must be provided. If SubscriberType is set to RESIDENTIAL, a FirstName and LastName must be provided.
  • TnAttributes - Can be SUPPed prior to completion of the port-in request.
  • Triggered - May be included in the PUT payload, but cannot be changed in a SUPP.

Request URL#

PUT https://dashboard.bandwidth.com/api/accounts/{accountId}/portins/{orderId}

Examples#

Request

PUT https://dashboard.bandwidth.com/api/accounts/{accountId}/portins/{orderId} HTTP/1.1
Content-Type: application/xml; charset=utf-8
Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=
<?xml version="1.0" encoding="UTF-8"?>
<LnpOrderSupp>
<CustomerOrderId>SJM00002</CustomerOrderId>
<RequestedFocDate>2014-12-04T13:00:00.000Z</RequestedFocDate>
<BillingTelephoneNumber>8045030092</BillingTelephoneNumber>
<NewBillingTelephoneNumber>9175131245</NewBillingTelephoneNumber>
<WirelessInfo>
<AccountNumber>23453245</AccountNumber>
<PinNumber>1111</PinNumber>
</WirelessInfo>
<Subscriber>
<SubscriberType>RESIDENTIAL</SubscriberType>
<FirstName>Steve</FirstName>
<LastName>McKinnon</LastName>
<ServiceAddress>
<!-- If true will overwrite all address fields,
those which should be required remain required.
Affect only supp. Default false. -->
<ResetAddressFields>true</ResetAddressFields>
<HouseNumber>115</HouseNumber>
<StreetName>Monarch Way</StreetName>
<City>Cary</City>
<StateCode>NC</StateCode>
<Zip>27518</Zip>
</ServiceAddress>
</Subscriber>
<SiteId>743</SiteId>
<PartialPort>true</PartialPort>
<ListOfPhoneNumbers>
<PhoneNumber>2019721004</PhoneNumber>
<PhoneNumber>2019721005</PhoneNumber>
</ListOfPhoneNumbers>
<LoaAuthorizingPerson>Steve McKinnon</LoaAuthorizingPerson>
<AlternateSpid>Foo</AlternateSpid>
</LnpOrderSupp>

Response

HTTP 200 OK
Content-Type: application/xml; charset=utf-8
<LnpOrderResponse>
<OrderId>b6080e4c-7ddf-4faa-bbd8-328a72de9297</OrderId>
<Status>
<Code>200</Code>
<Description>Supp request received. Please use the order id to check the status of your order later.</Description>
</Status>
<ProcessingStatus>REQUESTED_SUPP</ProcessingStatus>
<RequestedFocDate>2014-12-04T13:00:00Z</RequestedFocDate>
<BillingTelephoneNumber>8045030092</BillingTelephoneNumber>
<NewBillingTelephoneNumber>9175131245</NewBillingTelephoneNumber>
<Triggered>false</Triggered>
</LnpOrderResponse>

Cancel a Portin Order#

The API allows a user to cancel an existing LNP order. The order number that was generated in the create request must be provided, and dhe status of the order shall not be marked as COMPLETE. The DELETE method is used for this purpose.

Request URL#

DELETE https://dashboard.bandwidth.com/api/accounts/{accountId}/portins/{orderId}

Examples#

Request

DELETE https://dashboard.bandwidth.com/api/accounts/{accountId}/portins/{orderId} HTTP/1.1
Content-Type: application/xml; charset=utf-8
Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=

Response

HTTP 200 OK