Get-CsOnlineUser -Filter: find Teams users by policy, phone number or account type

Get-CsOnlineUser -Filter "PROPERTY -eq 'value'" returns only the Teams users that match a condition, evaluated by the service, instead of downloading every user and filtering with Where-Object. It is how Teams administrators find who has a given policy, phone number, voice setting or account type. The reference: "The Filter parameter uses the same filtering syntax as the Where-Object cmdlet." The cmdlet is in the MicrosoftTeams module and needs Connect-MicrosoftTeams.

Connect-MicrosoftTeams
Get-CsOnlineUser -Filter "EnterpriseVoiceEnabled -eq `$true" | Select-Object DisplayName, LineUri
Get-CsOnlineUser -Filter {LineURI -eq "tel:+14255550100"}
Get-CsOnlineUser -Filter "FeatureTypes -Contains 'PhoneSystem'"
Get-CsOnlineUser -Filter {UserPrincipalName -like "test*"} -ResultSize 50

Syntax: strings and script blocks

The parameter is a string. A script block {...} is converted to its text, so both forms work, but they quote differently: inside double quotes, escape $ as `$true; inside single quotes or a script block, write $true. Checked offline in MicrosoftTeams 8.0.0 (Windows PowerShell 5.1):

Import-Module MicrosoftTeams
$c = Get-Command Get-CsOnlineUser
"Filter type: " + $c.Parameters['Filter'].ParameterType.Name
"AccountType values: " + ([enum]::GetNames($c.Parameters['AccountType'].ParameterType) -join ', ')
try { Get-CsOnlineUser -Filter {AccountType -ne 'Guest'} -ErrorAction Stop } catch { $_.Exception.Message }

Filter type: String
AccountType values: User, ResourceAccount, Guest, SfbOnPremUser, IneligibleUser, Unknown
Session is not established, run Connect-MicrosoftTeams before requesting access token

The last line shows that the filter is sent to the service, which requires a session: without one the cmdlet stops with Session is not established, run Connect-MicrosoftTeams before requesting access token.

Useful filters from the reference

Sort with -Sort (alias -OrderBy), for example -OrderBy "DisplayName asc"; the reference notes that sorting on some attributes like LineURI can be case-sensitive.

Pitfalls

• Check the attribute first. The reference documents filtering details per attribute (for example FeatureTypes only with -Contains, from module 4.0.0). For an attribute it does not mention, test on a small -ResultSize or filter the output with Where-Object.
• Renamed attributes. Module 3.0.0 renamed several properties (ObjectId to Identity, Enabled to IsSipEnabled, FirstName to GivenName). Old scripts filtering on the old names need updating.
• Result size. -ResultSize limits how many users come back; set it while you test a filter.
• Phone numbers. Assignment is done with Set-CsPhoneNumberAssignment; a missing -PhoneNumberType there causes its own error.
• Policies. To find who has a meeting policy and change it, see Grant-CsTeamsMeetingPolicy.

FAQ