> ## Documentation Index > Fetch the complete documentation index at: https://www.bolna.ai/docs/llms.txt > Use this file to discover all available pages before exploring further. # Move phone number API > Move a phone number between the main account and sub-accounts in your Bolna organization. An enterprise feature that needs sub-accounts. > [!NOTE] > > This is an `enterprise` feature and requires an organization account with [sub-accounts](/docs/api-reference/sub-accounts/overview). 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](/docs/tool-calling/transfer-calls.md). * 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](/docs/api-reference/inbound/unlink.md) 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. ## OpenAPI ````yaml POST /phone-numbers/move openapi: 3.1.0 info: title: Bolna API description: >- Use and leverage Bolna Voice AI using APIs through HTTP requests from any language in your applications and workflows. license: name: MIT version: 1.0.0 servers: - url: https://api.bolna.ai description: Production server security: - bearerAuth: [] tags: - name: SIP trunks description: >- Bring-your-own-carrier SIP trunks, their gateways, carrier IPs and numbers. paths: /phone-numbers/move: post: description: >- Move a phone number between the main account and sub-accounts of your organization. This changes which account owns the number. To transfer a live call to another number, see [call transfer](/tool-calling/transfer-calls). requestBody: description: >- Phone number to move, along with its current (source) and new (target) sub-account content: application/json: schema: $ref: '#/components/schemas/MovePhoneNumberRequest' required: true responses: '200': description: Phone number move response content: application/json: schema: $ref: '#/components/schemas/MovePhoneNumberResponse' '400': description: >- Bad request — invalid payload, source and target are the same, the number is not in the given source sub-account, a multi-tenant sub-account is involved, or the number is still linked to an agent. content: application/json: schema: $ref: '#/components/schemas/Error' examples: Linked to an agent: summary: The phone number is still linked to an agent value: message: >- Cannot move: phone number is linked to an agent. Please unlink the agent first. Wrong source sub-account: summary: >- The phone number does not belong to the given source sub-account value: message: Phone number is not in the specified source subaccount Multi-tenant sub-account: summary: The source or target sub-account is multi-tenant value: message: Move not supported for multi-tenant subaccounts '403': description: >- Forbidden — the account is not part of an organization, or the phone number or a sub-account does not belong to your organization. content: application/json: schema: $ref: '#/components/schemas/Error' examples: Not an organization account: summary: The API key does not belong to an organization account value: message: This feature requires an organization account Sub-account outside organization: summary: The target sub-account belongs to a different organization value: message: Target subaccount does not belong to your organization '404': description: >- The phone number, source sub-account or target sub-account was not found content: application/json: schema: $ref: '#/components/schemas/Error' examples: Phone number not found: value: message: Phone number not found Target sub-account not found: value: message: Target subaccount not found components: schemas: MovePhoneNumberRequest: type: object required: - phone_number_id - source_sub_account_id - target_sub_account_id properties: phone_number_id: type: string format: uuid example: 123e4567-e89b-12d3-a456-426614174000 description: >- The `id` of the phone number to move, from the [List phone numbers API](/api-reference/phone-numbers/get_all) source_sub_account_id: type: string format: uuid nullable: true example: null description: >- The sub-account `id` the phone number currently belongs to. Pass `null` if the number is on the main (organization) account. target_sub_account_id: type: string format: uuid nullable: true example: a3f1c2d4-5e6b-4c7d-8e9f-0a1b2c3d4e5f description: >- 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`. MovePhoneNumberResponse: type: object properties: message: type: string example: Phone number moved successfully phone_number_id: type: string format: uuid example: 123e4567-e89b-12d3-a456-426614174000 description: The `id` of the moved phone number phone_number: type: string example: '+19876543210' description: >- The moved phone number in [E.164](https://en.wikipedia.org/wiki/E.164) format source_sub_account_id: type: string format: uuid nullable: true example: null description: >- The sub-account the phone number was moved from (`null` for the main account) target_sub_account_id: type: string format: uuid nullable: true example: a3f1c2d4-5e6b-4c7d-8e9f-0a1b2c3d4e5f description: >- The sub-account the phone number was moved to (`null` for the main account) Error: required: - error - message type: object properties: error: type: integer format: int32 message: type: string securitySchemes: bearerAuth: type: http scheme: bearer ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.