Get-CsOnlineUser

Reference

Module:: MicrosoftTeamsPowerShell

Applies to:: Microsoft Teams

Returns information about users who have accounts homed on Microsoft Teams or Skype for Business Online.

Syntax

Get-CsOnlineUser
   [[-Identity] <UserIdParameter>]
   [-AccountType <String>]
   [-Filter <String>]
   [-ResultSize <Unlimited>]
   [-SkipUserPolicies]
   [-SoftDeletedUser]
   [-Sort]
   [-UsePreferredDC]
   [<CommonParameters>]

Description

The Get-CsOnlineUser cmdlet returns information about users who have accounts homed on Microsoft Teams The returned information includes standard Active Directory account information (such as the department the user works in, his or her address and phone number, etc.): the Get-CsOnlineUser cmdlet returns information about such things as whether or not the user has been enabled for Enterprise Voice and which per-user policies (if any) have been assigned to the user.

Note that the Get-CsOnlineUser cmdlet does not have a TenantId parameter; that means you cannot use a command similar to this in order to limit the returned data to users who have accounts with a specific Microsoft Teams or Skype for Business Online tenant:

Get-CsOnlineUser -TenantId "bf19b7db-6960-41e5-a139-2aa373474354"

However, if you have multiple tenants you can return users from a specified tenant by using the Filter parameter and a command similar to this:

Get-CsOnlineUser -Filter "TenantId -eq 'bf19b7db-6960-41e5-a139-2aa373474354'"

That command will limit the returned data to user accounts belong to the tenant with the TenantId "bf19b7db-6960-41e5-a139-2aa373474354". If you do not know your tenant IDs you can return that information by using this command:

Get-CsTenant

If you have a hybrid or "split domain" deployment (that is, a deployment in which some users have accounts homed on Skype for Business Online while other users have accounts homed on an on-premises version of Skype for Business Server 2015) keep in mind that the Get-CsOnlineUser cmdlet only returns information for Skype for Business Online users. However, the cmdlet will return information for both online users and on-premises users. If you want to exclude Skype for Business Online users from the data returned by the Get-CsUser cmdlet, use the following command:

Get-CsUser -Filter "TenantId -eq '00000000-0000-0000-0000-000000000000'"

By definition, users homed on the on-premises version will always have a TenantId equal to 00000000-0000-0000-0000-000000000000. Users homed on Skype for Business Online will a TenantId that is equal to some value other than 00000000-0000-0000-0000-000000000000.

Examples

-------------------------- Example 1 --------------------------

Get-CsOnlineUser

The command shown in Example 1 returns information for all the users configured as online users.

-------------------------- Example 2 --------------------------

Get-CsOnlineUser -Identity "sip:kenmyer@litwareinc.com"

In Example 2 information is returned for a single online user: the user with the SIP address "sip:kenmyer@litwareinc.com".

-------------------------- Example 3 --------------------------

Get-CsOnlineUser -Filter "ArchivingPolicy -eq 'RedmondArchiving'"

Example 3 uses the Filter parameter to limit the returned data to online users who have been assigned the per-user archiving policy RedmondArchiving.

To do this, the filter value {ArchivingPolicy -eq "RedmondArchiving"} is employed; that syntax limits returned data to users where the ArchivingPolicy property is equal to (-eq) "RedmondArchiving".

-------------------------- Example 4 --------------------------

Get-CsOnlineUser -Filter {HideFromAddressLists -eq $True}

Example 4 returns information only for user accounts that have been configured so that the account does not appear in Microsoft Exchange address lists.

(That is, the Active Directory attribute msExchHideFromAddressLists is True.) To carry out this task, the Filter parameter is included along with the filter value {HideFromAddressLists -eq $True}.

-------------------------- Example 5 --------------------------

Get-CsOnlineUser -Filter {LineURI -eq "tel:+1234"}
Get-CsOnlineUser -Filter {LineURI -eq "tel:+1234,ext:"}
Get-CsOnlineUser -Filter {LineURI -eq "1234"}

Example 5 returns information for user accounts that have been assigned a designated phone number.

-------------------------- Example 6 --------------------------

Get-CsOnlineUser -AccountType ResourceAccount

Example 6 returns information for user accounts that are categorized as resource accounts.

-------------------------- Example 7 --------------------------

Get-CsOnlineUser -Filter "FeatureTypes -Contains 'PhoneSystem'"

