Skip to content

Phone Number Management (.NET)¶

The Phone Numbers SDK is useful when you need to provision numbers for SMS, voice, or call automation.

Setup¶

using Azure.Communication.PhoneNumbers;

var client = new PhoneNumbersClient("endpoint=https://contoso.communication.azure.com/;accesskey=...");

Operation	Typical inputs
Search	Country, number type, capabilities
Purchase	Search id, quantity
List owned	None
Release	Phone number in E.164 format

Search for available numbers¶

var searchResponse = await client.StartSearchAvailablePhoneNumbersAsync(new PhoneNumberSearchOptions(
    countryCode: "US",
    phoneNumberType: PhoneNumberType.TollFree,
    assignmentType: PhoneNumberAssignmentType.Application,
    capabilities: new PhoneNumberCapabilities(voice: PhoneNumberCapabilityType.Outbound, sms: PhoneNumberCapabilityType.Inbound)));

var searchResult = await searchResponse.WaitForCompletionAsync();
Console.WriteLine($"Search id: {searchResult.Value.SearchId}");

Purchase numbers¶

await client.PurchasePhoneNumbersAsync(searchResult.Value.SearchId);
Console.WriteLine("Purchased numbers from the completed search.");

List owned numbers¶

await foreach (var number in client.GetPurchasedPhoneNumbersAsync())
{
    Console.WriteLine($"{number.PhoneNumber} | {number.CountryCode} | {number.PhoneNumberType}");
}

Release numbers¶

await client.ReleasePhoneNumberAsync("+18005550100");
Console.WriteLine("Number released.");

Full example¶

using Azure.Communication.PhoneNumbers;

var client = new PhoneNumbersClient(Environment.GetEnvironmentVariable("ACS_CONNECTION_STRING"));

var search = await client.StartSearchAvailablePhoneNumbersAsync(new PhoneNumberSearchOptions(
    countryCode: "US",
    phoneNumberType: PhoneNumberType.Geographic,
    assignmentType: PhoneNumberAssignmentType.Application,
    capabilities: new PhoneNumberCapabilities(
        voice: PhoneNumberCapabilityType.Outbound,
        sms: PhoneNumberCapabilityType.Inbound)));

var completed = await search.WaitForCompletionAsync();
Console.WriteLine($"Search completed: {completed.Value.SearchId}");

await client.PurchasePhoneNumbersAsync(completed.Value.SearchId);

await foreach (var phone in client.GetPurchasedPhoneNumbersAsync())
{
    Console.WriteLine(phone.PhoneNumber);
}

Operational tips¶

Release carefully

Releasing a number can be irreversible. Confirm that no live application depends on it.

See Also¶

Sources¶

https://learn.microsoft.com/azure/communication-services/quickstarts/telephony/phone-number-management
https://learn.microsoft.com/azure/communication-services/concepts/telephony/phone-numbers