Bulk Port-Ins

Overview

The /bulkPortins endpoint is used to manage requests to port a diverse collection of telephone numbers into the Bandwidth network. These telephone numbers are 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. The elements 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.

High Level Steps

In general, here are the typical high level steps for using bulk port-in:

1. Create the draft bulk port-in order
   • All bulk port-ins are created as drafts
   • All fields are optional for a draft bulk port-in order
   • Include only fields that should be shared to all child port-in orders associated with the bulk port-in (e.g. customer order id, service address, etc.)
2. Add telephone numbers
   • You can add up to 20,000 telephone numbers
   • The telephone numbers will be validated and assigned to child port-in orders according to which telephone numbers can be ported together
3. Check the breakdown status to ensure all of your telephone numbers are portable
   • If there are errors, adjust the telephone number list until the order reaches the VALID_DRAFT_TNS state
4. Optionally, update the port-in list
   • Detach orders that you wish to treat as stand-alone
   • Attach draft stand-alone orders that you want to be part of the bulk port-in
5. Update child port-in orders with information specific to individual port-in orders
   • Update LOA docs for each child order
   • Ensure each child order has the desired requested FOC date
6. Submit the bulk port-in order
   • This causes all child orders to be submitted
   • You will receive a 4xx response if a child order cannot be submitted
7. Monitor for completion
   • You can monitor the bulk port-in, or all child port-ins

The remaining sections describe each of these steps in further detail.

Creating a Bulk Port-in

To create a bulk port-in order, you must make a POST request to our /bulkPortins endpoint. This order is used to manage the porting event throughout the lifecycle of the request. This can be done through tools like Postman or cURL. Note the OrderId field in response. It will be used for the next steps.

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 request payload. It is acceptable to create a bulk port-in with an empty payload if there are no fields to share across child port-ins.

Successful creation of the draft bulk port-in will result in a 201 HTTP response, with payload including an OrderId element that must be used to refer to the bulk port-in order.

A bulk port-in in DRAFT state will be automatically removed after 2 days if no updates occur.

Adding Telephone Numbers

After the bulk port-in is created, add telephone numbers to the order using PUT /bulkPortins/{orderId}/tnList endpoint.

• A bulk port-in may have up to 20,000 telephone numbers.
• The telephone number list may include a mix of regular and toll free telephone numbers.
• A given telephone number may exist in more than one draft bulk port-in order, but can only exist in one active port-in order. An active port-in order is one that is not a draft and not in a terminal state (complete or cancelled).
• Adding telephone numbers will cause the bulk port-in to transition to the VALIDATE_DRAFT_TNS state while the telephone numbers are being validated and separated into child orders.
• If the TN list includes non-portable telephone numbers, the bulk port-in will transition to the INVALID_DRAFT_TNS state. From this state, the TN list must be updated using PUT /accounts/{accountId}/bulkPortins/{orderId}/tnList. Each non-portable telephone number is associated with an error describing why the TN is not portable.
• If toll free number validation cannot be completed due to a problem communicating with our toll free porting vendor (e.g. because they are down for maintenance, or network errors), you can cause the resumption of retries by PATCH on /accounts/{accountId}/bulkPortins/{orderId} with a payload including the RetryValidation element with a value of true. If this error persists, please contact Bandwidth for assistance.
• If the TN list includes only portable telephone numbers, the bulk port-in will transition to the VALID_DRAFT_TNS state. Only from this state can you submit the bulk port-in.
• Once in the VALID_DRAFT_TNS state, one or more child port-ins will exist. Each child port-in includes telephone numbers that can be ported together.
• If toll free telephone numbers are included in the TN list, the validation may take a couple of minutes, depending on how many toll free numbers are present.

Checking Validation Status

The /accounts/{accountId}/bulkPortins/{orderId}/tnList API is asynchronous. If your TN list included toll free telephone numbers, it can take a minute or two to get the results of the validation. If you are subscribed to order events for bulk port-ins, or subscribed to order events to this specific bulk port-in, you will receive a notification when the validation completes and the state transitions to either VALID_DRAFT_TNS or INVALID_DRAFT_TNS. Or, you may use GET /accounts/{accountId}/bulkPortins/{orderId}/tnList to poll for completion of the validation.

