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?

Key Behaviors to Know

• MoveTn Checker endpoint (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.
• Handling of invalid numbers
  • A phone number that is not a validly formatted E.164 number causes the entire request to be rejected (HTTP 400) — nothing is moved, including the MoveTn Checker, the single order, and the bulk order endpoints.
  • A correctly formatted number that fails another check (not in your inventory, not in a movable status, already on another in-flight order, and similar) is reported individually and excluded from the move; the rest of the numbers in the request are still processed.

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. Omit it for within-account moves — sending the destination account's own ID in this field causes the request to be rejected.

The property names below use the JSON (camelCase) names used by the MoveTn Order, Bulk MoveTn Order, and MoveTn Checker endpoints. The legacy XML MoveTn Order endpoint uses PascalCase element names instead (for example SourceAccountId), and does not support bulk, campaign migration, or the MoveTn Checker.

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 moving a number across accounts, Bandwidth transfers its E911 endpoints to the destination account as part of the move. This requires the source account to have E911 or Emergency service and the destination account to have Emergency service; if either account lacks the necessary product, the legacy MOVE/DELETE handling below applies instead.

Before the transfer, NANP voice numbers go through an E911 validation check. If that validation fails, or the validation service is unavailable, the move is rejected for the numbers involved. If the transfer itself fails after passing validation, the order still completes, but Bandwidth adds a note to the order's history: "An error was encountered while transferring emergency services endpoints to the destination account. Please transfer emergency services manually or reach out to support." Always check order history on cross-account moves involving E911-enabled numbers. A failure that happens after the transfer has been accepted (asynchronously) is not reflected in the order at all — if you have numbers with E911 service, confirm E911 configuration on the destination account after the move completes.

e911ServiceAction parameter provides flexibility on handling the E911 service of a number when moving to a new account. It is only valid for cross-account moves — setting it on a within-account move is rejected. 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. An explicit MOVE to a destination account that does not have the E911 product also fails the move.

A MoveTn order that completes successfully may still include warnings if E911 provisioning or unprovisioning didn't fully succeed on a number — check the warnings list on the order status response in addition to errors.

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 a number across accounts to a destination with Voice Configuration Packages enabled, this is required if the number currently belongs to the source account and is voice-enabled — the move is rejected without it. Supplying a voiceConfigurationPackageId to a destination account without the Voice Configuration Packages feature is also rejected, as is a package that's incompatible with the numbers being moved.

Moving a number across accounts from a source account that has Voice Configuration Packages enabled to a destination account that does not is not currently allowed.

Impact to Messaging Services

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 = USE_CURRENT_NUMBER_SETTINGS and it will leave SMS disabled on the number (the value is matched case-insensitively, so UseCurrentNumberSettings also works).

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

Setting messagingService = USE_CURRENT_NUMBER_SETTINGS also triggers its own, request-level compatibility check: the whole move is rejected if the destination location has SMS or MMS disabled while the source location has it enabled and the numbers being moved have messaging, or if the source and destination locations both have SMS enabled but use different A2P/P2P message types, or if you're moving across accounts and the two accounts' NNIDs don't match.

Impact to Line Features

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

• Port-out passcode - kept on the number if the destination account supports port-out passcode protection; otherwise it is removed during the move.
• 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.

A phone number is also blocked from moving if any of the following apply:

• It is not in InService or InAccount status.
• It is on another order that is still processing, or has a port-out in progress.
• It is a short code being moved across accounts — short codes can only move within an account.
• (Cross-account only) It is an external number — external numbers must be moved with an Import TN order instead.
• (Cross-account only) It is a toll-free number and the destination account doesn't have toll-free calling enabled.
• (Cross-account only) Its voice and messaging services would end up on different locations within the destination account — voice and messaging must reside on the same location.

See Moving Numbers in Bulk below for the bulk order's additional, separate limit on total numbers per order.

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 almost the same request body as the MoveTn Order (JSON-only) — it does not accept customerOrderId, since it doesn't create an order — and performs the same validations as the order, but it doesn’t actually move the number or change any of its settings or configuration. The MoveTn Checker returns validation errors per phone number so you can make adjustments before submitting the real move. Warnings (for example, related to E911 or SMS provisioning) are produced only by the actual order, not by the Checker.

Moving Numbers in Bulk

The Bulk MoveTn Order endpoint must be enabled on your account before you can use it — contact Bandwidth support to get started.

For larger moves spanning multiple destinations, use the Bulk MoveTn Order endpoint. A single bulk order request can contain multiple orderDetails groupings, each with its own destination sub-account, location, and configuration (source account, VCP, requirements package, messaging and E911 settings).

The total number of unique phone numbers across all orderDetails groupings in one bulk order is limited by an account-level setting — contact Bandwidth support if you need yours raised. Exceeding it rejects the entire bulk order (no order is created).

Internally, Bandwidth creates one or more child MoveTn orders from each orderDetails grouping. Numbers are split into separate child orders by destination, configuration, country code, and campaign — in particular, toll-free numbers and numbers being migrated with a messaging campaign (see below) always end up in their own child orders, and any single grouping larger than 5,000 numbers is further split into multiple child orders of up to 5,000 numbers each.

A bulk order's status can be RECEIVED, PROCESSING, COMPLETE, or FAILED (bulk orders don't have a PARTIAL status — that only applies to the underlying child orders). FAILED means either the whole request was rejected up front, or every number in it failed validation so that no child orders could be created. A COMPLETE bulk order can still have a non-empty errors list — this reports individual numbers that were excluded during validation and weren't moved, even though the rest of the order succeeded. Always check errors on a bulk order, even when its status is COMPLETE.

Migrating 10DLC Messaging Campaigns

When moving numbers across accounts in a bulk order, set migrateCampaign to true to move each number's 10DLC messaging campaign along with it, instead of removing the number from its campaign. This requires:

• Every orderDetails grouping in the request to specify the same sourceAccountId (campaign migration only works cross-account, and only with a single source account per bulk order).
• Both the source and destination accounts to support campaign import.
• The source and destination accounts' CSP IDs to match.
• The source and destination accounts' NNIDs to match.
• The destination location to have A2P messaging enabled if the source location does.
• The source account to be the current messaging owner of the numbers.
• Each campaign being migrated to contain 17,000 numbers or fewer, with every number on that campaign included in the same bulk order.

A number whose campaign doesn't meet these requirements is excluded from the move and reported in the bulk order's errors; the rest of the order proceeds normally.

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.