Get all available user numbers in Calling Plans

You can check how many numbers you have in your Teams Calling Plans. PowerShell cmdlet to use is Get-CsPhoneNumberAssignment.

Description

In the example below, we'll list all the user numbers. We're only interested in the ones, which are available to assign. Therefore, we'll filter out the numbers already assigned.

The most frequent use-case for such listing will be to find out a number, which can be assigned to a new employee.

Script

We'll use the Teams PowerShell module. Since version 2.0 the cmdlet for connecting is:

Connect-MicrosoftTeams

The cmdlet we used in the previous version of this article was Get-CsOnlineTelephoneNumber. However, that one is currently decommissioned. Its replacement is Get-CsPhoneNumberAssignment.

The set of parameters we need to use is:

$csPhoneNumberAssignmentParams = @{
  CapabilitiesContain = 'UserAssignment'
  NumberType = 'CallingPlan'
  PstnAssignmentStatus = 'Unassigned'
}
$allNumbers = Get-CsPhoneNumberAssignment @csPhoneNumberAssignmentParams

Parameters we use:

• CapabilitiesContain - in our example we're only interested in user numbers
• NumberType - we don't consider direct routing or operator connect in our example. If you're looking for non-Microsoft numbers, you'd have to update the value accordingly
• PstnAssignmentStatus - we need to assign the number afterwards. If the number was already assigned, we'd not be interested in it

Supporting more than 500 numbers

The example above will return only the first 500 numbers. If we have a larger tenancy, we'd need to consider the fact that we might have more numbers available.

The new cmdlet doesn't have a ResultSize parameter we could use. We need to run the cmdlet in a loop using Top and Skip parameters. An example of how we can do that is shown below:

$skip = 0
$allNumbers = do {
  $csPhoneNumberAssignmentParams = @{
    CapabilitiesContain = 'UserAssignment'
    NumberType = 'CallingPlan'
    PstnAssignmentStatus = 'Unassigned'
    Skip = $skip
  }
  $res = Get-CsPhoneNumberAssignment @csPhoneNumberAssignmentParams
  $skip += 500
  $res
} while ($res)

Processing data

Now we have our numbers saved into a variable. We can process them, as we need.

Few examples:

# Count by country
$allNumbers | Group-Object IsoCountryCode -NoElement

# List all numbers
$allNumbers.TelephoneNumber

# Copy all numbers to clipboard
$allNumbers.TelephoneNumber | clip