Get-CsPhoneNumberAssignment

Get-CsPhoneNumberAssignment
    [-ActivationState <String>]
    [-AssignedPstnTargetId <String>]
    [-AssignmentCategory <String>]
    [-CapabilitiesContain <String>]
    [-CivicAddressId <String>]
    [-Filter <String>]
    [-IsoCountryCode <String>]
    [-LocationId <String>]
    [-NetworkSiteId <String>]
    [-NumberType <String>]
    [-PstnAssignmentStatus <String>]
    [-Skip <Int32>]
    [-TelephoneNumber <String>]
    [-TelephoneNumberContain <String>]
    [-TelephoneNumberGreaterThan <String>]
    [-TelephoneNumberLessThan <String>]
    [-TelephoneNumberStartsWith <String>]
    [-Top <Int32>]
    [-Break]
    [-HttpPipelineAppend <SendAsyncStep[]>]
    [-HttpPipelinePrepend <SendAsyncStep[]>]
    [-Proxy <Uri>]
    [-ProxyCredential <PSCredential>]
    [-ProxyUseDefaultCredentials]
    [<CommonParameters>]

This cmdlet displays information about one or more phone numbers. You can filter the phone numbers to return by using different parameters. Returned results are sorted by TelephoneNumber in ascending order.

The following attributes are supported for the Filter parameter:

• TelephoneNumber
• OperatorId
• PstnAssignmentStatus (also supported AssignmentStatus)
• ActivationState
• IsoCountryCode
• Capability (also supported AcquiredCapabilities)
• IsOperatorConnect
• PstnPartnerName (also supported PartnerName)
• LocationId
• CivicAddressId
• NetworkSiteId
• NumberType
• AssignedPstnTargetId (also supported TargetId)
• TargetType
• AssignmentCategory
• ResourceAccountSharedCallingPolicySupported
• SupportedCustomerActions
• ReverseNumberLookup
• RoutingOptions
• SmsActivationState
• Tags

If you are using both -Skip X and -Top Y for filtering, the returned results will first be skipped by X, and then the top Y results will be returned.

By default, this cmdlet returns a maximum of 500 results. You can return up to 1000 results by using the Top parameter. To retrieve more than 1000 results, use the Skip and Top parameters together to page through results in increments of up to 1000 numbers. To download a full list of telephone numbers acquired by the tenant, use the Export-CsAcquiredPhoneNumber cmdlet.

Get-CsPhoneNumberAssignment -TelephoneNumber +14025551234

TelephoneNumber         : +14025551234
OperatorId              : 2b24d246-a9ee-428b-96bc-fb9d9a053c8d
NumberType              : CallingPlan
ActivationState         : Activated
AssignedPstnTargetId    : dc13d97b-7897-494e-bc28-6b469bf7a70e
AssignmentCategory      : Primary
Capability              : {UserAssignment}
City                    : Omaha
CivicAddressId          : 703b30e5-dbdd-4132-9809-4c6160a6acc7
IsoCountryCode          : US
IsoSubdivision          : Nebraska
LocationId              : 407c17ae-8c41-431e-894a-38787c682f68
LocationUpdateSupported : True
NetworkSiteId           :
PortInOrderStatus       :
PstnAssignmentStatus    : UserAssigned
PstnPartnerId           : 7fc2f2eb-89aa-41d7-93de-73d015d22ff0
PstnPartnerName         : Microsoft
NumberSource            : Online
ReverseNumberLookup		: {}
Tag						: {}
AssignmentBlockedState  :
AssignmentBlockedUntil  :
SmsActivationState      : NotActivated

This example displays information about the Microsoft Calling Plan subscriber phone number +1 (402) 555-1234. You can see that it is assigned to a user.

Get-CsPhoneNumberAssignment -TelephoneNumber "+12065551000;ext=524"

