Share via

PhoneNumbersClient class

Package:
@azure/communication-phone-numbers

Client class for interacting with Azure Communication Services Phone Number Administration.

Constructors

PhoneNumbersClient(string, KeyCredential, PhoneNumbersClientOptions)

Initializes a new instance of the PhoneNumberAdministrationClient class using an Azure KeyCredential.
PhoneNumbersClient(string, PhoneNumbersClientOptions)

Initializes a new instance of the PhoneNumberAdministrationClient class using a connection string.
PhoneNumbersClient(string, TokenCredential, PhoneNumbersClientOptions)

Initializes a new instance of the PhoneNumberAdministrationClient class using a TokenCredential.

Methods

beginPurchasePhoneNumbers(string, BeginPurchasePhoneNumbersOptions)

Starts the purchase of the phone number(s) in the search associated with a given id.

This function returns a Long Running Operation poller that allows you to wait indefinitely until the operation is complete.

Example usage:

import { DefaultAzureCredential } from "@azure/identity";
import {
  PhoneNumbersClient,
  SearchAvailablePhoneNumbersRequest,
} from "@azure/communication-phone-numbers";

const credential = new DefaultAzureCredential();
const client = new PhoneNumbersClient("<endpoint-from-resource>", credential);

const searchRequest: SearchAvailablePhoneNumbersRequest = {
  countryCode: "US",
  phoneNumberType: "tollFree",
  assignmentType: "application",
  capabilities: {
    sms: "outbound",
    calling: "none",
  },
  quantity: 1,
};

const searchPoller = await client.beginSearchAvailablePhoneNumbers(searchRequest);

// The search is underway. Wait to receive searchId.
const { searchId, phoneNumbers } = await searchPoller.pollUntilDone();

const purchasePoller = await client.beginPurchasePhoneNumbers(searchId);

// Purchase is underway.
await purchasePoller.pollUntilDone();
console.log(`Successfully purchased ${phoneNumbers[0]}`);
beginReleasePhoneNumber(string, BeginReleasePhoneNumberOptions)

Starts the release of a purchased phone number.

This function returns a Long Running Operation poller that allows you to wait indefinitely until the operation is complete.

Example usage:

import { DefaultAzureCredential } from "@azure/identity";
import { PhoneNumbersClient } from "@azure/communication-phone-numbers";

const credential = new DefaultAzureCredential();
const client = new PhoneNumbersClient("<endpoint-from-resource>", credential);

const phoneNumberToRelease = "<phone-number-to-release>";

const releasePoller = await client.beginReleasePhoneNumber(phoneNumberToRelease);

// Release is underway.
await releasePoller.pollUntilDone();
console.log("Successfully release phone number.");
beginReservationPurchase(string, BeginReservationPurchaseOptions)

Starts the purchase of the phone number(s) in the search associated with a given id.

This function returns a Long Running Operation poller that allows you to wait indefinitely until the operation is complete.

Example usage:

import { DefaultAzureCredential } from "@azure/identity";
import { PhoneNumbersClient } from "@azure/communication-phone-numbers";

const credential = new DefaultAzureCredential();
const client = new PhoneNumbersClient("<endpoint-from-resource>", credential);

const reservationId = "<reservation-id>";

const purchasePoller = await client.beginReservationPurchase(reservationId);

// Purchase is underway.
const purchaseResult = await purchasePoller.pollUntilDone();
console.log(`Successfully purchased phone numbers in reservation: ${reservationId}`);

Begins the purchase of the phone numbers in the reservation with the given ID.
beginSearchAvailablePhoneNumbers(SearchAvailablePhoneNumbersRequest, BeginSearchAvailablePhoneNumbersOptions)

Starts a search for phone numbers given some constraints such as name or area code. The phone numbers that are found are reserved until you cancel, purchase or the reservation expires.

This function returns a Long Running Operation poller that allows you to wait indefinitely until the operation is complete.

Example usage:

import { DefaultAzureCredential } from "@azure/identity";
import {
  PhoneNumbersClient,
  SearchAvailablePhoneNumbersRequest,
} from "@azure/communication-phone-numbers";

const credential = new DefaultAzureCredential();
const client = new PhoneNumbersClient("<endpoint-from-resource>", credential);

const searchRequest: SearchAvailablePhoneNumbersRequest = {
  countryCode: "US",
  phoneNumberType: "tollFree",
  assignmentType: "application",
  capabilities: {
    sms: "outbound",
    calling: "none",
  },
  quantity: 1,
};

const searchPoller = await client.beginSearchAvailablePhoneNumbers(searchRequest);

// The search is underway. Wait to receive searchId.
const searchResults = await searchPoller.pollUntilDone();
console.log(`Found phone number: ${searchResults.phoneNumbers[0]}`);
console.log(`searchId: ${searchResults.searchId}`);
beginUpdatePhoneNumberCapabilities(string, PhoneNumberCapabilitiesRequest, BeginUpdatePhoneNumberCapabilitiesOptions)

