Phone Numbers - List Available Localities

Service:

Communication

API Version:

2025-06-01

Gets the list of cities or towns with available phone numbers.

GET {endpoint}/availablePhoneNumbers/countries/{countryCode}/localities?api-version=2025-06-01

With optional parameters:

GET {endpoint}/availablePhoneNumbers/countries/{countryCode}/localities?skip={skip}&maxPageSize={maxPageSize}&administrativeDivision={administrativeDivision}&api-version=2025-06-01&phoneNumberType={phoneNumberType}

URI Parameters

Name	In	Required	Type	Description
countryCode	path	True	string	The ISO 3166-2 country code, e.g. US.
endpoint	path	True	string (url)	The communication resource, for example https://resourcename.communication.azure.com
api-version	query	True	string	Version of API to invoke
administrativeDivision	query		string	An optional parameter for the name of the state or province in which to search for the area code.
maxPageSize	query		integer (int32)	An optional parameter for how many entries to return, for pagination purposes. The default value is 100.
phoneNumberType	query		PhoneNumberType	Filter by numberType, e.g. Geographic, TollFree, Mobile.
skip	query		integer (int32)	An optional parameter for how many entries to skip, for pagination purposes. The default value is 0.

Request Header

Name	Required	Type	Description
accept-language		string	The locale to display in the localized fields in the response. e.g. 'en-US'

Responses

Name	Type	Description
200 OK	PhoneNumberLocalities	Success
Other Status Codes	CommunicationErrorResponse	Failure

Examples

Get PhoneNumber Search Result

Sample request

HTTP

GET https://resourcename.communication.azure.com//availablePhoneNumbers/countries/CA/localities?api-version=2025-06-01&phoneNumberType=mobile

Sample response

Status code:

200

{
  "phoneNumberLocalities": [
    {
      "localizedName": "Vancouver",
      "administrativeDivision": {
        "localizedName": "British Columbia",
        "abbreviatedName": "BC"
      }
    },
    {
      "localizedName": "Toronto",
      "administrativeDivision": {
        "localizedName": "Ontario",
        "abbreviatedName": "ON"
      }
    }
  ]
}

Definitions

Name	Description
CommunicationError	The Communication Services error.
CommunicationErrorResponse	The Communication Services error.
PhoneNumberAdministrativeDivision	Represents an administrative division. e.g. state or province.
PhoneNumberLocalities	Represents a wrapper around a list of cities or towns.
PhoneNumberLocality	Represents a locality.
PhoneNumberType	Represents the number type of the offering.

CommunicationError

Object

The Communication Services error.

Name	Type	Description
code	string	The error code.
details	CommunicationError[]	Further details about specific errors that led to this error.
innererror	CommunicationError	The inner error if any.
message	string	The error message.
target	string	The error target.

CommunicationErrorResponse

Object

The Communication Services error.

Name	Type	Description
error	CommunicationError	The Communication Services error.

PhoneNumberAdministrativeDivision

Object

Represents an administrative division. e.g. state or province.

Name	Type	Description
abbreviatedName	string	Represents the abbreviated name of the administrative division of the locality. e.g. state or province abbreviation such as WA (Washington).
localizedName	string	Represents the localized name of the administrative division of the locality. e.g. state or province localized name.

PhoneNumberLocalities

Object

Represents a wrapper around a list of cities or towns.

Name	Type	Description
nextLink	string	Represents the URL link to the next page.
phoneNumberLocalities	PhoneNumberLocality[]	Represents the underlying list of localities, e.g. cities or town.

PhoneNumberLocality

Object

Represents a locality.

Name	Type	Description
administrativeDivision	PhoneNumberAdministrativeDivision	Represents an administrative division. e.g. state or province.
localizedName	string	Represents the localized name of the locality.

PhoneNumberType

Enumeration

Represents the number type of the offering.

Value	Description
geographic
tollFree
mobile