---
title: "Search for available phone numbers to purchase."
method: POST
path: "/availablePhoneNumbers/countries/{countryCode}/:search"
tags: ["Find and purchase available phone numbers"]
---

# Search for available phone numbers to purchase.

`POST /availablePhoneNumbers/countries/{countryCode}/:search`

## Path parameters

- `countryCode` string, required

## Query parameters

- `api-version` string, required

## Request body

- PhoneNumberSearchRequest — Represents a phone number search request to find phone numbers. Found phone numbers are temporarily held for a following purchase.
  - `phoneNumberType` 'geographic' | 'tollFree' | 'mobile', required — The type of phone numbers to search for, e.g. geographic, tollFree, mobile.
  - `assignmentType` 'person' | 'application', required — 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, required — Capabilities of a phone number.
    - `calling` 'none' | 'inbound' | 'outbound' | 'inbound+outbound', required — Capability value for calling.
    - `sms` 'none' | 'inbound' | 'outbound' | 'inbound+outbound', required — Capability value for SMS.
  - `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.

## Response `202`

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.

- PhoneNumberSearchResult — The result of a phone number search operation.
  - `searchId` string, required — The search id.
  - `phoneNumbers` string[], required — The phone numbers that are available. Can be fewer than the desired search quantity.
  - `phoneNumberType` 'geographic' | 'tollFree' | 'mobile', required — The phone number's type, e.g. geographic, tollFree, mobile.
  - `assignmentType` 'person' | 'application', required — Phone number's assignment type.
  - `capabilities` PhoneNumberCapabilities, required — Capabilities of a phone number.
    - `calling` 'none' | 'inbound' | 'outbound' | 'inbound+outbound', required — Capability value for calling.
    - `sms` 'none' | 'inbound' | 'outbound' | 'inbound+outbound', required — Capability value for SMS.
  - `cost` PhoneNumberCost, required — The incurred cost for a single phone number.
    - `amount` number, double, required — The cost amount.
    - `currencyCode` string, required — The ISO 4217 currency code for the cost amount, e.g. USD.
    - `billingFrequency` 'monthly', required — The frequency with which the cost gets billed.
  - `searchExpiresBy` string, date-time, required — 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.
  - `isAgreementToNotResellRequired` boolean — Indicates if do not resell agreement is required. If true, the phone numbers cannot be acquired unless the customer provides explicit agreement to not resell them.
  - `errorCode` integer — The error code of the search.
  - `error` 'NoError' | 'UnknownErrorCode' | 'OutOfStock' | 'AuthorizationDenied' | 'MissingAddress' | 'InvalidAddress' | 'InvalidOfferModel' | 'NotEnoughLicenses' | 'NoWallet' | 'NotEnoughCredit' | 'NumbersPartiallyAcquired' | 'AllNumbersNotAcquired' | 'ReservationExpired' | 'PurchaseFailed' | 'BillingUnavailable' | 'ProvisioningFailed' | 'UnknownSearchError' — Mapping Error Messages to Codes

## Other responses

- `default` — Failure

---

[API](https://skmtc.dev/azure/apis/communication-phonenumbers.md) · [All operations](https://skmtc.dev/azure/apis/communication-phonenumbers/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/azure/communication-phonenumbers/revisions/6e81b3741aa7/schema)