Moving Phone Numbers

The MoveTn Order facilitates the movement of phone numbers between different locations (formerly "SIP peer"). Since locations have specific settings (e.g., messaging enabled/disabled), moving a number might alter its service state. This process is further complicated if the destination Location is on a different account, which also has its own distinct settings. This guide aims to explain the various MoveTn order options and suggest appropriate strategies for different situations.

Two High-Level Move Scenarios

Moving within an Account to a Different Location

In this case, the destination location may or may not be on the same subaccount (formerly "site"). Key considerations in this scenario:

• What are the different settings between the two locations?
• Is messaging enabled/disabled on the destination location?
• Are there different voice settings on the destination location?

Moving to a Location on a Different Account

There are multiple considerations in this scenario:

• Differences between the location settings (ie: messaging)
• Are the phone numbers in a 10DLC messaging campaign?
• Differences between the account E911 configurations?
• How are voice services configured?

Recent MoveTn Changes

July 2025

Some exciting recent changes and enhancements to the MoveTn Order:

• MoveTn Checker endpoint (Available now, JSON-only)
  • The MoveTn Checker allows users to “test” moving numbers within or across accounts. It provides feedback using the same validation the MoveTn Order endpoint uses without actually moving the numbers.
• Graceful handling of invalid numbers (Scheduled: August 1, 2025)
  • If invalid numbers are included in the MoveTn Order request, they will be ignored, resulting in a Partial order (or Failed if they are all invalid).
• Preventing Messaging Service Disruption (Scheduled: August 1, 2025)
  • Prior to this update customers could move numbers to a new location and unknowingly break the messaging capabilities of the number.
    • For example, if the destination location had SMS disabled, it would disable it on the number during the move.
    • Another example, numbers on a 10DLC messaging campaign cannot be moved to a new account and would be automatically removed from the campaign.
  • In this update, we now block these adverse actions by default. For customers that wish to do these moves anyway can use parameters to “bypass” the blocks.

Callback Webhooks for MoveTn Orders

It may be valuable to receive a callback notification for MoveTn orders (like other Bandwidth order types). This allows users to trigger other actions based on status changes of the MoveTn order. Combined with the MoveTn Order Details API, the callbacks can be a valuable way for identifying warnings and errors in MoveTn orders.

Learn more: Order Webhook Guide

Important Properties and Considerations of the MoveTn Order

Moving Across Accounts

SourceAccountId is only used when moving numbers from one account to another account.

Note: when moving across accounts, please review the impacts to Emergency/Voice Services and consider using the MoveTn Checker endpoint to preview any warnings or errors.

Moving via the Bandwidth App User Interface

When moving numbers across accounts within the Bandwidth App UI, it’s helpful to think about it as a “push” process; you login to the account where the number currently resides. You can then double-check the number details and then visit the MoveTn page to specify where you want to “push” the number. You will select the destination account, sub-account and location and any other relevant move parameters.

Impact to Emergency Services / E911

When possible, the MoveTn order will attempt to “move” the E911 service active on a number to the new account. However, this is fairly limited. More often, when moving from one account to another with different E911 service, the E911 service will need to be removed from the number and then re-applied after the move on the new account.

E911ServiceAction parameter provides flexibility on handling the E911 service of a number when moving to a new account. The default is to “MOVE,” but that may not be possible, resulting in an error where DELETE is required. For example, if moving numbers to an account that uses PIDFLO for E911 then E911ServiceAction = DELETE is required, and the E911 service will need to be configured on the numbers after the move.

Impact to Voice Services

For “legacy” Bandwidth accounts that use voice configurations at the location level, moved numbers will simply inherit the voice settings of the location they are moved to.

For Universal Platform accounts that utilize Voice Configuration Packages (VCPs), the location does not impact voice service - that is done through the VCP assigned to the number.

VoiceConfigurationPackageId - when moving to an account with Voice Configuration Packages enabled, it is important to include a VCP so that voice service will be enabled on the number during the move to avoid service disruption.

Impact to Messaging Services

Preventing unintended loss of messaging service

Beginning August 1, we will block moving numbers where messaging service (including campaign assignment) will be disrupted. If you would like to remove numbers from a campaign or disrupt messaging service while moving numbers, utilize the following parameters:

• BypassMessagingLossBlock - by default this is false and a number is protected from losing messaging service.
• BypassMessagingCampaignBlock - by default this is false and a number is protected from being removed from a 10DLC messaging campaign.

By setting both of these bypass parameters to true it will allow moving numbers in these scenarios (removing messaging and/or campaigns).

Protecting Disabled Messaging Services on Numbers

MessagingService - allows users to specify how to handle messaging services on a number. There are a couple account and location configurations that can impact messaging settings:

• Account level: Messaging Setting “Enabled on new TNs” - this is a special account setting that automatically enables messaging services when numbers are added to a messaging-enabled location. Bandwidth Support can help with any additional details.
• Location level: SMS/MMS enabled for the location - this is a setting you manage at the location-level.

If these account and location settings are enabled and a number is moved to that account and location then messaging service will be provisioned for the number.

If you wish to prevent the “automatic” activation on a number where SMS is disabled then set MessagingService = UseCurrentNumberSettings and it will leave SMS disabled on the number.

This is an important setting if messaging service on a number is done through a provider other than Bandwidth. When moving these numbers UseCurrentNumberSettings will prevent Bandwidth from auto-activating messaging and overwriting the other provider.

Impact to Line Features

Line features are retained during moves unless the destination account does not support them. Supported features include:

• Port-out passcode
• Number protection
• LIDB
• DLDA

Limitations of the MoveTn Order

The MoveTn Order, like other Bandwidth orders, includes some limitations for performance and manageability:

Constraint	Limit
Max phone numbers per order	5,000
Rate limit	~10k numbers/min; 150 orders/min
Destination constraint	One Location per order
Cross-account constraint	Must stay within same Global Account Number

These limitations allow the MoveTn Order to be a relatively “fast” order to execute - typically within a second or two. There are other validations done based on account and location configurations. These can be observed by using the MoveTn Checker endpoint - if desired.

Utilizing the MoveTn Checker Endpoint

Before executing large or cross-account moves, it’s important to test them using the MoveTn Checker endpoint. It is a synchronous endpoint that takes the same request body as the MoveTn Order (JSON-only) and performs all the same validations and checks as the order - but, it doesn’t actually move the number or change any of its settings or configuration. The MoveTn Checker will return any warnings or errors to provide visibility to users so they can make any adjustments or understand the impact of move scenarios.

Upgrading to a Bandwidth Universal Platform Account

With the release of the Bandwidth Universal Platform customers may choose to work with the Bandwidth team to set up a new account and move numbers from their legacy account to the new account.

Bandwidth has an upgrade initiative underway to help customers with this process. It will utilize different strategies and tools (like the MoveTn Checker and Order) to help customers make the most of the new Universal Platform capabilities.