Phone Numbers - Search Available Phone Numbers

  • Reference
Service:
Communication
API Version:
2021-03-07

Search for available phone numbers to purchase.

POST {endpoint}/availablePhoneNumbers/countries/{countryCode}/:search?api-version=2021-03-07

URI Parameters

Name In Required Type Description
countryCode
 path True

string

The ISO 3166-2 country code, e.g. US.
endpoint
 path True

string

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

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

POST https://resourcename.communication.azure.com//availablePhoneNumbers/countries/US/:search?api-version=2021-03-07

{
  "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
Response Body
{
  "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.
PhoneNumberAssignmentType

The assignment type of the phone numbers to search for. A phone number can be assigned to a person, or to an application.
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

The type of phone numbers to search for, e.g. geographic, or tollFree.

BillingFrequency

The frequency with which the cost gets billed.

Name Type Description
monthly

string

CommunicationError

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

The Communication Services error.

Name Type Description
error

CommunicationError

The Communication Services error.

PhoneNumberAssignmentType

The assignment type of the phone numbers to search for. A phone number can be assigned to a person, or to an application.

Name Type Description
application

string

person

string

PhoneNumberCapabilities

Capabilities of a phone number.

Name Type Description
calling

PhoneNumberCapabilityType

Capability value for calling.
sms

PhoneNumberCapabilityType

Capability value for SMS.

PhoneNumberCapabilityType

Capability value for calling.

Name Type Description
inbound

string

inbound+outbound

string

none

string

outbound

string

PhoneNumberCost

The incurred cost for a single phone number.

Name Type Description
amount

number

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

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

1

The quantity of desired phone numbers. The default value is 1.

PhoneNumberSearchResult

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.
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

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

The type of phone numbers to search for, e.g. geographic, or tollFree.

Name Type Description
geographic

string

tollFree

string