Example 7 returns information for user's assigned plans.

Parameters

-AccountType

This parameter is added to Get-CsOnlineUser starting from TPM 4.5.1 to indicate the user type. The possible values for the AccountType parameter are:

User - to query for user accounts.
ResourceAccount - to query for app endpoints or resource accounts.
Guest - to query for guest accounts.
SfBOnPremUser - to query for users that are hosted on-premises
IneligibleUser - to query for a user that does not have valid Teams license (except Guest, ResourceAccount and SfbOnPremUser).

Type:	UserIdParameter
Position:	1
Default value:	None
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False
Applies to:	Microsoft Teams

-Filter

Enables you to limit the returned data by filtering on specific attributes. For example, you can limit returned data to users who have been assigned a specific voice policy, or users who have not been assigned a specific voice policy.

The Filter parameter uses the same filtering syntax as the Where-Object cmdlet. For example, the following filter returns only users who have been enabled for Enterprise Voice: -Filter 'EnterpriseVoiceEnabled -eq $True' or -Filter "EnterpriseVoiceEnabled -eq `$True".

Examples:

Get-CsOnlineUser -Filter {AssignedPlan -like "MCO"}
Get-CsOnlineUser -Filter {UserPrincipalName -like "test*" -and (AssignedPlans -eq "MCOEV" -or AssignedPlans -like "MCOPSTN*")}
Get-CsOnlineUser -Filter {OnPremHostingProvider -ne $null}
Get-CsOnlineUser -Filter {WhenChanged -gt "1/25/2022 11:59:59 PM"}

Type:	String
Position:	Named
Default value:	None
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False
Applies to:	Microsoft Teams

-Identity

Indicates the Identity of the user account to be retrieved.

For TeamsOnly customers using the Teams PowerShell Module version 3.0.0 or later, you use the following values to identify the account:

GUID
SIP address
UPN
Alias

Using the Teams PowerShell Module version 2.6 or earlier only, you can use the following values to identify the account:

GUID
SIP address
UPN
Alias
Display name. Supports the asterisk ( * ) wildcard character. For example, -Identity "* Smith" returns all the users whose display names end with Smith.

Type:	UserIdParameter
Position:	1
Default value:	None
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False
Applies to:	Microsoft Teams

-ResultSize

Note: Starting with Teams PowerShell Modules version 4.0 and later, "-ResultSize" type has been changed to uint32.

Enables you to limit the number of records returned by the cmdlet. For example, to return seven users (regardless of the number of users that are in your forest) include the ResultSize parameter and set the parameter value to 7. Note that there is no way to guarantee which seven users will be returned.

The result size can be set to any whole number between 0 and 2147483647, inclusive. The value 0 returns no data. If you set the ResultSize to 7 but you have only three users in your forest, the command will return those three users, and then complete without error.

Type:	Unlimited
Position:	Named
Default value:	None
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False
Applies to:	Microsoft Teams

-SkipUserPolicies

PARAMVALUE: SwitchParameter

Type:	SwitchParameter
Position:	Named
Default value:	None
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False
Applies to:	Microsoft Teams

-SoftDeletedUser

This parameter enables you to return a collection of all the users who are deleted and can be restored within 30 days from their deletion time

Type:	SwitchParameter
Position:	Named
Default value:	None
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False
Applies to:	Microsoft Teams

-Sort

Sorting is now enabled in Teams PowerShell Module by using the "-Sort" or "-OrderBy" parameters. For example:

Get-CsOnlineUser -Filter {LineURI -like 123} -OrderBy "DisplayName asc"
Get-CsOnlineUser -Filter {DisplayName -like '*abc'} -OrderBy {DisplayName desc}

Note: Sorting on few attributes like LineURI can be case-sensitive.

Type:	String
Aliases:	OrderBy
Position:	Named
Default value:	None
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False
Applies to:	Microsoft Teams

-UsePreferredDC

Reserved for Microsoft internal use.

Type:	SwitchParameter
Position:	Named
Default value:	False
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

Outputs

Notes

A recent fix has addressed an issue where some Guest users were being omitted from the output of the Get-CsOnlineUser cmdlet, resulting in an increase in the reported user count.

Commonly used FeatureTypes and their descriptions:

Teams: Enables Users to access Teams
AudioConferencing': Enables users to call-in to Teams meetings from their phones
PhoneSystem: Enables users to place, receive, transfer, mute, unmute calls in Teams with mobile device, PC, or IP Phones
CallingPlan: Enables an All-in-the-cloud voice solution for Teams users that connects Teams Phone System to the PSTN to enable external calling. With this option, Microsoft acts as the PSTN carrier.
TeamsMultiGeo: Enables Teams chat data to be stored at rest in a specified geo location
VoiceApp: Enables to set up resource accounts to support voice applications like Auto Attendants and Call Queues
M365CopilotTeams: Enables Copilot in Teams
TeamsProMgmt: Enables enhanced meeting recap features like AI generated notes and tasks from meetings, view when a screen was shared etc
TeamsProProtection: Enables additional ways to safeguard and monitor users' Teams experiences with features like Sensitivity labels, Watermarking, end-to-end encryption etc.
TeamsProWebinar: Enables advances webinar features like engagement reports, RTMP-In, Webinar Wait List, in Teams.
TeamsProCust: Enables meeting customization features like branded meetings, together mode, in Teams.
TeamsProVirtualAppt: Enables advances virtual appointment features like SMS notifications, custom waiting room, in Teams.
TeamsRoomPro: Enables premium in-room meeting experience like intelligent audio, large galleries in Teams.
TeamsRoomBasic: Enables core meeting experience with Teams Rooms Systems.
TeamsAdvComms: Enables advances communication management like custom communication policies in Teams.
TeamsMobileExperience: Enables users to use a single phone number in Teams across both sim-enabled mobile phone and desk lines.
Conferencing_RequiresCommunicationCredits: Allows pay-per minute Audio Conferencing without monthly licenses.
CommunicationCredits: Enables users to pay Teams calling and conferencing through the credits.

Updates in Teams PowerShell Module version 6.1.1 Preview and later

The following updates are applicable for organizations that use Microsoft Teams PowerShell version 6.1.1 (Targeted Release: April 15th, 2024) or later. These changes will be gradually rolled out for all tenants starting from April 26th, 2024.

When using the Get-CsOnlineUser cmdlet in Teams PowerShell Module without the -identity parameter, we are introducing these updates:

Before the rollout, unlicensed users who did not have a valid Teams license were displayed in the output of the Get-CsOnlineUser cmdlet for 30 days after license removal. After the rollout, Get-CsOnlineUser will show unlicensed users after the initial 30 days and also include unlicensed users who never had a valid Teams license.
The AccountType value Unknown is being renamed to IneligibleUser, and will include users who do not have a valid Teams license (exceptions: Guest, SfbOnPremUser, and ResourceAccount).
You can exclude users with the AccountType as IneligibleUser from the output with the AccountType filter. For example, Get-CsOnlineUser -Filter {AccountType -ne 'IneligibleUser'}

When Get-CsOnlineUser is used with the -identity parameter, you can also use UPN, Alias, and SIP Address with the -identity parameter to obtain the information for a specific unlicensed user.

Updates in Teams PowerShell Module version 6.1.0 and later

The following updates are applicable for organizations that use Microsoft Teams PowerShell version 6.1.0 or later.

LocationPolicy: LocationPolicy attribute is being deprecated from the output of Get-CsOnlineUser in all clouds. Get-CsPhoneNumberAssignment -IsoCountryCode can be used to get the LocationPolicy information. (Note: LocationPolicy attribute will no longer be populated with value in the older Teams Powershell Module versions (<6.1.0) starting from 20th March 2024.)
OptionFlags: OptionFlags attribute will no longer be populated with value in the output of Get-CsOnlineUser in all clouds. It's important to note that other details besides EnterpriseVoiceEnabled, previously found in OptionFlags, are no longer relevant for Teams. Administrators can still utilize the EnterpriseVoiceEnabled attribute in the output of the Get-CsOnlineUser cmdlet to get this information. (Note: This change will be rolled out to all Teams Powershell Module versions (=<6.1.0) starting from 20th March 2024.)

Updates in Teams PowerShell Module version 6.0.0 and later

The following updates are applicable for organizations having TeamsOnly users that use Microsoft Teams PowerShell version 6.0.0 or later.

GracePeriodExpiryDate: GracePeriodExpiryDate attribute is being introduced within the AssignedPlan JSON array. It specifies the date when the grace period of a previously deleted license expires, and the license will be permanently deleted. The attribute remains empty/null for active licenses. (Note: The attribute is currently in private preview and will display valid values only for private preview)
IsInGracePeriod: IsInGracePeriod attribute is a boolean flag that indicates that the associated plan is in grace period after deletion. (Note: The attribute is currently in private preview and will display valid values only for private preview)

