Query Regarding Programmatic Management of Operator Connect Number Usage

Hello Devendra,

Thank you for clearly outlining your automation requirements. Based on Microsoft's current public documentation, the supported method for programmatically changing a phone number's usage in Microsoft Teams is the New-CsPhoneNumberUsageChangeOrder PowerShell cmdlet, available in MicrosoftTeams PowerShell module 7.5.0 or later.

This cmdlet submits an asynchronous request to change a phone number's usage, such as converting a user number into a service number. When the request is created, it returns an Order ID, indicating that the change request has been accepted for processing rather than completed immediately.

Before submitting a usage-change request, verify the following prerequisites:

• The phone number is not currently assigned to a user, resource account, voice application, conference bridge, or third-party application.
• The target usage appears under Available usages in Teams Admin Center > Voice > Phone numbers.
• The administrator performing the action holds an appropriate role, such as Teams Telephony Administrator or higher.
• Licensing requirements for the target usage have been met.
• MicrosoftTeams PowerShell module 7.5.0 or later is installed.

Keep in mind that available usage options vary based on factors such as the number type, country or region, licensing configuration, and service provider. For Operator Connect numbers, supported capabilities may also depend on how the operator provisioned the number within the tenant.

While Microsoft documents support for submitting usage-change orders, including changes involving the ServiceType parameter, the documentation does not provide a complete conversion matrix. This is particularly relevant for scenarios involving Third-Party App usage. As a result, support should not be assumed for every Operator Connect number across conversions such as:

• Voice App → Third-Party App
• Third-Party App → Voice App
• User → Voice App
• Voice App → User

The most reliable way to determine whether a specific conversion is supported is to check the number's Available usages in the Teams Admin Center. If the desired usage is not listed, PowerShell is unlikely to bypass underlying restrictions imposed by the provider, number type, region, or licensing model.

Microsoft Graph also exposes Teams telephone number management capabilities through its /beta endpoint. These APIs can retrieve number information and manage number assignments, including assigning, unassigning, and updating assignments for Operator Connect numbers.

However, these APIs focus on number assignments, not the underlying usage type of the phone number. They should not be considered a programmatic equivalent of the Teams Admin Center's Change usage action unless Microsoft publishes a dedicated Graph API for that purpose.

It's also worth noting that Microsoft Graph /beta APIs are subject to change and are not recommended for production-critical automation. At present, the documented and supported approach for automating phone-number usage changes remains:

New-CsPhoneNumberUsageChangeOrder

If the requested usage is unavailable, or if a usage-change request fails for an Operator Connect number, the next step is to engage both the Operator Connect provider and Microsoft 365 Support. The provider may need to verify whether the number was provisioned with the capabilities required for the intended usage.

At this time, Microsoft's public documentation does not confirm the existence of an internal Microsoft API, a partner-exclusive Operator Connect API, or any roadmap commitment to expose usage-change functionality through Microsoft Graph. Likewise, any undocumented endpoints used by the Teams Admin Center should be avoided, as they are unsupported and may change without notice.

References:

• New-CsPhoneNumberUsageChangeOrder
• Manage the usage of a phone number
• Configure Operator Connect
• Microsoft Graph numberAssignment

For scenarios involving Third-Party App usage, I recommend validating the number's available usages first and testing the workflow with a non-production number before rolling out automation at scale. This helps confirm provider-specific behavior and avoids unexpected restrictions in production environments.
I hope this information is helpful and please let me know if you need any further assistance.