Sample GET /tnList response when validation is still in progress.

<TnListResponse>
	<ProcessingStatus>VALIDATE_DRAFT_TNS</ProcessingStatus>
	<OrderId>33b58246-f27c-4b1d-896d-0acc03b3ad8a</OrderId>
	<NotValidatedTnList>
		<TN>8772397726</TN>
		<TN>8006148733</TN>
		<TN>4047221089</TN>
		<TN>7013498774</TN>
	</NotValidatedTnList>
</TnListResponse>

In the above scenario, all of the telephone numbers will appear in the NotValidatedTnList array.

Sample GET /tnList response with non-portable toll free numbers.

<TnListResponse>
	<ProcessingStatus>INVALID_DRAFT_TNS</ProcessingStatus>
	<OrderId>33b58246-f27c-4b1d-896d-0acc03b3ad8a</OrderId>
	<!-- If at least one TN is portable -->
	<PortableTnList>
		<TN>8772397726</TN>
	</PortableTnList>
	<ChildPortinOrder>
		<OrderId>10f48fec-9db0-4f68-8bcb-c8a6a230a2d9</OrderId>
		<TnList>
			<Tn>8772397726</Tn>
		</TnList>
	</ChildPortinOrder>
	<ErrorList>
		<Error>
			<Code>7642</Code>
			<Description>TN list contains at least one toll free number that cannot be ported due to spare status.</Description>
			<TnList>
				<Tn>8005587721</Tn>
			</TnList>
		</Error>
		<Error>
			<Code>7643</Code>
			<Description>TN list contains at least one toll free number that cannot be ported due to unavailable status.</Description>
			<TnList>
				<Tn>8335098835</Tn>
			</TnList>
		</Error>
	</ErrorList>
</TnListResponse>

In the above scenario, all telephone numbers will be accounted for in the PortableTnList or an Error element. For details on toll free number validation, please see Toll Free Porting Validations.

Sample GET /tnList response when validation cannot be completed.

<TnListResponse>
    <ErrorList>
        <Error>
            <Code>7626</Code>
            <Description>No results from toll free porting vendor after trying for 300 seconds.</Description>
            <TelephoneNumbers>
                <Tn>8336001666</Tn>
            </TelephoneNumbers>
        </Error>
    </ErrorList>
    <OrderId>46602764-7dc0-4958-bc09-2c9e20f59bbc</OrderId>
    <PortableTnList/>
    <ProcessingStatus>INVALID_DRAFT_TNS</ProcessingStatus>
</TnListResponse>

In the above scenario, the system has retried for 5 minutes before giving up. You can kick off another 5 minutes of retry attempts (and hopefully succeed!) by issuing a PATCH operation to /accounts/{accountId}/bulkPortins/{orderId} with a payload that includes the RetryValidation element with a value of true. If this condition persists, please contact Bandwidth for assistance. We may have information about toll free porting vendor scheduled maintenance, or estimated time to repair for unplanned outages.

Sample GET /tnList response with portable numbers.

<TnListResponse>
    <ChildPortinOrderList>
        <ChildPortinOrder>
            <OrderId>8762dd42-1f75-4774-93ca-70b3d148ce09</OrderId>
            <TnList>
                <TN>8336532076</TN>
            </TnList>
        </ChildPortinOrder>
        <ChildPortinOrder>
            <OrderId>6691fabd-4c0e-48f5-849d-5a11e2659e21</OrderId>
            <TnList>
                <TN>8336531993</TN>
            </TnList>
        </ChildPortinOrder>
    </ChildPortinOrderList>
    <OrderId>b3d89f9e-a46e-4d56-aaad-9c9d8ac98bb9</OrderId>
    <PortableTnList>
        <TN>8336531993</TN>
        <TN>8336532076</TN>
    </PortableTnList>
    <ProcessingStatus>VALID_DRAFT_TNS</ProcessingStatus>
