---
title: "Browses for available phone numbers to purchase."
method: POST
path: "/availablePhoneNumbers/countries/{countryCode}/:browse"
tags: ["Browse, reserve and purchase available phone numbers"]
---

# Browses for available phone numbers to purchase.

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

Browses for available phone numbers to purchase. The response will be a randomized list of phone numbers available to purchase matching the browsing criteria. This operation is not paginated. Since the results are randomized, repeating the same request will not guarantee the same results.

## Path parameters

- `countryCode` string, required

## Query parameters

- `api-version` string, required

## Request body

- PhoneNumbersBrowseRequest — The parameters for the browse operation.
  - `phoneNumberType` 'geographic' | 'tollFree' | 'mobile', required — Represents the number type of the offering.
  - `capabilities` PhoneNumberBrowseCapabilitiesRequest — The minimum desired capabilities for the browse operation request.
    - `calling` 'none' | 'inbound' | 'outbound' | 'inbound+outbound' — Capability value for calling.
    - `sms` 'none' | 'inbound' | 'outbound' | 'inbound+outbound' — Capability value for SMS.
  - `assignmentType` 'person' | 'application' — Represents the assignment type of the offering. Also known as the use case.
  - `phoneNumberPrefixes` string[] — The phone number prefix to match. If specified, the search will be limited to phone numbers that start with the any of the given prefixes.

## Response `200`

A randomized list of phone numbers available to purchase matching the browsing criteria.

- PhoneNumbersBrowseResult — The result of a phone number browse operation.
  - `phoneNumbers` AvailablePhoneNumber[], required — The phone numbers that are available for purchase.
    - `id` string — The id of the phone number.
    - `countryCode` string, required — The ISO 3166-2 country code, e.g. US.
    - `phoneNumber` string — The phone number in E.164 format, e.g. +11234567890.
    - `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.
    - `phoneNumberType` 'geographic' | 'tollFree' | 'mobile', required — Represents the number type of the offering.
    - `assignmentType` 'person' | 'application', required — Represents the assignment type of the offering. Also known as the use case.
    - `cost` PhoneNumberCost — 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.
    - `status` 'available' | 'reserved' | 'expired' | 'error' | 'purchased' — Represents the status of the phone number. Possible values include: 'available', 'reserved', 'expired', 'error', 'purchased'.
    - `isAgreementToNotResellRequired` boolean — Indicates if do not resell agreement is required. If true, the phone number cannot be acquired unless the customer provides explicit agreement to not resell it.
    - `error` AvailablePhoneNumberError — Contains error details in case of failure when reserving, releasing or purchasing the phone number. Note that this is ignored by the service when present in requests.
      - `code` string — The error code indicating the reason why the operation performed on the phone number failed.
      - `message` string — The error message describing the failure that occurred.

## Other responses

- `default` — Failure

## Changes

- **2021-05-19** (2021-03-07) `5c6abf2b2252` — 1 breaking
  - api path removed without deprecation

[Change history](https://skmtc.dev/azure/apis/communication-phonenumbers/changes/availablePhoneNumbers/countries/:countryCode/:browse/post.md)

---

[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)