Updates in Teams PowerShell Module version 5.9.0 and later

The following updates are applicable for organizations having TeamsOnly users that use Microsoft Teams PowerShell version 5.9.0 or later in GCC High and DoD environments (note that these changes are already rolled out in commercial environments). These updates will be applicable to older Teams PowerShell versions from 15th March 2024 in GCC High and DoD environments:

The following attributes are populated with correct values in the output of Get-CsOnlineUser when not using the "-identity" parameter:

CountryAbbreviation
UserValidationErrors
WhenCreated

The following updates are applicable to the output in scenarios where "-identity" parameter is not used:

Only valid OnPrem users would be available in the output: These are users that are DirSyncEnabled and have a valid OnPremSipAddress or SIP address in ShadowProxyAddresses.
Guest are available in the output
Unlicensed Users: Unlicensed users would show up in the output of Get-CsOnlineUser (note Unlicensed users in commercial clouds would show up in the output for only 30 days post-license removal.)
Soft deleted users: These users will be displayed in the output of Get-CsOnlineUser and the TAC Manage Users page by default with SoftDeletionTimestamp set to a value.
AccountType as Unknown will be renamed to AccountType as IneligibleUser in GCC High and DoD environments. IneligibleUser will include users who do not have any valid Teams licenses (except Guest, SfbOnPremUser, ResourceAccount).

If any information is required for a user that is not available in the output (when not using "-identity" parameter) then it can be obtained using the "-identity" parameter. Information for all users would be available using the "-identity" parameter until they are hard deleted.

If Guest, Soft Deleted Users, IneligibleUser are not required in the output then they can be filtered out by using filter on AccountType and SoftDeletionTimestamp. For example:

Get-CsOnlineUser -Filter {AccountType -ne 'Guest'}
Get-CsOnlineUser -Filter {SoftDeletionTimestamp -eq $null}
Get-CsOnlineUser -Filter {AccountType -ne 'IneligibleUser'}

Updates in Teams PowerShell Module version 3.0.0 and above

The following updates are applicable for organizations having TeamsOnly users that use Microsoft Teams PowerShell version 3.0.0 and later, excluding updates mentioned previously for Teams PowerShell Module version 5.0.0:

New user attributes:

FeatureTypes: Array of unique strings specifying what features are enabled for a user. This attribute is an alternative to several attributes that have been dropped as outlined in the next section.

Some of the commonly used FeatureTypes include:

Teams
AudioConferencing
PhoneSystem
CallingPlan

Note: This attribute is now filterable in Teams PowerShell Module versions 4.0.0 and later using the "-Contains" operator as shown in Example 7.

AccountEnabled: Indicates whether a user is enabled for login in Microsoft Entra ID.

Dropped attributes:

The following attributes are no longer relevant to Teams and have been dropped from the output:

AcpInfo
AdminDescription
ArchivingPolicy
AudioVideoDisabled
BaseSimpleUrl
BroadcastMeetingPolicy
CallViaWorkPolicy
ClientPolicy
ClientUpdateOverridePolicy
ClientVersionPolicy
CloudMeetingOpsPolicy
CloudMeetingPolicy
CloudVideoInteropPolicy
ContactOptionFlags
CountryOrRegionDisplayName
Description
DistinguishedName
EnabledForRichPresence
ExchangeArchivingPolicy
ExchUserHoldPolicies
ExperiencePolicy
ExternalUserCommunicationPolicy
ExUmEnabled
Guid
HomeServer
HostedVoicemailPolicy
IPPBXSoftPhoneRoutingEnabled
IPPhone
IPPhonePolicy
IsByPassValidation
IsValid
LegalInterceptPolicy
LicenseRemovalTimestamp
LineServerURI
Manager
MNCReady
Name
NonPrimaryResource
ObjectCategory
ObjectClass
ObjectState
OnPremHideFromAddressLists
OriginalPreferredDataLocation
OriginatingServer
OriginatorSid
OverridePreferredDataLocation
PendingDeletion
PrivateLine
ProvisioningCounter
ProvisioningStamp
PublishingCounter
PublishingStamp
Puid
RemoteCallControlTelephonyEnabled
RemoteMachine
SamAccountName
ServiceInfo
StsRefreshTokensValidFrom
SubProvisioningCounter
SubProvisioningStamp
SubProvisionLineType
SyncingCounter
TargetRegistrarPool
TargetServerIfMoving
TeamsInteropPolicy
ThumbnailPhoto
UpgradeRetryCounter
UserAccountControl
UserProvisionType
UserRoutingGroupId
VoicePolicy - Alternative is the CallingPlan and PhoneSystem string in FeatureTypes
XForestMovePolicy
AddressBookPolicy
GraphPolicy
PinPolicy
PreferredDataLocationOverwritePolicy
PresencePolicy
SmsServicePolicy
TeamsVoiceRoute
ThirdPartyVideoSystemPolicy
UserServicesPolicy
ConferencingPolicy
Id
MobilityPolicy
OnlineDialinConferencingPolicy - Alternative is the AudioConferencing string in FeatureTypes
Sid
TeamsWorkLoadPolicy
VoiceRoutingPolicy
ClientUpdatePolicy
HomePhone
HostedVoiceMail
MobilePhone
OtherTelephone
StreetAddress
WebPage
AssignedLicenses
OnPremisesUserPrincipalName
HostedVoiceMail
LicenseAssignmentStates
OnPremDomainName
OnPremSecurityIdentifier
OnPremSamAccountName
CallerIdPolicy
Fax
LastName (available in Teams PowerShell Module 4.2.1 and later)
Office
Phone
WindowsEmailAddress
SoftDeletedUsers (available in Teams PowerShell Module 4.4.3 and later)

The following attributes are temporarily unavailable in the output when using the "-Filter" or when used without the "-Identity" parameter:

WhenChanged
CountryAbbreviation

Note: These attributes will be available in the near future.

Attributes renamed:

ObjectId renamed to Identity
FirstName renamed to GivenName
DirSyncEnabled renamed to UserDirSyncEnabled
MCOValidationErrors renamed to UserValidationErrors
Enabled renamed to IsSipEnabled
TeamsBranchSurvivabilityPolicy renamed to TeamsSurvivableBranchAppliancePolicy
CountryOrRegionDisplayName introduced as Country (in versions 4.2.0 and later)
InterpretedUserType: "AADConnectEnabledOnline" prefix for the InterpretedUserType output value has now been renamed DirSyncEnabledOnline, for example, AADConnectEnabledOnlineTeamsOnlyUser is now DirSyncEnabledOnlineTeamsOnlyUser.

Attributes that have changed in meaning/format:

OnPremLineURI: This attribute previously used to refer to both:

LineURI set via OnPrem AD.
Direct Routing numbers assigned to users via Set-CsUser.

In Teams PowerShell Modules 3.0.0 and above OnPremLineURI will only refer to the LineURI set via OnPrem AD. Direct Routing numbers will be available from the LineURI field. Direct Routing Numbers can be distinguished from Calling Plan Numbers by looking at the FeatureTypes attribute.

The output format of AssignedPlan and ProvisionedPlan have now changed from XML to JSON array.
The output format of Policies has now changed from String to JSON type UserPolicyDefinition.

INPUTS

NOTES

Set-CsUser

Partager via

Get-CsOnlineUser

Syntax

Description

Examples

-------------------------- Example 1 --------------------------

-------------------------- Example 2 --------------------------

-------------------------- Example 3 --------------------------

-------------------------- Example 4 --------------------------

-------------------------- Example 5 --------------------------

-------------------------- Example 6 --------------------------

-------------------------- Example 7 --------------------------

Parameters

-AccountType

-Filter

-Identity

-ResultSize

-SkipUserPolicies

-SoftDeletedUser

-Sort

-UsePreferredDC

Outputs

INPUTS

NOTES

Commentaires

Ressources supplémentaires

Partager via

Get-CsOnlineUser

Syntax

Description

Examples

-------------------------- Example 1 --------------------------

-------------------------- Example 2 --------------------------

-------------------------- Example 3 --------------------------

-------------------------- Example 4 --------------------------

-------------------------- Example 5 --------------------------

-------------------------- Example 6 --------------------------

-------------------------- Example 7 --------------------------

Parameters

-AccountType

-Filter

-Identity

-ResultSize

-SkipUserPolicies

-SoftDeletedUser

-Sort

-UsePreferredDC

Outputs

INPUTS

NOTES

RELATED LINKS

Commentaires

Ressources supplémentaires