TelephoneNumber         : +12065551000;ext=524
OperatorId              : 83d289bc-a4d3-41e6-8a3f-cff260a3f091
NumberType              : DirectRouting
ActivationState         : Activated
AssignedPstnTargetId    : 2713551e-ed63-415d-9175-fc4ff825a0be
AssignmentCategory      : Primary
Capability              : {ConferenceAssignment, VoiceApplicationAssignment, UserAssignment}
City                    :
CivicAddressId          : 00000000-0000-0000-0000-000000000000
IsoCountryCode          :
IsoSubdivision          :
LocationId              : 00000000-0000-0000-0000-000000000000
LocationUpdateSupported : True
NetworkSiteId           :
PortInOrderStatus       :
PstnAssignmentStatus    : UserAssigned
PstnPartnerId           :
PstnPartnerName         :
NumberSource            : OnPremises
ReverseNumberLookup		: {}
Tag						: {}
AssignmentBlockedState  :
AssignmentBlockedUntil  :
SmsActivationState      : NotActivated

This example displays information about the Direct Routing phone number +1 (206) 555-1000;ext=524. You can see that it is assigned to a user.

Get-CsPhoneNumberAssignment -CapabilitiesContain "VoiceApplicationAssignment,ConferenceAssignment"

This example returns all phone numbers that have both the capability VoiceApplicationAssignment and the capability ConferenceAssignment assigned, but phone numbers that have only one of these capabilities assigned won't be returned.

Get-CsPhoneNumberAssignment -AssignedPstnTargetId user1@contoso.com

This example returns information about the phone number assigned to user1@contoso.com.

Get-CsPhoneNumberAssignment -AssignedPstnTargetId aa1@contoso.com

This example returns information about the phone number assigned to resource account aa1@contoso.com.

Get-CsPhoneNumberAssignment -ActivationState Activated -CapabilitiesContain VoiceApplicationAssignment -PstnAssignmentStatus Unassigned

This example returns information about all activated phone numbers with the capability VoiceApplicationAssignment that are not assigned.

Get-CsPhoneNumberAssignment -TelephoneNumberContain "524"

This example returns information about all phone numbers that contain the digits 524, including the phone number with extension 524 used in example 2.

Get-CsPhoneNumberAssignment -Skip 1000 -Top 1000

This example returns phone numbers 1001 through 2000 from the sorted results.

Get-CsPhoneNumberAssignment -AssignedPstnTargetId 'TeamsSharedCallingRoutingPolicy|Tag:SC1'

This example returns all phone numbers assigned as emergency numbers in the Teams shared calling routing policy instance SC1.

Get-CsPhoneNumberAssignment -TelephoneNumber "+12065551000;ext=524"

TelephoneNumber         : +12065551000;ext=524
OperatorId              : 83d289bc-a4d3-41e6-8a3f-cff260a6f091
NumberType              : DirectRouting
ActivationState         : Activated
AssignedPstnTargetId    : 2713551e-ed63-415d-9175-fc4ff825a0be
AssignmentCategory      : Primary
Capability              : {ConferenceAssignment, VoiceApplicationAssignment, UserAssignment}
City                    :
CivicAddressId          : 00000000-0000-0000-0000-000000000000
IsoCountryCode          :
IsoSubdivision          :
LocationId              : 00000000-0000-0000-0000-000000000000
LocationUpdateSupported : True
NetworkSiteId           :
PortInOrderStatus       :
PstnAssignmentStatus    : UserAssigned
PstnPartnerId           :
PstnPartnerName         :
NumberSource            : OnPremises
ReverseNumberLookup		: {SkipInternalVoip}
Tag						: {}
AssignmentBlockedState  :
AssignmentBlockedUntil  :
SmsActivationState      : NotActivated

This example shows a phone number where the SkipInternalVoip reverse number lookup option is enabled.

Get-CsPhoneNumberAssignment -Filter "TelephoneNumber -eq '+12065551000'"

