Toll-free port-in API changes

Effective September 6, 2023, Bandwidth is introducing automated toll-free port-in processing. If you currently submit toll-free port-ins to Bandwidth using either the /portins API or /bulkPortins API, please update your API software.

Important: You do not need to make any updates if you submit toll-free port-ins via the Bandwidth App UI or non-toll-free port-ins using either the /portins or /bulkPortins API.

What are the benefits of toll-free port-in automation?

The automation of the toll-free porting process offers the following benefits:

• Reduction in the time it takes to submit the toll-free port-in
• Decrease in toll-free port-in rejections
• Elimination of human errors between the time you submit the port-in and the time SOMOS processes the order

What is changing with the /portins API?

The toll-free port-in process has been too manual and slow for too long. Bandwidth has taken steps to solve this problem, which required some changes to how you use our APIs to submit toll-free port-ins.

Automation of toll-free number validation

When you submit toll-free numbers in the /accounts/{accountId}/portins API, Bandwidth now fetches the toll-free number status and the controlling RespOrg information from SOMOS. This information is used to determine whether the toll-free numbers are portable and if they can be ported together in a port-in order. This allows you to submit toll-free port-in orders that won’t be rejected for these reasons.

Unfortunately, this validation can’t be accomplished within the 30-second HTTP timeout of the API call. To address this, we’ve introduced two new states: VALIDATE_TFNS and INVALID_TFNS.

A port-in order with toll-free numbers will start in the VALIDATE_TFNS state and remain there while we fetch the toll-free number status and RespOrg data from SOMOS. If all of the toll-free numbers are portable and can be ported together, the port-in will transition to the PENDING_DOCUMENTS state.

However, if any of the toll-free numbers aren’t portable or belong to different controlling RespOrgs, the port-in will transition to the INVALID_TFNS state. To update the toll-free numbers, you can simply PUT /accounts/{accountId}/portins/{orderId} with an updated list of toll-free numbers, causing the order to transition back to the VALIDATE_TFNS state, and then repeat the validation.

Streamlining of data necessary to submit a toll-free port-in

The Bandwidth port-in validation software previously required you to populate some fields that were necessary for non-toll-free port-ins but not used for toll-free port-ins. This enhancement removes these requirements and greatly reduces the data you need to provide when creating a toll-free port-in order.

With this enhancement, only the following port-in fields are mandatory:

• LoaAuthorizingPerson
• ListOfPhoneNumbers
• SiteId
• PeerId (only if you’re not using the default location)
• TargetRespOrgId (new! - see next section)

You may still include the following optional elements:

• CustomerOrderId
• RequestedFocDate
• ProcessingStatus (if you create your port-in in DRAFT mode)

Addition of TargetRespOrgId field to port-in request

The TargetRespOrgId is a new field that was previously only supplied in the LOA. We’ve added it to the /portins payload to better support RespOrg Exception customers.

Generally, you’ll need to set this field to JYT01 when porting to Bandwidth. But there may be circumstances in which you port using another Bandwidth RespOrg ID, or, if you’re a RespOrg Exception customer, you may specify the target RespOrg ID you wish to use.

Mandatory LOA for toll-free port-ins

Because we now automatically submit the RespOrg change request to SOMOS, which requires the inclusion of the LOA, you must upload the LOA in order to submit the toll-free port-in order. This means your port-in order will remain in the PENDING_DOCUMENTS state (following the successful validation of the toll-free numbers) until you upload an LOA as follows:

• Use the documentType query parameter or header of the same name to indicate that the document type is LOA. Prior to this enhancement, you had to make a separate API call to the /accounts/{accountId}/portins/{orderId}/loas/{fileId}/metadata endpoint to set the document type.
• Upload a document in either PDF or TIFF format. The content-type header and the document extension should match.
• Optional: Use the /accounts/{accountId}/portins/{orderId}/loas/{fileId}/metadata endpoint to create a document name.

Note: You may still upload other document types (e.g., INVOICE, CSR, OTHER) as desired, but one valid LOA is now mandatory. 

Once you’ve uploaded the LOA, your port-in order will transition to the SUBMITTED state. From there, Bandwidth will immediately send the RespOrg change to SOMOS, if needed. After this point, your port-in order will behave exactly the same as before the enhancement.

How can I test my changes prior to production deployment?

If you don’t already have an account set up in Bandwidth’s test environment (aka the Interop), we can create one for you. The test environment runs production quality software that is the same, or possibly a day or two newer than production. Its purpose is to allow you to test Bandwidth’s Numbers APIs in an environment separate from Production and not connected to external vendors.

In the test environment, we can provide you with phone number ranges that will cause specific success or error responses for number validation. We can also enable a setting that allows you to manually update the toll-free port-in order state after it has reached the SUBMITTED state. This way, you can trigger notifications for FOC, EXCEPTION, CANCELLED, and COMPLETE states.

Please open a ticket with your Bandwidth Support Team when you’re ready to implement the changes described in this document, and we’ll prepare you for successful testing.

How can I coordinate the transition to the new functionality?

Our goal is to allow you to make changes and deploy them until we enable the feature flag that implements the new functionality on the Bandwidth side. In this section, we’ll examine each of the changes described above and recommend how to transition to the new functionality.

Automation of toll-free number validation

The toll-free number validation didn’t occur prior to this enhancement, so all toll-free numbers belonged to the fictitious “Toll-Free Carrier” and were assumed to be portable. This means when you submit the port-in, it won’t transition to the new VALIDATE_TFNS state. Instead, it will behave like today, going through the PENDING_DOCUMENTS state to SUBMITTED, without mandating the LOA upload.

During the period in which your updates have been deployed, but the feature flag hasn’t been enabled yet, your software would have to support the following state transitions:

• PENDING_DOCUMENTS to SUBMITTED (before the feature flag is enabled, even if no LOA was uploaded)
• VALIDATE_TFNS to INVALID_TFNS (after the feature flag is enabled, if toll-free numbers can’t be ported, or can’t be ported together)
• VALIDATE_TFNS to PENDING_DOCUMENTS (after the feature flag is enabled but LOA not yet uploaded)
• PENDING_DOCUMENTS to SUBMITTED (after the feature flag is enabled and valid LOA uploaded)

The ability to support all of these state transitions avoids having to coordinate your deployment with Bandwidth enabling the feature flag for your account.

Streamlining of data necessary to submit a toll-free port-in

You should continue to send all of the fields you send today in the /portins payload before Bandwidth enables the feature flag. Once the feature flag is enabled, Bandwidth will ignore the unneeded fields and you can remove them at your own convenience.

Addition of TargetRespOrgId field to port-in request

You can continue to include the TargetRespOrgId field before Bandwidth enables the feature flag, although it will be ignored. Once the feature flag is enabled, however, Bandwidth will begin requiring the TargetRespOrgId field in all toll-free port-in requests.

Mandatory LOA for toll-free port-ins

You can continue to upload the LOA after the port-in has already transitioned to the SUBMITTED state before Bandwidth enables the feature flag. Once the feature flag is enabled, the port-in order will remain in the PENDING_DOCUMENTS state until you upload a valid LOA in either PDF or TIFF format. Then, once the document is uploaded, the order will transition to the SUBMITTED state.