Starts the update of a purchased phone number's capabilities.

This function returns a Long Running Operation poller that allows you to wait indefinitely until the operation is complete.

Example usage:

import { DefaultAzureCredential } from "@azure/identity";
import {
  PhoneNumbersClient,
  PhoneNumberCapabilitiesRequest,
} from "@azure/communication-phone-numbers";

const credential = new DefaultAzureCredential();
const client = new PhoneNumbersClient("<endpoint-from-resource>", credential);

const phoneNumberToUpdate = "<phone-number-to-update>";

// This will update phone number to send and receive sms, but only send calls.
const updateRequest: PhoneNumberCapabilitiesRequest = {
  sms: "inbound+outbound",
  calling: "outbound",
};

const updatePoller = await client.beginUpdatePhoneNumberCapabilities(
  phoneNumberToUpdate,
  updateRequest,
);

// Update is underway.
const { capabilities } = await updatePoller.pollUntilDone();
console.log(`These are the update capabilities: ${capabilities}`);
browseAvailablePhoneNumbers(BrowseAvailableNumbersRequest, BrowseAvailableNumbersOptions)

Browses for available phone numbers to purchase.

Example usage:

import { DefaultAzureCredential } from "@azure/identity";
import {
  PhoneNumbersClient,
  BrowseAvailableNumbersRequest,
} from "@azure/communication-phone-numbers";

const credential = new DefaultAzureCredential();
const client = new PhoneNumbersClient("<endpoint-from-resource>", credential);

const browseAvailableNumberRequest: BrowseAvailableNumbersRequest = {
  countryCode: "US",
  phoneNumberType: "tollFree",
};
const browseAvailableNumbers = await client.browseAvailablePhoneNumbers(
  browseAvailableNumberRequest,
  {
    capabilities: {
      calling: "outbound",
    },
    assignmentType: "application",
  },
);
for (const phoneNumber of browseAvailableNumbers.phoneNumbers) {
  console.log("Found phone number: ", phoneNumber.phoneNumber);
}

Browse available phone numbers
createOrUpdateReservation(CreateOrUpdateReservationRequest, CreateOrUpdateReservationOptions)

Adds and removes phone numbers from the reservation with the given ID. The response will be the updated state of the reservation. Phone numbers can be reserved by including them in the payload. If a number is already in the reservation, it will be ignored. To remove a phone number, set it explicitly to null in the request payload. This operation is idempotent. If a reservation with the same ID already exists, it will be updated, otherwise a new one is created. Only reservations with 'active' status can be updated. Updating a reservation will extend the expiration time of the reservation to 15 minutes after the last change, up to a maximum of 2 hours from creation time. Partial success is possible, in which case the response will have a 207 status code.

Example usage:

import { DefaultAzureCredential } from "@azure/identity";
import {
  PhoneNumbersClient,
  BrowseAvailableNumbersRequest,
  AvailablePhoneNumber,
} from "@azure/communication-phone-numbers";

const credential = new DefaultAzureCredential();
const client = new PhoneNumbersClient("<endpoint-from-resource>", credential);

const browseAvailableNumberRequest: BrowseAvailableNumbersRequest = {
  countryCode: "US",
  phoneNumberType: "tollFree",
};

const browseAvailableNumbers = await client.browseAvailablePhoneNumbers(
  browseAvailableNumberRequest,
  {
    capabilities: {
      calling: "outbound",
    },
    assignmentType: "application",
  },
);
const phoneNumbers = browseAvailableNumbers.phoneNumbers;
const phoneNumbersList = [phoneNumbers[0], phoneNumbers[1]];
const reservationResponse = await client.createOrUpdateReservation(
  {
    reservationId: "reservationId",
  },
  {
    add: phoneNumbersList,
  },
);
const numbersWithError: AvailablePhoneNumber[] = [];
for (const number of Object.values(reservationResponse.phoneNumbers || {})) {
  if (number != null && number.status === "error") {
    numbersWithError.push(number);
  }
}
if (numbersWithError.length > 0) {
  console.log("Errors occurred during reservation");
} else {
  console.log("Reservation operation completed without errors.");
}

Create or update a reservation.
deleteReservation(string, DeleteReservationOptions)

Deletes a reservation by its ID..

Example usage:

import { DefaultAzureCredential } from "@azure/identity";
import { PhoneNumbersClient } from "@azure/communication-phone-numbers";

const credential = new DefaultAzureCredential();
const client = new PhoneNumbersClient("<endpoint-from-resource>", credential);

const reservationId = "<reservation-id>";
await client.deleteReservation(reservationId);

console.log(`Reservation with ID ${reservationId} has been deleted.`);

Delete a reservation.
getPurchasedPhoneNumber(string, OperationOptions)

Gets the details of a purchased phone number. Includes phone number, cost, country code, etc.
getReservation(string, GetReservationOptions)