TelephoneNumber         : +12065551000
OperatorId              : 83d289bc-a4d3-41e6-8a3f-cff260a3f091
NumberType              : DirectRouting
ActivationState         : Activated
AssignedPstnTargetId    : 2713551e-ed63-415d-9175-fc4ff825a0be
AssignmentCategory      : Primary
Capability              : {ConferenceAssignment, VoiceApplicationAssignment, UserAssignment}
City                    :
CivicAddressId          : 00000000-0000-0000-0000-000000000000
IsoCountryCode          :
IsoSubdivision          :
LocationId              : 00000000-0000-0000-0000-000000000000
LocationUpdateSupported : True
NetworkSiteId           :
PortInOrderStatus       :
PstnAssignmentStatus    : UserAssigned
PstnPartnerId           :
PstnPartnerName         :
NumberSource            : OnPremises
ReverseNumberLookup		: {}
Tag						: {}
AssignmentBlockedState  :
AssignmentBlockedUntil  :
SmsActivationState      : NotActivated

This example shows a way to use -Filter parameter to display information of a specific number.

Get-CsPhoneNumberAssignment -Filter "TelephoneNumber -like '+12065551000' -and NumberType -eq 'DirectRouting'"

TelephoneNumber         : +12065551000
OperatorId              : 83d289bc-a4d3-41e6-8a3f-cff260a3f591
NumberType              : DirectRouting
ActivationState         : Activated
AssignedPstnTargetId    : 2713551e-ed63-415d-9175-fc4ff825a0be
AssignmentCategory      : Primary
Capability              : {ConferenceAssignment, VoiceApplicationAssignment, UserAssignment}
City                    :
CivicAddressId          : 00000000-0000-0000-0000-000000000000
IsoCountryCode          :
IsoSubdivision          :
LocationId              : 00000000-0000-0000-0000-000000000000
LocationUpdateSupported : True
NetworkSiteId           :
PortInOrderStatus       :
PstnAssignmentStatus    : UserAssigned
PstnPartnerId           :
PstnPartnerName         :
NumberSource            : OnPremises
ReverseNumberLookup		: {}
Tag						: {}
AssignmentBlockedState  :
AssignmentBlockedUntil  :
SmsActivationState      : NotActivated

This example shows a way to get filtered results using multiple Filter parameters.

Get-CsPhoneNumberAssignment -Filter "Tags -contains ['Engineering']"

TelephoneNumber         : +12065551102
OperatorId              : 83d289bc-a4d3-41e6-8a3f-cff260a3f071
NumberType              : DirectRouting
ActivationState         : Activated
AssignedPstnTargetId    : 2713551e-ed63-415d-9175-fc4ff825a0be
AssignmentCategory      : Primary
Capability              : {ConferenceAssignment, VoiceApplicationAssignment, UserAssignment}
City                    :
CivicAddressId          : 00000000-0000-0000-0000-000000000000
IsoCountryCode          :
IsoSubdivision          :
LocationId              : 00000000-0000-0000-0000-000000000000
LocationUpdateSupported : True
NetworkSiteId           :
PortInOrderStatus       :
PstnAssignmentStatus    : UserAssigned
PstnPartnerId           :
PstnPartnerName         :
NumberSource            : OnPremises
ReverseNumberLookup		: {}
Tag						: {Engineering}
AssignmentBlockedState  :
AssignmentBlockedUntil  :
SmsActivationState      : NotActivated

This example shows a way to get filtered results using tags. Tags are not case sensitive.

Get-CsPhoneNumberAssignment -TelephoneNumber +14025551234

TelephoneNumber         : +14025551234
OperatorId              : 2b24d246-a9ee-428b-96bc-fb9d9a053c8d
NumberType              : CallingPlan
ActivationState         : Activated
AssignedPstnTargetId    :
AssignmentCategory      :
Capability              : {UserAssignment}
City                    : Omaha
CivicAddressId          :
IsoCountryCode          : US
IsoSubdivision          : Nebraska
LocationId              :
LocationUpdateSupported : True
NetworkSiteId           :
PortInOrderStatus       :
PstnAssignmentStatus    : Unassigned
PstnPartnerId           : 7fc2f2eb-89aa-41d7-93de-73d015d22ff0
PstnPartnerName         : Microsoft
NumberSource            : Online
ReverseNumberLookup		: {}
Tag						: {}
AssignmentBlockedState  : BlockedForever
AssignmentBlockedUntil  :
SmsActivationState      : NotActivated