</TnListResponse>

In the above scenario, both of the toll free numbers were portable. The two toll free numbers are added to separate child port-in orders because they belong to different controlling RespOrgs and therefore cannot be ported together.

Updating the Bulk Port-in (Optional)

Updating Bulk Port-in Data Elements

While the bulk port-in is still in a draft state, you may update it using either PUT or PATCH on /accounts/{accountId}/bulkPortins/{orderId}. PUT may only be used prior to the bulk port-in having child orders. After child orders exist, you must update the bulk port-in using PATCH.

If you PATCH a bulk port-in order that has child port-in orders associated with it, the data you add/update in the bulk port-in will also be written to all child orders. This comes in handy, if you need to update the service address, for example.

But beware if you have already made port-specific updates to any of the child port-ins, because updating the bulk port-in will cause those changes to be overwritten.

Attaching or Detaching Child Port-in Orders

While the bulk port-in is still in a draft state, you may issue PUT /accounts/{accountId}/bulkPortins/{orderId}/portinList to change the child port-ins that are associated with the bulk port-in order.

In order to attach a child port-in to a bulk port-in, both the child port-in and the bulk port-in must be in a draft state. For the child port-in, this means ProcessingStatus is DRAFT. For the bulk port-in, the order must have ProcessingStatus of: DRAFT, VALID_DRAFT_TNS, or INVALID_DRAFT_TNS. Once a child port-in has been attached to a bulk port-in, that child port-in's telephone numbers are included in the bulk port-in's TN list.

If the bulk port-in is already in progress and a child order has to be cancelled and resubmitted (e.g. it encountered an error that could not be resolved by SUPP), it is not possible to attach the new port-in to the bulk port-in. In this case, you will have to manage the new port-in independently of the bulk port-in.

A more common use-case, however, is to use PUT /accounts/{accountId}/bulkPortins/{orderId}/portinList to detach child port-in orders from a bulk port-in. It may be convenient to use the bulk port-in APIs simply as a means to validate a list of numbers and create all of the necessary child port-ins. Doing so alleviates you from the need to determine which telephone numbers can be ported together. If you do not care about trying to have all of the child port-ins complete on the same FOC date, you can detach them and treat them as any other stand-alone port-in order. Unlike attaching child orders, child orders may be detached from the bulk port-in even after the bulk port-in has been submitted (ProcessingStatus is IN_PROGRESS/).

If all of a bulk port-in's child orders are detached, the bulk port-in order returns to DRAFT state. If that draft bulk port-in order is not updated again, it will be removed by the system after two days of being idle.

Updating the TN List

You may update the TN List for a draft bulk port-in using PUT /accounts/{accountId}/bulkPortins/{orderId}/tnList. Doing so causes the telephone number validation to start again. This means the draft bulk port-in returns to the VALIDATE_DRAFT_TNS state while validation is in progress.

Once validation succeeds, the bulk port-in child orders are replaced by new child orders with new child port-in order-ids. But the Bandwidth software attempts to save any data that was present in the prior child port-in orders. It does this by mapping the old and new child port-in orders that have the most telephone numbers in common. When a mapping is determined, the data is copied from the old child port-in order to the corresponding new child port-in order. This capability means you will not lose data you may have altered in the child port-in orders just because you updated a few telephone numbers in the TN list.

If validation fails, as with the original TN list submission, no child port-in orders are created.

Updating Child Port-in Data

Once you have a bulk port-in with some number of child port-ins, you may want to update the child port-in orders by

• Adding additional data that was not present in the bulk port-in
• Overriding data that was shared from the bulk port-in

The data to update will be data that is specific to individual child port-in orders. For example, each child port-in order will likely require its own letter of authorization (LOA) document.

If you wish to make an update that applies to all port-ins, you should make that update in the bulk port-in, causing it to be shared with each child port-in. This is described in the section above called Updating Bulk Port-in Data Elements.

To update a child port-in order, you must use PUT /accounts/{accountId}/portins/{orderId} for elements other than the LOA. To update the LOA for a child port-in, you must use

