Stand-Alone Port-Ins
Overview
The /portins API is used to create and manage a single port-in order for a set of telephone numbers that are portable and can be ported together. This same API is used for porting both regular and toll free telephone numbers, although unlike bulk port-ins, regular and toll free numbers cannot be mixed together in a stand-alone port-in.
In general, numbers can be ported together if they meet the following criteria:
- They are hosted by the same losing carrier or controlling RespOrg prior to the port-in.
- They are in service with the losing carrier or controlling RespOrg
- A single person has the ability to authorize the port (i.e. one person is financially responsible for the numbers on the losing account)
You can find more information about rules for which numbers can port together in a stand-alone port-in in the sections called
High Level Steps
To create and manage a port-in (regular or toll free), these are the basic steps:
- Check if the numbers are portable and can be ported together.
- Request a FOC date, or default to the earliest estimated FOC date.
- Create the port-in order, possibly in DRAFT state.
- Optionally update fields in the port-in.
- Optionally upload supporting documents.
- Monitor order status.
- Optionally add notes to the order to communicate with Bandwidth.
These steps are not necessarily in a fixed order.
The remainder of this document provides more detailed information for creating and managing port-ins.
Planning Your Port-in
Prior to creating a port-in order, you'll want to determine if the number or numbers are portable, and if you have more than one number, if they can be ported together in one port-in order.
Bandwidth provides two API tools to provide this information:
- /accounts/{accountId}/lnpchecker - for regular telephone numbers
- /accounts/{accountId}/tollFreePortingValidations - for toll free telephone numbers
The /lnpchecker tool is described in LNP Checker.
The /tollFreePortingValidations tool is described in Toll Free Porting Validations.
You may submit up to 5,000 telephone numbers in a stand-alone port-in. But unfortunately, our porting vendors impose lower limits for certain port-types as follows:
- An automated on-net port-in may have up to 999 telephone numbers
- If you have more than 999 telephone numbers that need to be ported in a single port-in order, please contact Bandwidth for assistance.
- An automated off-net port-in may have up to 49 telephone numbers
- Bandwidth will automatically convert an automated off-net port-in with more than 49 telephone numbers to a manual off-net port-in.
If you just want the earliest possible FOC date, you may omit the RequestedFocDate from the /accounts/{accountId}/portins payload. Doing so will cause Bandwidth to determine the earliest FOC date based on our experience with the losing carrier.
If you would prefer to request a specific date, please know that the requested date must be a business day and not fall on a porting holiday, and must not be more than 30 days from the current date.
Creating a Stand-Alone Port-in
Once you have used /lnpchecker or /tollFreePortingValidations to determine if your telephone numbers can be ported together, you can create a port-in order.
Note that you may skip the /lnpchecker or /tollFreePortingValidations checks, but that increases the likelihood that your port-in order will transition to the Exception state as soon as you submit the order. The validations performed by /lnpchecker or /tollFreePortingValidations are repeated when you submit a port-in order. Since some port types do not allow the telephone number list to be edited after submission, you may have to cancel and resubmit the order if it is determined that your telephone numbers cannot be ported in the same port-in order.
The number of telephone numbers that can be included in a port-in order varies depending on the port type.
- An automated on-net port-in, wireless or wireline, may have up to 999 telephone numbers. If the order includes more than 999 telephone numbers, the order is rejected.
- An automated off-net port-in may have up to 49 telephone numbers. If the order includes more than 49 telephone numbers, it is automatically converted into a manual off-net port-in.
- An internal port-in may have up to 5,000 telephone numbers.
- A manual off-net port-in may have up to 5,000 telephone numbers.
- A manual toll free port-in may have up to 5,000 telephone numbers.
Creating a Draft Port-in
Bandwidth provides the ability for you to create a port-in order in DRAFT state. This allows you to manipulate the order with minimal validation checking prior to submitting the port-in. In DRAFT state, a port-in order can exist without all of the mandatory elements, while you gather the necessary information from your customer or back-office systems. Then, when you are ready, you can submit the port-in and all of the validations will be run to ensure that the port-in can be successfully sent to our porting vendor for processing.
To create a DRAFT port-in, you must include the ProcessingStatus element with a value of “draft” when you create the port-in using POST /accounts/{accountId}/portins.
Then you can use PUT /accounts/{accountId}/portins/{orderId} to add or change your port-in order.
When you are ready to submit the draft port-in order, simply PUT to the order with the ProcessingStatus value changed to “submitted”.
Be aware that draft port-in orders are automatically removed from the system if they remain in the draft state and sit idle (i.e. no PUT updates) for 48 hours since the last update.
Creating a Regular Port-in
Use POST /accounts/{accountId}/portins to create a port-in order for regular (non toll free/) telephone numbers. This API is asynchronous, meaning the POST will create an order with a unique order-id that you will use to check status as it progresses. Please see Order Model for more information.
When you POST to /accounts/{accountId}/portins, some validation is performed to ensure that your request is properly formed. If errors are detected during this validation, you will receive a 4xx response that includes one or more Errors objects, containing an error code and description. These errors must be corrected before resubmitting the POST operation.
If your request passes the initial round of validation, you will receive a 201 response, including an OrderId element with a unique string that you will use to refer to the port-in order in subsequent requests. Additional validation is performed at this point, and if errors are detected, the 201 response will include one or more Errors objects and the ProcessingStatus will be set to Exception. In this case, the order is created and you must use PUT /accounts/{accountId}/portins/{orderId} to correct the errors.
All manual port-in orders will activate at 11:30 AM ET on FOC day. For automated orders, you have more flexibility in the activation time, although the details vary slightly based on the specific port type.
For internal ports (i.e. where Bandwidth is already the carrier), automated off-net ports, and automated on-net wireline ports, you may specify an activation time other than 11:30 AM ET using the RequestedFocDate. But this only works if you also include the Triggered element with a value of true. If you do not include the Triggered element in your port-in request, the time portion of the RequestedFocDate will be ignored. For automated on-net wireless port-ins, Triggered=true is implied.
Automated off-net ports may be scheduled for activation between 6:00 AM ET and 10:00 PM ET. Automated on-net and internal ports may be scheduled for activation between 5:00 AM ET and 10:00 PM ET.
Creating a Toll Free Port-in
Use POST /accounts/{accountId}/portins (yes! - the same endpoint as is used for regular port-ins/) to create a toll free port-in order.
See Creating a Regular Port-in above, since all of that applies to toll free port-ins.
But toll free port-ins differ in what happens when a draft or non-draft order is created. When a toll free port-in is created, the software checks all of the toll free numbers to ensure that they are portable and that they belong to the same controlling RespOrg. This checking can take a couple of minutes. So that you can tell what is going on, the toll free port-in order has some ProcessingStatus states as follows:
For non-draft port-ins:
- VALIDATE_TFNS - The toll free number validation is in progress.
- INVALID_TFNS - At least one toll free number included in the port-in is not portable, or cannot be ported together with other toll free numbers included in the port-in.
Note: There is no VALID_TFNS state, because if the toll free numbers are valid in a non-DRAFT port-in, the order transitions to PENDING_DOCUMENTS.
For DRAFT port-ins:
- VALIDATE_DRAFT_TFNS - The toll free number validation is in progress.
- INVALID_DRAFT_TFNS - At least one toll free number included in the port-in is not portable, or cannot be ported together with other toll free numbers included in the port-in.
- VALID_DRAFT_TFNS - All toll free numbers are portable and can be ported together. This is the state from which you can submit your draft toll free port-in order when you are ready.
Nearly all toll free port-ins require a letter of authorization (LOA) to be uploaded to the port-in order. Documents for toll free port-ins are covered below in Adding Documents to a Port-in. The only case in which a LOA document is NOT required for a toll free port-in is when the /portins API is being used to change RespOrg IDs within the same “entity”. (The RespOrg entity is the first 2 characters of the RespOrg ID.) For example, porting a toll free number to TargetRespOrgId xxA01 to xxA02, while leaving the number on the same Bandwidth account.
Unlike regular port-ins, if a toll free port-in requires a LOA document, the port-in order will transition to the PENDING_DOCUMENTS state after successfully validating the toll free numbers. The order will remain in PENDING_DOCUMENTS until a valid LOA is uploaded.
If you have uploaded the LOA to the port-in order while the port-in order was in the DRAFT ProcessingStatus, the toll free port-in order will transition directly to the SUBMITTED state once you submit the port-in.
If the toll free port-in order transitions to the INVALID_TFNS ProcessingStatus due to non-portable toll free numbers, or toll free numbers that cannot be ported together, you may use PUT /accounts/{accountId}/portins/{orderId} with an updated ListOfPhoneNumbers to restart the validation with an updated list of toll free telephone numbers.
If the toll free port-in order transitions to the INVALID_TFNS ProcessingStatus because we could not communicate with our toll free porting vendor, you can use PUT /accounts/{accountId}/portins/{orderId} with RetryValidation set to true. Note that failure to communicate with our porting vendor only occurs after retrying for 5 minutes. So it may be that the porting vendor is in a maintenance window - especially if you are submitting a toll free port-in late at night or on weekends. If this error persists, you can always call Bandwidth to inquire about a possible outage.
Fetching Port-in Status
Anytime you need an update on the status of a port-in order, you should use GET /accounts/{accountId}/portins/{orderId}. This will return the latest information about the port-in. You should do this even if you receive a notification about an order state change, because the GET response contains more information than the notification.
As we've mentioned in other places, port-in orders can take days to complete. While waiting for completion, you may poll the port-in order, or you may subscribe to port-in order status change and notes events.
The key items to look for in the 200 response to GET /accounts/{accountId}/portins/{orderId} are:
- ProcessingStatus - this is the current port-in order state. The values may be:
- DRAFT - The regular port-in order is in draft state and has not been submitted
- VALIDATE_DRAFT_TFNS - The toll free port-in order is in draft state and toll free number validation is in progress.
- INVALID_DRAFT_TFNS - The toll free port-in order is in draft state and toll free number validation has failed.
- VALID_DRAFT_TFNS - The toll free port-in order is in draft state and toll free number validation has completed successfully. From this state, you may submit the toll free port-in order.
- VALIDATE_TFNS - Toll free number validation is in progress for the non-draft toll free port-in order.
- INVALID_TFNS - Toll free number validation has failed for the non-draft toll free port-in order.
- PENDING_DOCUMENTS - The toll free port-in order requires a valid letter of authorization before it can be submitted.
- SUBMITTED - The port-in order has been submitted to the porting vendor.
- EXCEPTION - The port-in order has a problem that requires intervention. The order will include error information describing the problem.
- REQUESTED_SUPP - A request to update the order has been submitted.
- FOC - A firm order commitment date has been agreed upon. The date appears in the order as ActualFocDate.
- REQUESTED_CANCEL - A request to cancel the order has been submitted.
- CANCELLED - The order is cancelled. This could be because someone cancelled it (no errors will be present), or because the order incurred an error that could not be corrected.
- COMPLETE - The order is complete.
- The presence of Errors objects.
Updating a Port-in
A port-in order can be updated using PUT /accounts/{accountId}/portins/{orderId}. The rules about what can be changed vary depending on whether the order is in a draft state, and the port type.
When a port-in order is in one of the draft states (DRAFT, VALIDATE_DRAFT_TFNS, VALID_DRAFT_TFNS, or INVALID_DRAFT_TFNS), all elements may be updated using the PUT operation.
After an order has been submitted, the fields you are allowed to change vary depending on the port-type. The following figure summarizes the rules for updating port-in order fields by port-type.
If a port-in order already has a FOC date assigned, there are limits on how near to the FOC date and activation time you may update the port-in order. Generally, you cannot update a port-in if the FOC date and activation time are less than 24 hours in the future.
Adding Documents to a Port-in
Any time a port-in is requested, a letter of authorization (LOA) may be required by the carrier or account from which the telephone number is being ported. For port-types other than Phase 1 Automated Toll Free, Bandwidth does not prevent submission of a port-in order for which no LOA has been uploaded. But failure to upload a LOA could result in the port-in order being rejected.
For Phase 1 Automated Toll Free port-ins, a LOA must be uploaded prior to submission of the port-in to our toll free porting vendor. The port-in will remain in the PENDING_DOCUMENTS state until a document has been uploaded with type set to LOA and formatted as either PDF or TIFF (the two formats supported by our toll free porting vendor). If multiple LOA documents are present when the toll free port-in order is submitted (e.g. uploaded while the order was still a draft), the most recent one will be sent to the toll free porting vendor.
Some carriers or port-ins may require additional information like a copy of the last invoice from the losing carrier, or a Customer Service Record (CSR).
Document sizes are restricted to 3 mega-bytes.
Documents are uploaded using POST /accounts/{accountId}/portins/{orderId}/loas API. The port-in order must be created prior to uploading documents. The 201 response will assign a unique file identifier that is used to delete, update, or attach metadata to the document.
Documents may be removed from a port-in order using DELETE /accounts/{accountId}/portins/{orderId}/loas/{fileId}. Documents may not be removed after the port-in reaches a terminal state (i.e. CANCELLED or COMPLETE/).
Documents may be replaced using PUT /accounts/{accountId}/portins/{orderId}/loas/{fileId}.
Document metadata may be removed using DELETE /accounts/{accountId}/portins/{orderId}/loas/{fileId}/metadata.
Document metadata may be updated using PUT /accounts/{accountId}/portins/{orderId}/loas/{fileId}/metadata.
Supported Formats
Bandwidth supports document uploads in the following formats, although there are restrictions for toll free port-in LOA formats.
| Document Type | Content Header |
|---|---|
| CSV | text/csv |
| DOC | application/msword |
| DOCX | application/vnd.openxmlformats-officedocument.wordprocessingml.document |
| JPG/JPEG | image/jpeg |
| application/pdf | |
| PNG | image/png |
| TXT | text/plain |
| TIFF | image/tiff |
| XLS | application/vnd.ms-excel |
| XLSX | application/vnd.openxmlformats-officedocument.spreadsheetml.sheet |
For phase 1 toll free port-ins, the LOA document must be uploaded in either PDF or TIFF formats.
Metadata
You may use metadata to specify the document type (LOA, INVOICE, CSR, OTHER), or assign a filename to the document. Metadata is optional except for phase 1 toll free port-ins, which must have at least one document uploaded with the document type metadata set to LOA.
Document metadata may be added in either of the following ways:
- The document type may be included as either a query parameter or an API header in the POST /accounts/{accountId}/portins/{orderId}/loas API call.
- Document type and/or document name may be applied to a document that has already been uploaded using PUT /accounts/{accountId}/portins/{orderId}/loas/{fileId}/metadata.
Port-in Activation
Activation refers to the time on FOC day that the telephone numbers in the port-in will be placed in service. This section describes some rules related to activation times.
All port-ins must activate during our porting vendor's hours of operation. For automated off-net port-ins, between 6:00 AM ET and 10:00 PM ET. For automated on-net port-ins, between 5:00 AM ET and 10:00 PM ET.
If you schedule an activation outside of Bandwidth business hours (8:00 AM ET to 8:00 PM ET), you will receive a warning indicating that support may be delayed if a problem arises. But barring any problems, the activation will occur at the scheduled time.
Scheduled Activation
Manual Port-ins
All manual port-ins are activated by Bandwidth at 11:30 AM ET. This includes manual off-net, manual toll free, phase 1 automated toll free, and project ports. As a result, you should omit the Triggered element and the time portion of the RequestedFocDate. Both will be ignored if included.
It is possible to have manual ports activated at times other than 11:30 AM ET, but to do so requires that you submit a ticket to the Bandwidth LNP team.
A sample RequestedFocDate for a manual port-in looks like:
2023-01-30
Automated On-Net Wireless Port-ins
This section applies to on-net ports in which both the losing carrier and Bandwidth are considered to be wireless carriers. (Bandwidth can behave as a wireless carrier, but this capability must be specially requested from, and agreed to by Bandwidth.)
Automated wireless to wireless port-ins are scheduled by including a time in the RequestedFocDate element of the POST /accounts/{accountId}/portins payload, or adding/modifying the time using PUT /accounts/{accountId}/portins/{orderId}.
The specified time is conveyed to our on-net port-in vendor, who uses it to determine when to complete the port-in order on FOC day.
Valid RequestedFocDate formats follow the ISO8601 standard. Examples with time included:
2023-01-30T20:30:00Z - 20:30 UTC
2023-01-30T13:00:00-0400 - 1:00 PM EST
2023-01-30T17:45:00-0500 - 5:45 PM EDT
Since all wireless ports are scheduled, there is no need to include the Triggered element in the port-in payload. If you do include Triggered with a value of true, you will receive a warning that on-demand activation is not supported for wireless port-ins.
Automated Wireline Port-ins
This section applies to both on-net and off-net ports in which either the losing carrier or Bandwidth are considered to be wireline carriers. (Bandwidth is always considered to be a wireline carrier except by special arrangement.)
Automated wireline port-ins are scheduled by including a time in the RequestedFocDate element of the POST /accounts/{accountId}/portins payload, or adding/modifying the time using PUT /accounts/{accountId}/portins/{orderId}.
The specified time is used by Bandwidth to determine when to complete the port-in order on FOC day.
Valid RequestedFocDate formats follow the ISO8601 standard. Examples with time included:
2023-01-30T20:30:00Z - 20:30 UTC
2023-01-30T13:00:00-0400 - 1:00 PM EST
2023-01-30T17:45:00-0500 - 5:45 PM EDT
For wireline port-ins, if you want an activation time other than 11:30 AM ET, you MUST include the Triggered element with a value of true in your POST /accounts/{accountId}/portins payload. If you do not, your port-in will activate at 11:30 AM ET, and you will not be able to override this time using on-demand activation.
On-Demand Activation
On-demand activation is applicable to automated on-net and off-net wireline port-ins.
Sometimes it is desirable to activate a port-in on FOC day at a time to be determined that same day. For example, if voice over IP equipment is being delivered to the customer premise, and the technician wants to activate the port-in as soon as they've completed the installation, on-demand activation can be used to say “activate the port-in now”.
To do so, customers typically do the following:
- Include the Triggered element with a value of true in the POST /accounts/{accountId}/portins payload.
- Include a scheduled activation time that is late in the day on FOC day in the RequestedFocDate element of the
POST/accounts/{accountId}/portinspayload (e.g. RequestedFocDate2023-01-30T22:00:00-0400). - At the desired activation time, use PUT /accounts/{accountId}/portins/{orderId}/activationStatus with an AutoActivationDate set to a date in the past, meaning to activate immediately (e.g.
2000-02-23/).
To activate immediately, set AutoActivationDate to a date in the past.
Port-in Order Notes
The port-in notes capability provides a means to communicate with Bandwidth regarding a specific port-in order. When you add a note to a port-in order, a Zendesk ticket is automatically created and sent to our LNP team. The LNP team can also use notes to communicate back to you. If you are subscribed to port-in order status notifications, you will also be notified if Bandwidth adds a note to your order.
This capability is very useful for the following type of exchange:
You: Hey, I submitted this order 3 days ago and I have not received FOC. Can you tell me what's going on?
This creates a Zendesk ticket that will be assigned to someone on our LNP team to address.
Bandwidth: I've checked with the porting vendor and they are having difficulty getting a response from the losing carrier. I'll continue to follow up.
This will show up in the order history on the Bandwidth App's Port-in Order Details page. And, if you are subscribed to port-in order status notifications, will notify you via email or webhook, depending on your notification preferences.
Order notes increase productivity by making it easy to ask about an order without you having to cut and paste all of the order context information (e.g. order-id or PON, order state, what you've tried, etc.) into a separate ticketing system.
A note may be created using POST /accounts/{accountId}/portins/{orderId}/notes. The 201 response will assign a unique note identifier allowing you to update the note, if necessary.
You may fetch all of the notes for a port-in order using GET /accounts/{accountId}/portins/{orderId}/notes.
You can update an existing order note using PUT /accounts/{accountId}/portins/{orderId}/notes/{noteId}.
Port-in Order History
Each time a port-in order is created or changes state, a history entry is created showing the order status, a note indicating what happened, the date and time of the change, and what was changed if the order was modified. This order history is retained by Bandwidth as a history of the port-in order.
You can fetch the port-in order history using GET /accounts/{accountId}/portins/{orderId}/history.
Note that it occasionally takes a minute or two to update the order history. So if you perform an operation and immediately fetch the order history, the operation may not yet be reflected.
Finding a Port-in Order
Bandwidth's GET /accounts/{accountId}/portins API provides a way to search for port-in orders using a number of filters. This can be useful if you do not have the port-in order-id for an order, or if you need to find out if a port-in was created for a particular telephone number, etc.
Because this API has the potential to match a large number of port-in orders, the results are paginated. The pagination is controlled by two mandatory query parameters called page and size. Generally you start by setting page to 1, and size to the number of entries you want per page.
If more results exist than the number specified by “size”, you will have to fetch the next page. This can be done by using the Links element in the response payload.
The following query parameters can be used to filter the results. They are all logically ANDed together, such that the results will match all of the query parameters that are present in your query.
- status - only orders in the specified state
- startdate - the earliest last-modified date to include
- enddate - the latest last-modified date to include
- tn - the billing TN
- orderTn - one of the TNs being ported
- customerOrderId - orders matching this customer order id
- pon - orders having this PON
- date - only orders modified on this date
These query parameters are defined in the API reference.
The response will include the pagination links mentioned above, plus a TotalCount element indicating how many results there are in total, which might be greater than the value you supplied for “size”. The results will also contain an object for each order that matched all of your query parameters (limited to “size” entries). This object differs slightly from the data you would receive if you queried the specific order-id using GET /accounts/{accountId}/portins/{orderId}, but includes the main port-in fields, including the order-id.
Canceling a Port-in
You may cancel a stand-alone port-in using DELETE /accounts/{accountId}/portins/{orderId}.
If the port-in order is in DRAFT state, canceling the order will remove it from the system entirely.
If the port-in order is not in DRAFT state, but has not yet been submitted to a porting vendor, the port-in order will transition to the CANCELLED state.
If the port-in order has already been submitted to one of our porting vendors, the port-in order will transition to the REQUESTED_CANCEL state while we make sure that the losing carrier is also aware that the order is being cancelled and can comply. When this happens, the order will transition to CANCELLED state as soon as we've received confirmation from the losing carrier that they have canceled the order.
If a port-in order already has a FOC date assigned, there are limits on how near to the FOC date and activation time you may cancel the port-in order. Generally, you cannot cancel a port-in if the FOC date and activation time are less than 24 hours in the future.
The CANCELLED state is a terminal state, so you cannot do anything further with the order once it has reached this state.
If you've submitted an order that should not, or cannot complete, it is important that you cancel the order so that the telephone numbers in the order will not be prevented from appearing in subsequent orders.