Skip to main content
POST
cURL
This is an enterprise feature and requires an organization account with sub-accounts.
Use this API to move a phone number from one sub-account to another, from the main account to a sub-account, or from a sub-account back to the main account. It changes which account owns the number. To transfer a live call to another number, see call transfer.
  • Pass null for source_sub_account_id or target_sub_account_id to refer to the main (organization) account.
  • source_sub_account_id must match the sub-account the number currently belongs to.
  • The phone number must not be linked to an agent. Unlink the inbound agent before moving it.
  • Multi-tenant sub-accounts are not supported as a source or target.
This endpoint was previously POST /phone-numbers/transfer. That path still works but is deprecated, so use /phone-numbers/move in new integrations.

Authorizations

Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Body

application/json

Phone number to move, along with its current (source) and new (target) sub-account

phone_number_id
string<uuid>
required

The id of the phone number to move, from the List phone numbers API

Example:

"123e4567-e89b-12d3-a456-426614174000"

source_sub_account_id
string<uuid> | null
required

The sub-account id the phone number currently belongs to. Pass null if the number is on the main (organization) account.

Example:

null

target_sub_account_id
string<uuid> | null
required

The sub-account id to move the phone number to. Pass null to move it back to the main (organization) account. Must be different from source_sub_account_id.

Example:

"a3f1c2d4-5e6b-4c7d-8e9f-0a1b2c3d4e5f"

Response

Phone number move response

message
string
Example:

"Phone number moved successfully"

phone_number_id
string<uuid>

The id of the moved phone number

Example:

"123e4567-e89b-12d3-a456-426614174000"

phone_number
string

The moved phone number in E.164 format

Example:

"+19876543210"

source_sub_account_id
string<uuid> | null

The sub-account the phone number was moved from (null for the main account)

Example:

null

target_sub_account_id
string<uuid> | null

The sub-account the phone number was moved to (null for the main account)

Example:

"a3f1c2d4-5e6b-4c7d-8e9f-0a1b2c3d4e5f"