• POST /accounts/{accountId}/portins/{orderId}/loas to upload a new document
• PUT /accounts/{accountId}/portins/{orderId}/loas/{fileId} to replace a document

FOC Date Handling for Bulk Port-ins

The primary driver for bulk port-in is to allow Bandwidth wholesale customers to port-in their business customers, who may have a mix of numbers from different carriers, or a mix of toll free and non toll free numbers. To make things easier on the business porting their numbers, all of the telephone numbers should port-in on the same day and at the same time.

As a result, the bulk port-in software attempts to schedule all of the port-in orders so that they achieve FOC on the same date and time. For example, if there are multiple child port-in orders associated with the bulk port-in, and one takes longer than all the others to get FOC, all of the child port-ins will be scheduled to match the latest FOC date.

If having all of the child port-ins port on the same date is not important, you may create the port-in orders using bulk port-in, and then detach any child port-in orders for which you want to have independent control of the FOC date. Then you can use PUT /accounts/{accountId}/portins/{orderId} to adjust the requested FOC date on the detached port-in orders.

Submitting the Bulk Port-in

Once you think you have everything the way you want it, you may submit the bulk port-in (and its child port-ins) by updating the bulk port-in ProcessingStatus to IN_PROGRESS. This is done using PATCH /accounts/{accountId}/bulkPortins/{orderId}.

If successful, the bulk port-in state will change to IN_PROGRESS and the child port-ins will change to either SUBMITTED or PENDING_DOCUMENTS (if a document is required).

But when you submit the bulk port-in, additional validation is performed on all of the child port-ins. If any of the child orders cannot be submitted, you will receive a 4xx response to the PATCH operation and the bulk port-in and all of the child port-ins will remain in draft states.

Monitoring for Completion

After submitting a bulk port-in, you may monitor the status by monitoring the bulk port-in, or by monitoring the status of each child port-in.

To monitor the status of the bulk port-in, you may either poll its status using GET /accounts/{accountId}/bulkPortins/{orderId}, or you may subscribe to state change notifications by using POST /accounts/{accountId}/subscriptions with an order type of “bulkPortins”.

After successful submission of a bulk port-in, the ProcessingStatus value will be one of the following:

** ProcessingStatus**	** Meaning**	** Notes**
IN_PROGRESS	The bulk port-in is being processed.
NEEDS_ATTENTION	At least one child port-in order has transitioned to the Exception state.	You will need to examine the status of the child port-in orders to determine which one(s) are in Exception and why.
COMPLETED	The bulk port-in completed successfully.
PARTIAL	Some of the child port-ins have completed and some have been cancelled.	This can happen if a child port-in encounters an error from which it cannot recover. The child order has to be cancelled and resubmitted.
CANCELLED	All of the child port-ins have been cancelled.

To monitor the status by checking the status of each child port-in, you can get the child port-in order-ids by using GET /accounts/{accountId}/bulkPortins/{orderId}/portinList. Once you have the child port-in order-ids, you can use GET /accounts/{accountId}/portins/{orderId} to fetch the status of each. Again, you can poll for status updates, or you can use POST /accounts/{accountId}/subscriptions with an order type of “portins” to subscribe to order state change notifications.

Canceling a Bulk Port-in

Bulk port-in orders that are in one of the draft states (i.e. DRAFT, VALIDATE_DRAFT_TNS, VALID_DRAFT_TNS, or INVALID_DRAFT_TNS) are automatically removed from the system if there have been no changes for more than 48 hours. The actual removal occurs at 09:00 UTC for all draft orders with last modified date older than 48 hours.

You may also remove a draft bulk port-in by using DELETE /accounts/{accountId}/bulkPortins/{orderId}.

After a bulk port-in has been submitted (i.e. changed to IN_PROGRESS), you must cancel all child orders by using DELETE /accounts/{accountId}/portins/{orderId} in order to cancel the bulk port-in order. The status of the bulk port-in will change to CANCELLED only when all of the child port-in orders have been successfully cancelled. If at least one child port-in was already complete and the others were cancelled, the bulk port-in changes to the PARTIAL state.