How to Configure Teams Direct Routing PSTN Usages in PowerShell Using Set-CsOnlinePstnUsage

In Microsoft Teams Phone System architectures utilising Direct Routing, establishing outbound telephony calling paths requires connecting several independent routing policies and Session Border Controller (SBC) gateways. The foundational component tying these elements together is the Public Switched Telephone Network (PSTN) Usage record. PSTN Usages act as the logical bridge between Voice Routing Policies (assigned directly to end-users) and Online Voice Routes (which contain dialed number regex patterns and SBC gateway lists). Without properly configured PSTN usage records, Teams users cannot place outbound calls, as the routing engine cannot authorize matching voice routes. In the Microsoft Teams PowerShell administration module, administrators configure tenant PSTN usage records using the *-CsOnlinePstnUsage cmdlets.

Understanding Teams Direct Routing PSTN Usage Architecture

In Microsoft Teams Phone System, call authorization is governed by a three-tiered relationship:

  1. Voice Routing Policy (CsOnlineVoiceRoutingPolicy): Defines which calling classes a user is permitted to use by binding to one or more PSTN usages (e.g., “Local”, “National”, “International”, “Emergency”).
  2. PSTN Usage Record: An administrative string tag (a policy container) that exists globally within the Microsoft 365 tenant. It serves no other purpose than matching user policies with routing tables.
  3. Online Voice Route (CsOnlineVoiceRoute): Contains number patterns (regex) and SBC gateway addresses. It must be assigned the identical PSTN usage record to be evaluated for users holding that usage.

When a user dials a destination number, the Teams Phone routing engine queries the user’s voice routing policy, extracts their authorized PSTN usages, and searches exclusively for voice routes tagged with those exact same PSTN usages. If no match occurs, the call is rejected with a SIP 403 Forbidden or 404 Not Found error.

Connecting to the Microsoft Teams PowerShell Module

Managing tenant PSTN usage records requires Teams Administrator or Global Administrator privileges in Microsoft 365. Open an elevated PowerShell session and connect:

# Install Microsoft Teams module if not present
Install-Module -Name MicrosoftTeams -Force -AllowClobber

# Authenticate to Microsoft Teams tenant
Connect-MicrosoftTeams

Inspecting Existing PSTN Usages with Get-CsOnlinePstnUsage

To view all PSTN usage tags currently established within your Microsoft 365 tenant, execute:

Get-CsOnlinePstnUsage

The command outputs the complete collection of active usage strings. A representative output displays:

Identity : Global
Usage    : {Internal, Local, UK-National, International, Emergency}

Notice that the Usage property is an array of strings stored under the single Global tenant identity.

Adding New PSTN Usages with Set-CsOnlinePstnUsage

Because PSTN usages are stored as an array within the single Global identity, adding or removing usages is performed using the Set-CsOnlinePstnUsage cmdlet paired with the @{Add=...} or @{Remove=...} hash table syntax.

Example 1: Adding a Single PSTN Usage Record

To add a new dedicated usage for branch office routing (e.g., “London-Branch”):

# Append a new PSTN usage record without overwriting existing entries
Set-CsOnlinePstnUsage -Identity Global -Usage @{Add="London-Branch"}

Example 2: Adding Multiple PSTN Usage Records Simultaneously

When onboarding a new geographic region or enterprise division, add multiple records in a single administrative operation:

# Add multiple usage records for APAC operations
Set-CsOnlinePstnUsage -Identity Global `
  -Usage @{Add="APAC-Local", "APAC-National", "APAC-International"}

Verify that the new entries have appended successfully:

(Get-CsOnlinePstnUsage).Usage

Removing Obsolete PSTN Usages with Set-CsOnlinePstnUsage

Before removing a PSTN usage from the tenant, verify that it is no longer referenced in any active Online Voice Routing Policies or Online Voice Routes. If an active policy or route still references the usage string, removing it will cause routing failures for assigned users.

To remove a decommissioned usage string:

# Remove the London-Branch usage tag
Set-CsOnlinePstnUsage -Identity Global -Usage @{Remove="London-Branch"}

Binding PSTN Usages to Voice Routes and Policies

Once created, PSTN usage records must be associated with voice routes and user policies to complete the call routing triangle.

Associating PSTN Usage with a Voice Route

Assign the newly created usage to an outbound voice route targeting your primary Session Border Controllers:

# Add usage to UK National outbound voice route
Set-CsOnlineVoiceRoute -Identity "UK-National-Route" `
  -OnlinePstnUsages @{Add="UK-National"}

Associating PSTN Usage with a Voice Routing Policy

Assign the same usage to a voice routing policy granted to production users:

# Add usage to UK Standard voice routing policy
Set-CsOnlineVoiceRoutingPolicy -Identity "UK-Standard-Users" `
  -OnlinePstnUsages @{Add="UK-National"}

Auditing and Troubleshooting PSTN Routing Alignment

If an enterprise user reports an inability to dial specific destination numbers, query their assigned voice routing policy and compare its PSTN usages against matching voice routes:

$UserUPN = "[email protected]"

# Check policy assigned to user
$AssignedPolicy = (Get-CsUserPolicyAssignment -Identity $UserUPN -PolicyType TeamsVoiceRoutingPolicy).PolicyName
$PolicyUsages = (Get-CsOnlineVoiceRoutingPolicy -Identity $AssignedPolicy).OnlinePstnUsages

Write-Output "User Policy Usages: $($PolicyUsages -join ', ')"

# Verify which routes share these usages
Get-CsOnlineVoiceRoute | Where-Object {
  $route = $_
  $PolicyUsages | Where-Object { $route.OnlinePstnUsages -contains $_ }
} | Select-Object Identity, Priority, NumberPattern, OnlinePstnUsages

By leveraging PowerShell’s *-CsOnlinePstnUsage cmdlets, telecommunications administrators maintain clean, structured telephony topologies, connecting voice policies and SBC trunks seamlessly across global Microsoft Teams deployments.

Get the best tech tips delivered straight to your inbox.

Join thousands of readers mastering Apple, Google, Microsoft, and Linux.