Retrieves the reservation with the given ID, including all of the phone numbers associated with it.

Example usage:

import { DefaultAzureCredential } from "@azure/identity";
import { PhoneNumbersClient } from "@azure/communication-phone-numbers";

const credential = new DefaultAzureCredential();
const client = new PhoneNumbersClient("<endpoint-from-resource>", credential);

const reservationId = "<reservation-id>";
const reservationResponse = await client.getReservation(reservationId);

console.log(`Phone numbers in reservation: ${reservationResponse.phoneNumbers}`);

Get a reservation.
listAvailableCountries(ListAvailableCountriesOptions)

Iterates the available countries.

Example usage:

import { DefaultAzureCredential } from "@azure/identity";
import { PhoneNumbersClient } from "@azure/communication-phone-numbers";

const credential = new DefaultAzureCredential();
const client = new PhoneNumbersClient("<endpoint-from-resource>", credential);

for await (const country of client.listAvailableCountries()) {
  console.log("country: ", country.localizedName);
}

List all available countries.
listAvailableGeographicAreaCodes(string, ListGeographicAreaCodesOptions)

Iterates the available Geographic area codes.

Example usage:

import { DefaultAzureCredential } from "@azure/identity";
import { PhoneNumbersClient } from "@azure/communication-phone-numbers";

const credential = new DefaultAzureCredential();
const client = new PhoneNumbersClient("<endpoint-from-resource>", credential);

for await (const areaCodeItem of client.listAvailableGeographicAreaCodes("US")) {
  console.log("area code: ", areaCodeItem.areaCode);
}

List all available Geographic area codes.
listAvailableLocalities(string, ListLocalitiesOptions)

Iterates the available localities.

Example usage:

import { DefaultAzureCredential } from "@azure/identity";
import { PhoneNumbersClient } from "@azure/communication-phone-numbers";

const credential = new DefaultAzureCredential();
const client = new PhoneNumbersClient("<endpoint-from-resource>", credential);

for await (const locality of client.listAvailableLocalities("US")) {
  console.log("locality: ", locality.localizedName);
}

List all available localities.
listAvailableMobileAreaCodes(string, ListMobileAreaCodesOptions)

Iterates the available Mobile area codes.

Example usage:

import { DefaultAzureCredential } from "@azure/identity";
import { PhoneNumbersClient } from "@azure/communication-phone-numbers";

const credential = new DefaultAzureCredential();
const client = new PhoneNumbersClient("<endpoint-from-resource>", credential);

for await (const areaCodeItem of client.listAvailableMobileAreaCodes("IE")) {
  console.log("area code: ", areaCodeItem.areaCode);
}

List all available mobile area codes.
listAvailableOfferings(string, ListOfferingsOptions)

Iterates the available offerings.

Example usage:

import { DefaultAzureCredential } from "@azure/identity";
import { PhoneNumbersClient } from "@azure/communication-phone-numbers";

const credential = new DefaultAzureCredential();
const client = new PhoneNumbersClient("<endpoint-from-resource>", credential);

for await (const offering of client.listAvailableOfferings("US")) {
  console.log("phone number type: ", offering.phoneNumberType);
  console.log("cost: ", offering.cost.amount);
}

List all available offerings.
listAvailableTollFreeAreaCodes(string, ListTollFreeAreaCodesOptions)

Iterates the available Toll-Free area codes.

Example usage:

import { DefaultAzureCredential } from "@azure/identity";
import { PhoneNumbersClient } from "@azure/communication-phone-numbers";

const credential = new DefaultAzureCredential();
const client = new PhoneNumbersClient("<endpoint-from-resource>", credential);

for await (const areaCodeItem of client.listAvailableTollFreeAreaCodes("US")) {
  console.log("area code: ", areaCodeItem.areaCode);
}

List all available Toll-Free area codes.
listPurchasedPhoneNumbers(ListPurchasedPhoneNumbersOptions)

Iterates the purchased phone numbers.

Example usage:

import { DefaultAzureCredential } from "@azure/identity";
import { PhoneNumbersClient } from "@azure/communication-phone-numbers";

const credential = new DefaultAzureCredential();
const client = new PhoneNumbersClient("<endpoint-from-resource>", credential);

const phoneNumbers = client.listPurchasedPhoneNumbers();

for await (const phoneNumber of phoneNumbers) {
  console.log(`The id is the same as the phone number: ${phoneNumber.id}`);
  console.log(`Phone number type is ${phoneNumber.phoneNumberType}`);
}

List all purchased phone numbers.
listReservations(ListReservationOptions)

Iterates all phone number reservations.

Example usage:

import { DefaultAzureCredential } from "@azure/identity";
import { PhoneNumbersClient } from "@azure/communication-phone-numbers";

const credential = new DefaultAzureCredential();
const client = new PhoneNumbersClient("<endpoint-from-resource>", credential);

for await (const reservation of client.listReservations()) {
  console.log(`Reservation id: ${reservation.id}`);
}