This example displays information about the telephone number +1 (402) 555-1234, which has a permanent assignment block. This block prevents the number from being assigned to any other user. An admin can remove the block by using Remove-CsPhoneNumberAssignmentBlock.

Get-CsPhoneNumberAssignment -TelephoneNumber +14025551234

TelephoneNumber         : +14025551234
OperatorId              : 2b24d246-a9ee-428b-96bc-fb9d9a053c8d
NumberType              : CallingPlan
ActivationState         : Activated
AssignedPstnTargetId    :
AssignmentCategory      :
Capability              : {UserAssignment}
City                    : Omaha
CivicAddressId          :
IsoCountryCode          : US
IsoSubdivision          : Nebraska
LocationId              :
LocationUpdateSupported : True
NetworkSiteId           :
PortInOrderStatus       :
PstnAssignmentStatus    : Unassigned
PstnPartnerId           : 7fc2f2eb-89aa-41d7-93de-73d015d22ff0
PstnPartnerName         : Microsoft
NumberSource            : Online
ReverseNumberLookup		: {}
Tag						: {}
AssignmentBlockedState  : BlockedUntil
AssignmentBlockedUntil  : 2025-10-11T21:30:00.0000000Z
SmsActivationState      : NotActivated

This example displays information about the telephone number +1 (402) 555-1234, which has a temporary assignment block. This block prevents the number from being assigned to any other user. After the date and time shown in AssignmentBlockedUntil passes, the assignment block is automatically removed and the number becomes available for assignment. An admin can also remove the block manually by using Remove-CsPhoneNumberAssignmentBlock.

Get-CsPhoneNumberAssignment -TelephoneNumber +13603227351

TelephoneNumber         : +13603227351
OperatorId              : 0019adbc-b82a-47b4-a799-4e993a9982f1
NumberType              : CallingPlan
ActivationState         : Activated
AssignedPstnTargetId    : 2d43c5da-649b-406b-9d32-d130d2c53018
AssignmentCategory      : Primary
Capability              : {Geographic, InboundCalling, OutboundCalling, UserAssignment}
City                    : Marysville
CivicAddressId          : 822d4d26-2c43-460f-921c-179163b106f8
IsoCountryCode          : US
IsoSubdivision          : Washington
LocationId              : 4040949c-2424-469c-a9bc-563a5e5964f3
LocationUpdateSupported : True
NetworkSiteId           :
PortInOrderStatus       :
PstnAssignmentStatus    : UserAssigned
PstnPartnerId           : 7fc2f2eb-89aa-41d7-93de-73d015d22ff0
PstnPartnerName         : Microsoft
NumberSource            : Online
ReverseNumberLookup     : {}
Tag                     : {}
AssignmentBlockedState  : NotBlocked
AssignmentBlockedUntil  :
SmsActivationState      : Activated

This example displays information about the telephone number +1 (360) 322-7351 that is enabled for SMS.

Get-CsPhoneNumberAssignment -TelephoneNumber +13603227351

TelephoneNumber         : +13603227351
OperatorId              : 0019adbc-b82a-47b4-a799-4e993a9982f1
NumberType              : CallingPlan
ActivationState         : Activated
AssignedPstnTargetId    : 2d43c5da-649b-406b-9d32-d130d2c53018
AssignmentCategory      : Primary
Capability              : {Geographic, InboundCalling, OutboundCalling, UserAssignment}
City                    : Marysville
CivicAddressId          : 822d4d26-2c43-460f-921c-179163b106f8
IsoCountryCode          : US
IsoSubdivision          : Washington
LocationId              : 4040949c-2424-469c-a9bc-563a5e5964f3
LocationUpdateSupported : True
NetworkSiteId           :
PortInOrderStatus       :
PstnAssignmentStatus    : UserAssigned
PstnPartnerId           : 7fc2f2eb-89aa-41d7-93de-73d015d22ff0
PstnPartnerName         : Microsoft
NumberSource            : Online
ReverseNumberLookup     : {}
Tag                     : {}
AssignmentBlockedState  : NotBlocked
AssignmentBlockedUntil  :
SmsActivationState      : UpdatePending

This example displays information about the telephone number +1 (360) 322-7351 where SMS activation is pending.

