Phone Numbers - Search Available Phone Numbers

Service:

Communication

API Version:

2025-02-11

Search for available phone numbers to purchase.

POST {endpoint}/availablePhoneNumbers/countries/{countryCode}/:search?api-version=2025-02-11

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

Request Body

Name	Required	Type	Description
assignmentType	True	PhoneNumberAssignmentType	The assignment type of the phone numbers to search for. A phone number can be assigned to a person, or to an application.
capabilities	True	PhoneNumberCapabilities	Capabilities of a phone number.
phoneNumberType	True	PhoneNumberType	The type of phone numbers to search for, e.g. geographic, or tollFree.
areaCode		string	The area code of the desired phone number, e.g. 425.
quantity		integer (int32) minimum: 1 maximum: 2147483647	The quantity of desired phone numbers. The default value is 1.

Responses

Name	Type	Description
202 Accepted	PhoneNumberSearchResult	The service has accepted the request and will start processing later. It will return 'Accepted' immediately and include an 'Operation-Location' and 'Location' headers. Client side should further query the operation status using the URL specified in 'Operation-Location' header. When operation completes successfully query final result using URL specified in 'Location' header. Headers Location: string Operation-Location: string operation-id: string search-id: string
Other Status Codes	CommunicationErrorResponse	Failure

Examples

Search for phone numbers

Sample request

HTTP

POST https://resourcename.communication.azure.com//availablePhoneNumbers/countries/US/:search?api-version=2025-02-11

{
  "phoneNumberType": "tollFree",
  "assignmentType": "application",
  "capabilities": {
    "sms": "inbound+outbound",
    "calling": "none"
  },
  "areaCode": "425",
  "quantity": 1
}

Sample response

Status code:

202

Operation-Location: /phoneNumbers/operations/search_378ddf60-81be-452a-ba4f-613198ea6c28
Location: /availablePhoneNumbers/searchResults/378ddf60-81be-452a-ba4f-613198ea6c28
operation-id: search_378ddf60-81be-452a-ba4f-613198ea6c28
search-id: 378ddf60-81be-452a-ba4f-613198ea6c28

{
  "searchId": "378ddf60-81be-452a-ba4f-613198ea6c28",
  "phoneNumbers": [
    "+18001212121"
  ],
  "phoneNumberType": "tollFree",
  "assignmentType": "application",
  "capabilities": {
    "sms": "inbound+outbound",
    "calling": "none"
  },
  "cost": {
    "amount": 1.2,
    "currencyCode": "USD",
    "billingFrequency": "monthly"
  },
  "searchExpiresBy": "2020-11-19T16:31:49.048Z"
}

Definitions

Name	Description
BillingFrequency	The frequency with which the cost gets billed.
CommunicationError	The Communication Services error.
CommunicationErrorResponse	The Communication Services error.
Error	Mapping Error Messages to Codes
PhoneNumberAssignmentType	Represents the assignment type of the offering.
PhoneNumberCapabilities	Capabilities of a phone number.
PhoneNumberCapabilityType	Capability value for calling.
PhoneNumberCost	The incurred cost for a single phone number.
PhoneNumberSearchRequest	Represents a phone number search request to find phone numbers. Found phone numbers are temporarily held for a following purchase.
PhoneNumberSearchResult	The result of a phone number search operation.
PhoneNumberType	Represents the number type of the offering.

BillingFrequency

Enumeration

The frequency with which the cost gets billed.

Value	Description
monthly

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.

Error

Enumeration

Mapping Error Messages to Codes

Value	Description
AllNumbersNotAcquired
AuthorizationDenied
BillingUnavailable
InvalidAddress
InvalidOfferModel
MissingAddress
NoError
NoWallet
NotEnoughCredit
NotEnoughLicenses
NumbersPartiallyAcquired
OutOfStock
ProvisioningFailed
PurchaseFailed
ReservationExpired
UnknownErrorCode
UnknownSearchError

PhoneNumberAssignmentType

Enumeration

Represents the assignment type of the offering.

Value	Description
application
person

PhoneNumberCapabilities

Object

Capabilities of a phone number.

Name	Type	Description
calling	PhoneNumberCapabilityType	Capability value for calling.
sms	PhoneNumberCapabilityType	Capability value for SMS.

PhoneNumberCapabilityType

Enumeration

Capability value for calling.

Value	Description
inbound
inbound+outbound
none
outbound

PhoneNumberCost

Object

The incurred cost for a single phone number.

Name	Type	Description
amount	number (double)	The cost amount.
billingFrequency	BillingFrequency	The frequency with which the cost gets billed.
currencyCode	string	The ISO 4217 currency code for the cost amount, e.g. USD.

PhoneNumberSearchRequest

Object

Represents a phone number search request to find phone numbers. Found phone numbers are temporarily held for a following purchase.

Name	Type	Default value	Description
areaCode	string		The area code of the desired phone number, e.g. 425.
assignmentType	PhoneNumberAssignmentType		The assignment type of the phone numbers to search for. A phone number can be assigned to a person, or to an application.
capabilities	PhoneNumberCapabilities		Capabilities of a phone number.
phoneNumberType	PhoneNumberType		The type of phone numbers to search for, e.g. geographic, or tollFree.
quantity	integer (int32) minimum: 1 maximum: 2147483647	1	The quantity of desired phone numbers. The default value is 1.

PhoneNumberSearchResult

Object

The result of a phone number search operation.

Name	Type	Description
assignmentType	PhoneNumberAssignmentType	Phone number's assignment type.
capabilities	PhoneNumberCapabilities	Capabilities of a phone number.
cost	PhoneNumberCost	The incurred cost for a single phone number.
error	Error	Mapping Error Messages to Codes
errorCode	integer (int32)	The error code of the search.
phoneNumberType	PhoneNumberType	The phone number's type, e.g. geographic, or tollFree.
phoneNumbers	string[]	The phone numbers that are available. Can be fewer than the desired search quantity.
searchExpiresBy	string (date-time)	The date that this search result expires and phone numbers are no longer on hold. A search result expires in less than 15min, e.g. 2020-11-19T16:31:49.048Z.
searchId	string	The search id.

PhoneNumberType

Enumeration

Represents the number type of the offering.

Value	Description
geographic
tollFree