How to Audit Teams Phone Number Inventory in PowerShell Using Get-CsOnlineTelephoneNumber

In enterprise Microsoft Teams Phone deployments, managing telephone number inventories across global offices requires ongoing visibility into allocated DID (Direct Inward Dialling) ranges, service numbers, and carrier assignments. Organizations often maintain thousands of phone numbers procured across multiple sources—including Microsoft Calling Plans, Operator Connect partners, and Direct Routing session border controllers (SBCs). Without regular auditing, organizations risk paying licensing and carrier fees for unassigned or orphaned numbers, overlooking emergency service location binding errors, or encountering number exhaustion when onboarding new personnel. Using the Microsoft Teams PowerShell module and the Get-CsOnlineTelephoneNumber cmdlet, telephony administrators can comprehensively query, filter, report, and audit their entire enterprise phone number catalog.

Understanding Teams Telephone Number Inventory Management

The Teams Phone number management framework categorizes numbers based on procurement method, assignment target, and operational capabilities. Key architectural attributes include:

• Number Types: Numbers are classified as Subscriber (assigned to individual user accounts for personal voice calling) or Service (assigned to high-capacity voice resources such as auto attendants, call queues, or audio conferencing bridges).
• Carrier Providers: Phone numbers reflect their provisioning origin: Microsoft Calling Plans, Operator Connect providers, or on-premises Direct Routing SBC routes.
• Assignment Status: Indicates whether a telephone number is actively bound to a user or resource account (Assigned) or sitting unassigned in the tenant inventory pool (Unassigned).
• Activation State: Tracks carrier provisioning milestones (e.g. Activated, PendingActivation, or PortInPending).
• Location Association: Confirms whether the telephone number is legally linked to an emergency civic address in the Teams Location Information Server (LIS) to comply with statutory E911 regulations.

Prerequisites and PowerShell Session Initialisation

Auditing tenant telephone number inventories requires the Microsoft Teams PowerShell module with the Teams Administrator, Global Administrator, or Teams Communications Support Engineer role assigned in Microsoft Entra ID.

Install or verify the latest Microsoft Teams module version:

Get-Module -ListAvailable -Name MicrosoftTeams
Install-Module -Name MicrosoftTeams -Scope CurrentUser -Repository PSGallery -Force

Establish an authenticated remote management session:

Connect-MicrosoftTeams

Confirm the connection by verifying cmdlet availability:

Get-Command Get-CsOnlineTelephoneNumber

Retrieving Complete Tenant Telephone Number Inventory

To inspect all telephone numbers provisioned across your tenant regardless of carrier or assignment state, execute Get-CsOnlineTelephoneNumber:

Get-CsOnlineTelephoneNumber

In large global tenants with hundreds or thousands of numbers, format the output to display key diagnostic attributes in a clean tabular view:

Get-CsOnlineTelephoneNumber | Select-Object Id, TelephoneNumber, NumberType, ActivationState, AssignmentStatus, OperatorId | Format-Table -AutoSize

To count the total number of telephone numbers in tenant inventory:

(Get-CsOnlineTelephoneNumber).Count

Filtering for Unassigned Telephone Numbers (Capacity Auditing)

A primary responsibility of voice engineers is monitoring available number stock to support rapid employee onboarding and preventing wasted monthly subscription fees on unused numbers.

Query exclusively for unassigned telephone numbers currently available in your tenant pool:

Get-CsOnlineTelephoneNumber -Filter {AssignmentStatus -eq "Unassigned"} | Format-Table TelephoneNumber, NumberType, City, IsoCountryCode

Count available unassigned numbers by city and regional area code:

Get-CsOnlineTelephoneNumber -Filter {AssignmentStatus -eq "Unassigned"} | Group-Object -Property City | Select-Object Name, Count | Sort-Object Count -Descending

Auditing Numbers Assigned to Specific Services or Users

When triaging call delivery issues or tracking organizational resource accounts, administrators can filter numbers by assignment target.

To find all service numbers assigned to automated voice applications (auto attendants and call queues):

Get-CsOnlineTelephoneNumber -Filter {NumberType -eq "Service"} | Select-Object TelephoneNumber, AssignmentStatus, AssignedElementId, City

To search for a specific telephone number using wildcard or partial match patterns:

Get-CsOnlineTelephoneNumber | Where-Object { $_.TelephoneNumber -like "*5550199*" } | Format-List *

To identify telephone numbers assigned to users who have left the organization or have disabled user accounts, cross-reference assigned elements against Entra ID directory status:

$AssignedNumbers = Get-CsOnlineTelephoneNumber -Filter {AssignmentStatus -eq "Assigned" -and NumberType -eq "Subscriber"}
foreach ($Num in $AssignedNumbers) {
    $User = Get-CsOnlineUser -Identity $Num.AssignedElementId -ErrorAction SilentlyContinue
    if (-not $User -or $User.AccountEnabled -eq $false) {
        [PSCustomObject]@{
            TelephoneNumber = $Num.TelephoneNumber
            UserPrincipalName = $Num.AssignedElementId
            AccountEnabled = $User.AccountEnabled
        }
    }
}

Exporting Telephone Number Inventory Reports to CSV

Telephony audits require formal reporting for executive leadership, financial billing verification, and compliance officers. PowerShell allows rapid export of the complete number inventory to a structured CSV spreadsheet.

Get-CsOnlineTelephoneNumber | Select-Object TelephoneNumber, NumberType, AssignmentStatus, AssignedElementId, ActivationState, IsoCountryCode, City, CivicAddressId, Capabilities | Export-Csv -Path "C:\Reports\Teams_Phone_Inventory_$(Get-Date -Format 'yyyyMMdd').csv" -NoTypeInformation -Encoding utf8
Write-Host "Telephone inventory report exported successfully."

Troubleshooting Stale Inventory and Porting Sync Delays

When auditing telephone numbers, keep these common administrative caveats in mind:

• Operator Connect Sync Latency: Numbers acquired or ported through Operator Connect providers may take several hours to synchronize into the Microsoft Teams Phone database after carrier confirmation. Get-CsOnlineTelephoneNumber confirms when the carrier has committed the numbers to tenant inventory.
• Unreleased Reserved Numbers: If numbers were reserved in the Teams Admin Center or via telephone number orders but never assigned, they may show as pending. To release numbers back to Microsoft Calling Plan pools, use the Teams Admin Center or number order release workflows.
• Civic Address Association: Regulatory frameworks require all subscriber numbers to map to a valid emergency civic address. Audit numbers lacking a valid CivicAddressId:

  Get-CsOnlineTelephoneNumber | Where-Object { [string]::IsNullOrEmpty($_.CivicAddressId) } | Select-Object TelephoneNumber, City, AssignmentStatus

By regularly auditing phone numbers using Get-CsOnlineTelephoneNumber in PowerShell, telephony administrators maintain complete control over carrier resources, minimize licensing overhead, and ensure regulatory emergency calling compliance across Microsoft Teams.