Skip to main content

Manage bulk port-in orders

The bulkPortins endpoint is used to manage requests to port a diverse collection of Telephone Numbers into the Bandwidth Dashboard. These telephone numbers will be decomposed into a set of individual port-in orders based on port-type, losing carrier, losing RespOrg, etc., making all reasonable attempts to treat the individual port-in requests in a uniform manner. Like many other requests, the bulkPortins endpoint causes the creation of a Bulk Portins order that is used to manage the porting event throughout the lifecycle of the request.

When a bulk port-in is created successfully, it will have one or more child port-in orders that satisfy the following industry port-in rules:

  • Telephone numbers in a child port-in order all have the same port-type (e.g. toll free, automated on-net, automated off-net, internal, etc.).
  • Non-toll free telephone numbers in a child port-in order all have the same losing carrier.
  • Toll free telephone numbers in a child port-in order all have the same losing RespOrg.

The elements used or supplied in the bulk port-in payload are described in the table below. The values supplied in the bulk port-in payload are cascaded to the child port-in orders when possible. This is useful, for example, if you want all of the child orders to have the same CustomerOrderId, or RequestedFocDate.

All bulk port-ins start in a draft processing status and remain in a draft state until explicitly submitted by setting the bulk port-in ProcessingStatus to IN_PROGRESS. The bulk order starts in “DRAFT” state until telephone numbers are added using the /tnList endpoint. Once telephone numbers are added, the order transitions to VALIDATE_DRAFT_TNS, and from there to either VALID_DRAFT_TNS, or INVALID_DRAFT_TNS. If there are invalid, or non-portable telephone numbers, a GET on /tnList will show the errors. If all telephone numbers are portable, child port-in orders are created to handle the actual port-ins.

A bulk port-in order may have one of 3 terminal processing statuses: COMPLETED, CANCELLED, or PARTIAL, which are just an aggregation of the child order statuses. An order in a “terminal” state will never transition to any other processing status (terminal or not). A bulk port-in order goes to a terminal status automatically as soon as the last of its associated child port-ins transfers to terminal status (COMPLETE or CANCELLED). The resulting terminal processing status of the bulk port-in order depends on statuses of associated child port-ins: COMPLETED - when all child port-ins are in COMPLETE status, CANCELLED - when all child port-ins are in CANCELLED status, PARTIAL - when there is a mix of CANCELLED and COMPLETE child port-in statuses.

The following table describes parameters for the bulk port-in API. All parameters except for the URL parameter "accountId" are optional in the bulk port-in, although the rules for individual child port-ins described in the /portins API still apply to the child port-ins that make up the bulk port-in. Enforcement of required fields in the child port-ins occurs when the bulk port-in is submitted (i.e. changed from a DRAFT status to IN_PROGRESS). Only fields that you wish to use as defaults for all of the child port-in orders should be included in the bulk port-in order. The child port-ins are also created in DRAFT status, allowing you to update fields that need to be different for each child order before the child orders are submitted.

ParameterDescription
accountId (URL Parameter)The account ID for porting the numbers.
CustomerOrderIdInternal customer order id for tracking the order. This can be any alphanumeric string.
RequestedFocDateIf present this will specify the date and time that the port-in is requested to happen. The actual time and date is subject to negotiation with the losing carriers. Format is ISO8601 encoding of ZULU/UTC/GMT such as “2013-05-10T15:14:22Z”.
AlternateSpidUnique customer AltSPID to be applied to the port-in requests. Can be changed only for DRAFT bulk port-in.
BillingTelephoneNumber (BTN)Account or Billing telephone number for order. This will be unusual for bulk port-in requests that are expected to decompose into port-in requests from multiple carriers, because the value will be different for each losing carrier.
SubscriberType(BUSINESS, RESIDENTIAL) If residential, order will be rejected if a BusinessName is entered.
BusinessNameSubscriber business name.
FirstNameSubscriber first name.
MiddleInitialSubscriber middle initial.
LastNameSubscriber last name.
HouseNumberStreet address number.
HousePrefixStreet address number prefix.
HouseSuffixStreet address number suffix.
PreDirectionalStreet address pre-directional.
StreetNameStreet name.
StreetSuffixStreet suffix.
PostDirectionalStreet address post directional.
AddressLine2Put unit, suite, floor, etc. here.
CityCity.
StateCodeTwo letter state code.
ZipZip code.
PlusFourZip + 4 value.
Country3 letter country code.
LoaAuthorizingPersonFirst and last name of person who authorized LOA.
AccountNumberAccount number associated with the account on the losing carrier, often required for wireless ports, or enterprise ports. This will be unusual for bulk port-in requests that are expected to decompose into port-in requests from multiple carriers.
PinNumberPIN Number, often required for wireless ports.
siteidThis is the Site / Sub-Account ID made visible in the /accounts/{accountId}/sites API call
PeerIdThis is the SIP Peer / Location ID made visible in the /accounts/{accountId}/sites/{siteId}/sipPeers API call
TnAttributesAttributes to be assigned to the telephone number. Optional parameter. Possible values - "Protected"