Get-CsPhoneNumberAssignment -TelephoneNumber +1555555555

TelephoneNumber         : +1555555555
OperatorId              : 0019adbc-b82a-47b4-a799-4e993a9982f1
NumberType              : CallingPlan
ActivationState         : Activated
AssignedPstnTargetId    : 2d43c5da-649b-406b-9d32-d130d2c53018
AssignmentCategory      : Alternate
Capability              : {UserAssignment}
City                    : Marysville
CivicAddressId          : 822d4d26-2c43-460f-921c-179163b106f8
IsoCountryCode          : US
IsoSubdivision          : Washington
LocationId              : 4040949c-2424-469c-a9bc-563a5e5964f3
LocationUpdateSupported : True
NetworkSiteId           :
PortInOrderStatus       :
PstnAssignmentStatus    : UserAssigned
PstnPartnerId           : 7fc2f2eb-89aa-41d7-93de-73d015d22ff0
PstnPartnerName         : Microsoft
NumberSource            : Online
ReverseNumberLookup     : {}
Tag                     : {}
AssignmentBlockedState  : NotBlocked
AssignmentBlockedUntil  :
SmsActivationState      :

This example displays information about the telephone number +1 (555) 555-5555, which is assigned as an alternate number for the user. The multiline feature is in public preview.

Get-CsPhoneNumberAssignment -Filter "SmsActivationState -eq 'Activated'"

This example returns phone numbers where SMS activation is enabled.

This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutBuffer, -OutVariable, -PipelineVariable, -ProgressAction, -Verbose, -WarningAction, and -WarningVariable. For more information, see about_CommonParameters.

The activation state of the telephone number.

The ID of the object the phone number is assigned to, either the ObjectId of a user or resource account or the policy instance ID of a Teams shared calling routing policy instance.

The state of the number in terms of blocked assignment: NotBlocked if there is no assignment block on the number, BlockedForever if assignment is blocked indefinitely for the number, BlockedUntil if assignment is blocked for a specific amount of days (limited time assignment block currently not available).

The date until which assignment is blocked for the phone number. Null if the number is blocked for assignment indefinitely.

Contains the assignment category, such as Primary, Alternate, or Private.

The list of capabilities assigned to the phone number.

The city where the phone number is located.

The ID of the CivicAddress assigned to the phone number.

The ISO country code assigned to the phone number.

The subdivision within the country/region assigned to the phone number, for example, the state for US phone numbers.

The ID of the Location assigned to the phone number.

Boolean value that indicates whether updating the location assigned to the phone number is allowed.

This parameter is reserved for internal Microsoft use.

The source of the phone number. Online for phone numbers assigned in Microsoft 365 and OnPremises for phone numbers assigned in AD on-premises and synchronized into Microsoft 365.

The type of the phone number.

The ID of the operator.

The status of any port in order covering the phone number.

The assignment status of the phone number.

The ID of the PSTN partner providing the phone number.

The name of the PSTN partner.

The SMS activation state of the number.

The ID of the SMS partner.

The phone number. The number is always displayed with a prefixed "+", even if it wasn't assigned with a prefixed "+".

The object returned is of type SkypeTelephoneNumberMgmtCmdletAcquiredTelephoneNumber.

Status of Reverse Number Lookup (RNL). When it is set to SkipInternalVoip, the calls are handled through external PSTN connection instead of internal VoIP lookup.

The cmdlet is available in Teams PowerShell module 4.0.0 or later. The parameter AssignmentCategory was introduced in Teams PowerShell module 5.3.1-preview. The parameter NetworkSiteId was introduced in Teams PowerShell module 5.5.0. The output parameter NumberSource was introduced in Teams PowerShell module 5.7.0. The output parameters AssignmentBlockedState and AssignmentBlockedUntil were introduced in Teams PowerShell module 7.5.0. Multiline related cmdlets are available from Teams PowerShell module 7.6.0. The output parameter SmsActivationState was introduced in Teams PowerShell module 7.7.0.

The cmdlet is only available in commercial, GCC, GCCH and DoD cloud instances.