List all phone number reservations. Note that the reservations will not be populated with the phone numbers associated with them.
searchOperatorInformation(string[], SearchOperatorInformationOptions)

Search for operator information about specified phone numbers.

Constructor Details

PhoneNumbersClient(string, KeyCredential, PhoneNumbersClientOptions)

Initializes a new instance of the PhoneNumberAdministrationClient class using an Azure KeyCredential.

new PhoneNumbersClient(url: string, credential: KeyCredential, options?: PhoneNumbersClientOptions)

Parameters

url

string

The endpoint of the service (eg: https://contoso.eastus.communications.azure.net)

credential
KeyCredential

An object that is used to authenticate requests to the service. Use the Azure KeyCredential or @azure/identity to create a credential.

options
PhoneNumbersClientOptions

Optional. Options to configure the HTTP pipeline.

PhoneNumbersClient(string, PhoneNumbersClientOptions)

Initializes a new instance of the PhoneNumberAdministrationClient class using a connection string.

new PhoneNumbersClient(connectionString: string, options?: PhoneNumbersClientOptions)

Parameters

connectionString

string

Connection string to connect to an Azure Communication Service resource. (eg: endpoint=https://contoso.eastus.communications.azure.net/;accesskey=secret)

options
PhoneNumbersClientOptions

Optional. Options to configure the HTTP pipeline.

PhoneNumbersClient(string, TokenCredential, PhoneNumbersClientOptions)

Initializes a new instance of the PhoneNumberAdministrationClient class using a TokenCredential.

new PhoneNumbersClient(url: string, credential: TokenCredential, options?: PhoneNumbersClientOptions)

Parameters

url

string

The endpoint of the service (ex: https://contoso.eastus.communications.azure.net).

credential
TokenCredential

TokenCredential that is used to authenticate requests to the service.

options
PhoneNumbersClientOptions

Optional. Options to configure the HTTP pipeline.

Method Details

beginPurchasePhoneNumbers(string, BeginPurchasePhoneNumbersOptions)

Starts the purchase of the phone number(s) in the search associated with a given id.

This function returns a Long Running Operation poller that allows you to wait indefinitely until the operation is complete.

Example usage:

import { DefaultAzureCredential } from "@azure/identity";
import {
  PhoneNumbersClient,
  SearchAvailablePhoneNumbersRequest,
} from "@azure/communication-phone-numbers";

const credential = new DefaultAzureCredential();
const client = new PhoneNumbersClient("<endpoint-from-resource>", credential);

const searchRequest: SearchAvailablePhoneNumbersRequest = {
  countryCode: "US",
  phoneNumberType: "tollFree",
  assignmentType: "application",
  capabilities: {
    sms: "outbound",
    calling: "none",
  },
  quantity: 1,
};

const searchPoller = await client.beginSearchAvailablePhoneNumbers(searchRequest);

// The search is underway. Wait to receive searchId.
const { searchId, phoneNumbers } = await searchPoller.pollUntilDone();

const purchasePoller = await client.beginPurchasePhoneNumbers(searchId);

// Purchase is underway.
await purchasePoller.pollUntilDone();
console.log(`Successfully purchased ${phoneNumbers[0]}`);

function beginPurchasePhoneNumbers(searchId: string, options?: BeginPurchasePhoneNumbersOptions): Promise<PollerLike<PollOperationState<PurchasePhoneNumbersResult>, PurchasePhoneNumbersResult>>

Parameters

searchId

string

The id of the search to purchase. Returned from beginSearchAvailablePhoneNumbers

options
BeginPurchasePhoneNumbersOptions

Additional request options.

Returns

Promise<PollerLike<@azure/core-lro.PollOperationState<PurchasePhoneNumbersResult>, PurchasePhoneNumbersResult>>

beginReleasePhoneNumber(string, BeginReleasePhoneNumberOptions)

Starts the release of a purchased phone number.

This function returns a Long Running Operation poller that allows you to wait indefinitely until the operation is complete.

Example usage:

import { DefaultAzureCredential } from "@azure/identity";
import { PhoneNumbersClient } from "@azure/communication-phone-numbers";

const credential = new DefaultAzureCredential();
const client = new PhoneNumbersClient("<endpoint-from-resource>", credential);

const phoneNumberToRelease = "<phone-number-to-release>";

const releasePoller = await client.beginReleasePhoneNumber(phoneNumberToRelease);

// Release is underway.
await releasePoller.pollUntilDone();
console.log("Successfully release phone number.");

function beginReleasePhoneNumber(phoneNumber: string, options?: BeginReleasePhoneNumberOptions): Promise<PollerLike<PollOperationState<ReleasePhoneNumberResult>, ReleasePhoneNumberResult>>

Parameters

phoneNumber

string

The E.164 formatted phone number being released. The leading plus can be either + or encoded as %2B.

options
BeginReleasePhoneNumberOptions

Additional request options.

Returns

Promise<PollerLike<@azure/core-lro.PollOperationState<ReleasePhoneNumberResult>, ReleasePhoneNumberResult>>

beginReservationPurchase(string, BeginReservationPurchaseOptions)

Starts the purchase of the phone number(s) in the search associated with a given id.

This function returns a Long Running Operation poller that allows you to wait indefinitely until the operation is complete.

Example usage:

import { DefaultAzureCredential } from "@azure/identity";
import { PhoneNumbersClient } from "@azure/communication-phone-numbers";

const credential = new DefaultAzureCredential();
const client = new PhoneNumbersClient("<endpoint-from-resource>", credential);

const reservationId = "<reservation-id>";

const purchasePoller = await client.beginReservationPurchase(reservationId);

// Purchase is underway.
const purchaseResult = await purchasePoller.pollUntilDone();
console.log(`Successfully purchased phone numbers in reservation: ${reservationId}`);

Begins the purchase of the phone numbers in the reservation with the given ID.

function beginReservationPurchase(reservationId: string, options?: BeginReservationPurchaseOptions): Promise<PollerLike<PollOperationState<PurchasePhoneNumbersResult>, PurchasePhoneNumbersResult>>

Parameters

reservationId

string

The id of the reservation.

options
BeginReservationPurchaseOptions

Additional request options.

Returns

Promise<PollerLike<@azure/core-lro.PollOperationState<PurchasePhoneNumbersResult>, PurchasePhoneNumbersResult>>

beginSearchAvailablePhoneNumbers(SearchAvailablePhoneNumbersRequest, BeginSearchAvailablePhoneNumbersOptions)

Starts a search for phone numbers given some constraints such as name or area code. The phone numbers that are found are reserved until you cancel, purchase or the reservation expires.

This function returns a Long Running Operation poller that allows you to wait indefinitely until the operation is complete.

Example usage:

import { DefaultAzureCredential } from "@azure/identity";
import {
  PhoneNumbersClient,
  SearchAvailablePhoneNumbersRequest,
} from "@azure/communication-phone-numbers";

const credential = new DefaultAzureCredential();
const client = new PhoneNumbersClient("<endpoint-from-resource>", credential);

const searchRequest: SearchAvailablePhoneNumbersRequest = {
  countryCode: "US",
  phoneNumberType: "tollFree",
  assignmentType: "application",
  capabilities: {
    sms: "outbound",
    calling: "none",
  },
  quantity: 1,
};

const searchPoller = await client.beginSearchAvailablePhoneNumbers(searchRequest);

// The search is underway. Wait to receive searchId.
const searchResults = await searchPoller.pollUntilDone();
console.log(`Found phone number: ${searchResults.phoneNumbers[0]}`);
console.log(`searchId: ${searchResults.searchId}`);

function beginSearchAvailablePhoneNumbers(search: SearchAvailablePhoneNumbersRequest, options?: BeginSearchAvailablePhoneNumbersOptions): Promise<PollerLike<PollOperationState<PhoneNumberSearchResult>, PhoneNumberSearchResult>>

Parameters

search
SearchAvailablePhoneNumbersRequest

Request properties to constraint the search scope.

options
BeginSearchAvailablePhoneNumbersOptions

Additional request options.

Returns

Promise<PollerLike<@azure/core-lro.PollOperationState<PhoneNumberSearchResult>, PhoneNumberSearchResult>>

beginUpdatePhoneNumberCapabilities(string, PhoneNumberCapabilitiesRequest, BeginUpdatePhoneNumberCapabilitiesOptions)

Starts the update of a purchased phone number's capabilities.

This function returns a Long Running Operation poller that allows you to wait indefinitely until the operation is complete.

Example usage:

import { DefaultAzureCredential } from "@azure/identity";
import {
  PhoneNumbersClient,
  PhoneNumberCapabilitiesRequest,
} from "@azure/communication-phone-numbers";

const credential = new DefaultAzureCredential();
const client = new PhoneNumbersClient("<endpoint-from-resource>", credential);

const phoneNumberToUpdate = "<phone-number-to-update>";

// This will update phone number to send and receive sms, but only send calls.
const updateRequest: PhoneNumberCapabilitiesRequest = {
  sms: "inbound+outbound",
  calling: "outbound",
};

const updatePoller = await client.beginUpdatePhoneNumberCapabilities(
  phoneNumberToUpdate,
  updateRequest,
);

// Update is underway.
const { capabilities } = await updatePoller.pollUntilDone();
console.log(`These are the update capabilities: ${capabilities}`);

function beginUpdatePhoneNumberCapabilities(phoneNumber: string, request: PhoneNumberCapabilitiesRequest, options?: BeginUpdatePhoneNumberCapabilitiesOptions): Promise<PollerLike<PollOperationState<PurchasedPhoneNumber>, PurchasedPhoneNumber>>

Parameters

phoneNumber

string

The E.164 formatted phone number being updated. The leading plus can be either + or encoded as %2B.

request
PhoneNumberCapabilitiesRequest

The updated properties which will be applied to the phone number.

options
BeginUpdatePhoneNumberCapabilitiesOptions

Additional request options.

Returns

Promise<PollerLike<@azure/core-lro.PollOperationState<PurchasedPhoneNumber>, PurchasedPhoneNumber>>

browseAvailablePhoneNumbers(BrowseAvailableNumbersRequest, BrowseAvailableNumbersOptions)

Browses for available phone numbers to purchase.

Example usage:

import { DefaultAzureCredential } from "@azure/identity";
import {
  PhoneNumbersClient,
  BrowseAvailableNumbersRequest,
} from "@azure/communication-phone-numbers";

const credential = new DefaultAzureCredential();
const client = new PhoneNumbersClient("<endpoint-from-resource>", credential);

const browseAvailableNumberRequest: BrowseAvailableNumbersRequest = {
  countryCode: "US",
  phoneNumberType: "tollFree",
};
const browseAvailableNumbers = await client.browseAvailablePhoneNumbers(
  browseAvailableNumberRequest,
  {
    capabilities: {
      calling: "outbound",
    },
    assignmentType: "application",
  },
);
for (const phoneNumber of browseAvailableNumbers.phoneNumbers) {
  console.log("Found phone number: ", phoneNumber.phoneNumber);
}

Browse available phone numbers

function browseAvailablePhoneNumbers(request: BrowseAvailableNumbersRequest, options?: BrowseAvailableNumbersOptions): Promise<PhoneNumbersBrowseResult>

Parameters

request
BrowseAvailableNumbersRequest

The request parameters for browsing available phone numbers.

options
BrowseAvailableNumbersOptions

Additional request options.

Returns

Promise<PhoneNumbersBrowseResult>

createOrUpdateReservation(CreateOrUpdateReservationRequest, CreateOrUpdateReservationOptions)

Adds and removes phone numbers from the reservation with the given ID. The response will be the updated state of the reservation. Phone numbers can be reserved by including them in the payload. If a number is already in the reservation, it will be ignored. To remove a phone number, set it explicitly to null in the request payload. This operation is idempotent. If a reservation with the same ID already exists, it will be updated, otherwise a new one is created. Only reservations with 'active' status can be updated. Updating a reservation will extend the expiration time of the reservation to 15 minutes after the last change, up to a maximum of 2 hours from creation time. Partial success is possible, in which case the response will have a 207 status code.

Example usage:

import { DefaultAzureCredential } from "@azure/identity";
import {
  PhoneNumbersClient,
  BrowseAvailableNumbersRequest,
  AvailablePhoneNumber,
} from "@azure/communication-phone-numbers";

const credential = new DefaultAzureCredential();
const client = new PhoneNumbersClient("<endpoint-from-resource>", credential);

const browseAvailableNumberRequest: BrowseAvailableNumbersRequest = {
  countryCode: "US",
  phoneNumberType: "tollFree",
};

const browseAvailableNumbers = await client.browseAvailablePhoneNumbers(
  browseAvailableNumberRequest,
  {
    capabilities: {
      calling: "outbound",
    },
    assignmentType: "application",
  },
);
const phoneNumbers = browseAvailableNumbers.phoneNumbers;
const phoneNumbersList = [phoneNumbers[0], phoneNumbers[1]];
const reservationResponse = await client.createOrUpdateReservation(
  {
    reservationId: "reservationId",
  },
  {
    add: phoneNumbersList,
  },
);
const numbersWithError: AvailablePhoneNumber[] = [];
for (const number of Object.values(reservationResponse.phoneNumbers || {})) {
  if (number != null && number.status === "error") {
    numbersWithError.push(number);
  }
}
if (numbersWithError.length > 0) {
  console.log("Errors occurred during reservation");
} else {
  console.log("Reservation operation completed without errors.");
}

Create or update a reservation.

function createOrUpdateReservation(request: CreateOrUpdateReservationRequest, options?: CreateOrUpdateReservationOptions): Promise<PhoneNumbersReservation>

Parameters

request
CreateOrUpdateReservationRequest

The request parameters for creating or updating a reservation.

options
CreateOrUpdateReservationOptions

The options parameters.

Returns

Promise<PhoneNumbersReservation>

deleteReservation(string, DeleteReservationOptions)

Deletes a reservation by its ID..

Example usage:

import { DefaultAzureCredential } from "@azure/identity";
import { PhoneNumbersClient } from "@azure/communication-phone-numbers";

const credential = new DefaultAzureCredential();
const client = new PhoneNumbersClient("<endpoint-from-resource>", credential);

const reservationId = "<reservation-id>";
await client.deleteReservation(reservationId);

console.log(`Reservation with ID ${reservationId} has been deleted.`);

Delete a reservation.

function deleteReservation(reservationId: string, options?: DeleteReservationOptions): Promise<void>

Parameters

reservationId

string

The id of the reservation.

options
DeleteReservationOptions

Additional request options.

Returns

Promise<void>

getPurchasedPhoneNumber(string, OperationOptions)

Gets the details of a purchased phone number. Includes phone number, cost, country code, etc.

function getPurchasedPhoneNumber(phoneNumber: string, options?: OperationOptions): Promise<PurchasedPhoneNumber>

Parameters

phoneNumber

string

The E.164 formatted phone number being fetched. The leading plus can be either + or encoded as %2B.

options
OperationOptions

Additional request options.

Returns

Promise<PurchasedPhoneNumber>

getReservation(string, GetReservationOptions)

Retrieves the reservation with the given ID, including all of the phone numbers associated with it.

Example usage:

import { DefaultAzureCredential } from "@azure/identity";
import { PhoneNumbersClient } from "@azure/communication-phone-numbers";

const credential = new DefaultAzureCredential();
const client = new PhoneNumbersClient("<endpoint-from-resource>", credential);

const reservationId = "<reservation-id>";
const reservationResponse = await client.getReservation(reservationId);

console.log(`Phone numbers in reservation: ${reservationResponse.phoneNumbers}`);

Get a reservation.

function getReservation(reservationId: string, options?: GetReservationOptions): Promise<PhoneNumbersReservation>

Parameters

reservationId

string

The id of the reservation.

options
GetReservationOptions

Additional request options.

Returns

Promise<PhoneNumbersReservation>

listAvailableCountries(ListAvailableCountriesOptions)

Iterates the available countries.

Example usage:

import { DefaultAzureCredential } from "@azure/identity";
import { PhoneNumbersClient } from "@azure/communication-phone-numbers";

const credential = new DefaultAzureCredential();
const client = new PhoneNumbersClient("<endpoint-from-resource>", credential);

for await (const country of client.listAvailableCountries()) {
  console.log("country: ", country.localizedName);
}

List all available countries.

function listAvailableCountries(options?: ListAvailableCountriesOptions): PagedAsyncIterableIterator<PhoneNumberCountry, PhoneNumberCountry[], PageSettings>

Parameters

options
ListAvailableCountriesOptions

The optional parameters.

Returns

PagedAsyncIterableIterator<PhoneNumberCountry, PhoneNumberCountry[], PageSettings>

listAvailableGeographicAreaCodes(string, ListGeographicAreaCodesOptions)

Iterates the available Geographic area codes.

Example usage:

import { DefaultAzureCredential } from "@azure/identity";
import { PhoneNumbersClient } from "@azure/communication-phone-numbers";

const credential = new DefaultAzureCredential();
const client = new PhoneNumbersClient("<endpoint-from-resource>", credential);

for await (const areaCodeItem of client.listAvailableGeographicAreaCodes("US")) {
  console.log("area code: ", areaCodeItem.areaCode);
}

List all available Geographic area codes.

function listAvailableGeographicAreaCodes(countryCode: string, options?: ListGeographicAreaCodesOptions): PagedAsyncIterableIterator<PhoneNumberAreaCode, PhoneNumberAreaCode[], PageSettings>

Parameters

countryCode

string

The ISO 3166-2 country code.

options
ListGeographicAreaCodesOptions

The optional parameters.

Returns

PagedAsyncIterableIterator<PhoneNumberAreaCode, PhoneNumberAreaCode[], PageSettings>

listAvailableLocalities(string, ListLocalitiesOptions)

Iterates the available localities.

Example usage:

import { DefaultAzureCredential } from "@azure/identity";
import { PhoneNumbersClient } from "@azure/communication-phone-numbers";

const credential = new DefaultAzureCredential();
const client = new PhoneNumbersClient("<endpoint-from-resource>", credential);

for await (const locality of client.listAvailableLocalities("US")) {
  console.log("locality: ", locality.localizedName);
}

List all available localities.

function listAvailableLocalities(countryCode: string, options?: ListLocalitiesOptions): PagedAsyncIterableIterator<PhoneNumberLocality, PhoneNumberLocality[], PageSettings>

Parameters

countryCode

string

The ISO 3166-2 country code.

options
ListLocalitiesOptions

The optional parameters.

Returns

PagedAsyncIterableIterator<PhoneNumberLocality, PhoneNumberLocality[], PageSettings>

listAvailableMobileAreaCodes(string, ListMobileAreaCodesOptions)

Iterates the available Mobile area codes.

Example usage:

import { DefaultAzureCredential } from "@azure/identity";
import { PhoneNumbersClient } from "@azure/communication-phone-numbers";

const credential = new DefaultAzureCredential();
const client = new PhoneNumbersClient("<endpoint-from-resource>", credential);

for await (const areaCodeItem of client.listAvailableMobileAreaCodes("IE")) {
  console.log("area code: ", areaCodeItem.areaCode);
}

List all available mobile area codes.

function listAvailableMobileAreaCodes(countryCode: string, options?: ListMobileAreaCodesOptions): PagedAsyncIterableIterator<PhoneNumberAreaCode, PhoneNumberAreaCode[], PageSettings>

Parameters

countryCode

string

The ISO 3166-2 country code.

options
ListMobileAreaCodesOptions

The optional parameters.

Returns

PagedAsyncIterableIterator<PhoneNumberAreaCode, PhoneNumberAreaCode[], PageSettings>

listAvailableOfferings(string, ListOfferingsOptions)

Iterates the available offerings.

Example usage:

import { DefaultAzureCredential } from "@azure/identity";
import { PhoneNumbersClient } from "@azure/communication-phone-numbers";

const credential = new DefaultAzureCredential();
const client = new PhoneNumbersClient("<endpoint-from-resource>", credential);

for await (const offering of client.listAvailableOfferings("US")) {
  console.log("phone number type: ", offering.phoneNumberType);
  console.log("cost: ", offering.cost.amount);
}

List all available offerings.

function listAvailableOfferings(countryCode: string, options?: ListOfferingsOptions): PagedAsyncIterableIterator<PhoneNumberOffering, PhoneNumberOffering[], PageSettings>

Parameters

countryCode

string

The ISO 3166-2 country code.

options
ListOfferingsOptions

The optional parameters.

Returns

PagedAsyncIterableIterator<PhoneNumberOffering, PhoneNumberOffering[], PageSettings>

listAvailableTollFreeAreaCodes(string, ListTollFreeAreaCodesOptions)

Iterates the available Toll-Free area codes.

Example usage:

import { DefaultAzureCredential } from "@azure/identity";
import { PhoneNumbersClient } from "@azure/communication-phone-numbers";

const credential = new DefaultAzureCredential();
const client = new PhoneNumbersClient("<endpoint-from-resource>", credential);

for await (const areaCodeItem of client.listAvailableTollFreeAreaCodes("US")) {
  console.log("area code: ", areaCodeItem.areaCode);
}

List all available Toll-Free area codes.

function listAvailableTollFreeAreaCodes(countryCode: string, options?: ListTollFreeAreaCodesOptions): PagedAsyncIterableIterator<PhoneNumberAreaCode, PhoneNumberAreaCode[], PageSettings>

Parameters

countryCode

string

The ISO 3166-2 country code.

options
ListTollFreeAreaCodesOptions

The optional parameters.

Returns

PagedAsyncIterableIterator<PhoneNumberAreaCode, PhoneNumberAreaCode[], PageSettings>

listPurchasedPhoneNumbers(ListPurchasedPhoneNumbersOptions)

Iterates the purchased phone numbers.

Example usage:

import { DefaultAzureCredential } from "@azure/identity";
import { PhoneNumbersClient } from "@azure/communication-phone-numbers";

const credential = new DefaultAzureCredential();
const client = new PhoneNumbersClient("<endpoint-from-resource>", credential);

const phoneNumbers = client.listPurchasedPhoneNumbers();

for await (const phoneNumber of phoneNumbers) {
  console.log(`The id is the same as the phone number: ${phoneNumber.id}`);
  console.log(`Phone number type is ${phoneNumber.phoneNumberType}`);
}

List all purchased phone numbers.

function listPurchasedPhoneNumbers(options?: ListPurchasedPhoneNumbersOptions): PagedAsyncIterableIterator<PurchasedPhoneNumber, PurchasedPhoneNumber[], PageSettings>

Parameters

options
ListPurchasedPhoneNumbersOptions

The optional parameters.

Returns

PagedAsyncIterableIterator<PurchasedPhoneNumber, PurchasedPhoneNumber[], PageSettings>

listReservations(ListReservationOptions)

Iterates all phone number reservations.

Example usage:

import { DefaultAzureCredential } from "@azure/identity";
import { PhoneNumbersClient } from "@azure/communication-phone-numbers";

const credential = new DefaultAzureCredential();
const client = new PhoneNumbersClient("<endpoint-from-resource>", credential);

for await (const reservation of client.listReservations()) {
  console.log(`Reservation id: ${reservation.id}`);
}

List all phone number reservations. Note that the reservations will not be populated with the phone numbers associated with them.

function listReservations(options?: ListReservationOptions): PagedAsyncIterableIterator<PhoneNumbersReservation, PhoneNumbersReservation[], PageSettings>

Parameters

options
ListReservationOptions

The optional parameters.

Returns

PagedAsyncIterableIterator<PhoneNumbersReservation, PhoneNumbersReservation[], PageSettings>

searchOperatorInformation(string[], SearchOperatorInformationOptions)

Search for operator information about specified phone numbers.

function searchOperatorInformation(phoneNumbers: string[], options?: SearchOperatorInformationOptions): Promise<OperatorInformationResult>

Parameters

phoneNumbers

string[]

The phone numbers to search.

options
SearchOperatorInformationOptions

Additional request options.

Returns

Promise<OperatorInformationResult>