Skype for Business Online – Acquiring UK Telephone Numbers with PowerShell

This article details how to acquire telephone numbers from Microsoft using PowerShell.  This is a two step process, using the following cmdlets:

  • Search-CsOnlineTelephoneNumberInventory to reserve telephone numbers that are in the inventory and available to be acquired.
  • Select-CsOnlineTelephoneNumberInventory to acquire a list of inventoried telephone numbers and associate them with a Skype for Business Online tenant.

If you need instructions on how to connect to Skype for Business Online with PowerShell, see this article.

The amount of numbers you are entitled to acquire depends on the type of telephone number (Subscriber & Service) and the license types that have been purchased and assigned.  Values for both Subscriber & Service Numbers are available in the Skype for Business Admin Center, or by using the Get-CsOnlineTelephoneNumberAvailableCount cmdlet.  By default this will return the number of available Subscriber numbers, for Service numbers use the optional InventoryType parameter.

Get-CsOnlineTelephoneNumberAvailableCount -InventoryType Service | fl Count
Count : 52
Get-CsOnlineTelephoneNumberAvailableCount -InventoryType Subscriber | fl Count
Count : 120

See ‘How many phone numbers can you get?‘ for further detail.

Step 1: Search the Telephone Number Inventory

In this example, I’m acquiring 10 x Birmingham (0121) numbers.  They are temporarily reserved for 10 minutes.

$telSearch = Search-CsOnlineTelephoneNumberInventory -InventoryType Subscriber -Region EMEA -Country GB -Area ALL -City ENG_BI -AreaCode ‘121’ -Quantity 10

InventoryType can be Service (e.g. AutoAttendants, Call Queues, Conferencing), or Subscriber (i.e. assigned to Voice Users).

Region is the target geographical region.  You can see available regions by running the following command:

Get-CsOnlineTelephoneNumberInventoryRegions -InventoryType Subscriber
RunspaceId : 10600e36-230e-47ad-9f39-f5504614cb84
Id : EMEA
DefaultName : Europe Middle East and Africa
Countries : {}
RunspaceId : 10600e36-230e-47ad-9f39-f5504614cb84
Id : NOAM
DefaultName : North America
Countries : {}

County is the target country.  You can see available countries by running the following command:

Get-CsOnlineTelephoneNumberInventoryCountries -RegionalGroup EMEA -InventoryType Subscriber
RunspaceId : 10600e36-230e-47ad-9f39-f5504614cb84
Id : ES
DefaultName : Spain
Areas : {}
RunspaceId : 10600e36-230e-47ad-9f39-f5504614cb84
Id : FR
DefaultName : France
Areas : {}
RunspaceId : 10600e36-230e-47ad-9f39-f5504614cb84
Id : GB
DefaultName : Great Britain
Areas : {}
RunspaceId : 10600e36-230e-47ad-9f39-f5504614cb84
Id : IE
DefaultName : Ireland
Areas : {}
RunspaceId : 10600e36-230e-47ad-9f39-f5504614cb84
Id : NL
DefaultName : Netherlands
Areas : {}

Area is the target geographical area.  You can see available target geographical areas by running the following command.

Get-CsOnlineTelephoneNumberInventoryAreas -RegionalGroup EMEA -CountryOrRegion GB -InventoryType Subscriber
RunspaceId : 10600e36-230e-47ad-9f39-f5504614cb84
Id : ALL
DefaultName : All

City is the target geographical city.  You can see available cities and area codes by running the following command.  

Get-CsOnlineTelephoneNumberInventoryCities -InventoryType Subscriber -RegionalGroup EMEA -CountryOrRegion GB -Area ALL

Numbers are available in 146 cities, click here for the full list.

AreaCode specifies the area code to search for telephone numbers.

Quantity specifies the quantity of telephone numbers to reserve (the maximum is 500).

Look at $telSearch:

$telSearch
RunspaceId : da589e29-c486-4e5b-8f18-f71bbc0775b4
InventoryId : Subscriber
ReservationId : b3b25b00-c7c6-4c33-9dfe-7265050f8ee2
CreatedOn : 11/09/2017 08:55:29 +00:00
ExpiresOn : 11/09/2017 09:10:29 +00:00
Reservations : {Microsoft.Rtc.Management.Hosted.Bvd.Types.NumberReservationResponseItem}

To see the temporarily reserved numbers:

$telSearch.Reservations[0].Numbers
Number               DisplayNumber
————————   ————————-
+441214960002    +44 1214960002
+441214960032    +44 1214960032
+441214960099    +44 1214960099
+441214960102    +44 1214960102
+441214960205    +44 1214960205
+441214960322    +44 1214960322
+441214960421    +44 1214960421
+441214960693    +44 1214960693
+441214960812    +44 1214960812
+441214960982    +44 1214960982

Reservation ID is required to select the numbers, so put that into a new variable.

$telSearchID = $telSearch.ReservationID

Look at $telSearchID:

$telSearchID
b3b25b00-c7c6-4c33-9dfe-7265050f8ee2

Step 2: Acquire Numbers

Now select the desired numbers into a variable ($telAssign), and assign them to Skype for Business Online so they’re available to assign to users.

To take all of the numbers:

$telAssign = $telSearch.Reservations[0].Numbers

Or to be selective, for example to take numbers ending in a zero:

$telAssign = $telSearch.Reservations[0].Numbers.DisplayNumber | ? {$_ -like ‘*0’} 

Or numbers containing a double zero:

$telAssign = $telSearch.Reservations[0].Numbers.DisplayNumber | ? {$_ -like ‘*00*’}

Or if you want to exclude certain numbers patterns, e.g. 666:

$telAssign = $telSearch.Reservations[0].Numbers.DisplayNumber | ? {$_ -notlike ‘*666*’}

Acquire the desired numbers:

Select-CsOnlineTelephoneNumberInventory -ReservationId $telSearchID -TelephoneNumbers $telAssign.Number -Region EMEA -Country GB -Area ALL -City ENG_BI

The numbers are now assigned to the Skype for Business Online tenant and available for immediate assignment.  However, if you try and assign a number to a voice user you’ll get the following error: An emergency location is required for a user with the location GB. Please add location ID of a location that is available in the tenant location list.”

This is because every active phone number must be associated with an emergency address, this applies to numbers acquired from Microsoft and ported numbers.  

Run Get-CsOnlineLisLocation to return information on previously defined locations in the Location Information Service (LIS).  For the relevant LIS entry select the LocationID attribute value.

Get-CsOnlineLisLocation
RunspaceId : c5a30c0c-0c9a-47ac-a197-aacdcb9b3f63
TenantId : <removed>
LocationId : 12e121f1-2ebd-1ea2-1c21-bf12ad12f121
CivicAddressId : <removed>
Location :
CompanyName : X500
CompanyTaxId :
HouseNumber : 1
HouseNumberSuffix :
PreDirectional :
StreetName : The Avenue
StreetSuffix :
PostDirectional :
City : Birmingham
CityAlias :
PostalCode : B1 1AB
StateOrProvince :
CountryOrRegion : GB
Description : X500 Birmingham
ValidationStatus : Validated
NumberOfVoiceUsers : -1
NumberOfTelephoneNumbers : 0

When assigning the telephone number to the voice user, use the LocationID parameter with the value obtained from Get-CsOnlineLisLocation.

Set-CsOnlineVoiceUser -Identity steve.bush@x500.co.uk -TelephoneNumber  +441214960099 -LocationID 12e121f1-2ebd-1ea2-1c21-bf12ad12f121

For more information on assigning telephone numbers to users via PowerShell, see this article.

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out /  Change )

Google+ photo

You are commenting using your Google+ account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s