How to find unassigned phone numbers in Microsoft Teams

Before you start

Use an account that can manage phone numbers: Teams Telephony Administrator, Teams Communications Administrator or Teams Administrator, with a Teams licence. The PowerShell module needs Windows PowerShell 5.1 or PowerShell 7.2 or later. The example passes no permission or scope: its access is the signed-in account's role.

The Teams admin centre shows Voice only when the tenant has an Enterprise E5 licence (or Teams Premium), a Teams Phone add-on licence or an Audio Conferencing add-on licence. The examples read and export; they change nothing.

Option 1

Find unassigned phone numbers with PowerShell

Install the module once, then connect and export every number with an assignment status of Unassigned.

# Install once, if the module is not already installed.
Install-Module MicrosoftTeams -Scope CurrentUser

$ErrorActionPreference = 'Stop'
Connect-MicrosoftTeams | Out-Null
try {
    $query = @{ PstnAssignmentStatus = 'Unassigned'; Top = 1000 }
    $skip = 0
    $numbers = @()
    do {
        $batch = @(Get-CsPhoneNumberAssignment @query -Skip $skip)
        $numbers += $batch
        $skip += $query.Top
    } while ($batch.Count -eq $query.Top)
    if ($numbers.Count -eq 0) {
        Write-Output 'The tenant has no unassigned phone numbers.'
    } else {
        $numbers |
            Select-Object TelephoneNumber, NumberType, ActivationState, City, IsoCountryCode,
                NumberSource, AssignmentBlockedState,
                @{ Name = 'Capability'; Expression = { $_.Capability -join ', ' } } |
            Export-Csv -Path './unassigned-phone-numbers.csv' -NoTypeInformation -Encoding utf8
        Write-Output "$($numbers.Count) unassigned phone numbers."
    }
} finally {
    Disconnect-MicrosoftTeams
}

The cmdlet returns 500 numbers unless told otherwise, so the script reads 1,000 at a time until a page comes back short. Add -CapabilitiesContain UserAssignment to keep only numbers that can be given to people, or -ActivationState Activated to leave out numbers still being set up. AssignmentBlockedState needs module version 7.5.0 or later; Install-Module installs the latest.

Check a single number

Reconnect with Connect-MicrosoftTeams, then read 1 number. The main export above disconnects when it finishes.

# Run while connected to Microsoft Teams. Replace the example number.
Get-CsPhoneNumberAssignment -TelephoneNumber '+61255550100' |
    Select-Object TelephoneNumber, PstnAssignmentStatus, AssignedPstnTargetId, ActivationState

PstnAssignmentStatus says what holds the number: Unassigned, UserAssigned, ConferenceAssigned, VoiceApplicationAssigned, ThirdPartyAppAssigned or PolicyAssigned.

Option 2

Review unassigned numbers in the admin centre

1. Sign in to the Microsoft Teams admin centre for the correct tenant.
2. Go to Voice > Phone numbers.
3. Select the filter icon on the Assignment status column and choose Unassigned.
4. For more detail, use the Filter pane to narrow the list by activation state, number type or location.
5. Read the rows. Edit and Change usage are for changing a number, so use only the list.

This suits a quick look at a tenant you already have open. For a list to keep and compare, use PowerShell or Altivane.

Common questions

Why is a number I expect not on the list?

It is probably assigned to something other than a person. A number held by a conference bridge, a voice app such as an auto attendant or call queue, or a policy has its own status and is not unassigned. A Direct Routing number is missing until you upload it to the tenant's number inventory.

Why does an unassigned number say it is blocked?

An assignment block stops the number being given to anyone. AssignmentBlockedState is BlockedForever or BlockedUntil, and BlockedUntil clears itself on the date in AssignmentBlockedUntil. To lift a block early, an administrator runs Remove-CsPhoneNumberAssignmentBlock for that number.

What about people with Teams Phone but no number?

Altivane lists those people in Teams Phone Users Without a Number, beside the unassigned numbers. For the licence side, see how to find unused licences in Microsoft 365.