# PhoneNumbersClient API

> PhoneNumbersClient API on Apizie: 20 endpoints (Gets the list of available area codes., Gets the list of supported countries., Browses for available phone numbers to purchase., Gets the list of cities or towns with available phone numbers., …) returned as clean JSON through one API key. Send your own provider key in the x-upstream-key header. Call it over REST at https://zieapi.vercel.app/v1/cloud:azure-communication-phone-numbers/{endpoint} or from Claude, ChatGPT and Cursor through the Apizie MCP server. Free plan: 1,000 requests a month.

- Project key: `cloud:azure-communication-phone-numbers`
- Category: Cloud
- Status: byok
- Source: https://learn.microsoft.com/rest/api/azure/
- Page: https://zieapi.vercel.app/api/cloud/azure-communication-phone-numbers
- OpenAPI: https://zieapi.vercel.app/api/cloud/azure-communication-phone-numbers/openapi.json

The phone numbers client uses Azure Communication Services to purchase and manage phone numbers.

## Endpoints

### Gets the list of available area codes.
`GET https://zieapi.vercel.app/v1/cloud:azure-communication-phone-numbers/phone-numbers-list-area-codes` (byok)

| Parameter | Type | Required | Description |
|---|---|---|---|
| endpoint | string | yes | The communication resource, for example https://resourcename.communication.azure.com |
| countryCode | string | yes | The ISO 3166-2 country code, e.g. US. |
| phoneNumberType | string | yes | Filter by numberType, e.g. Geographic, TollFree, Mobile. |
| skip | integer | no | An optional parameter for how many entries to skip, for pagination purposes. The default value is 0. |
| maxPageSize | integer | no | An optional parameter for how many entries to return, for pagination purposes. The default value is 100. |
| assignmentType | string | no | Filter by assignmentType, e.g. Person, Application. |
| locality | string | no | The name of locality or town in which to search for the area code. This is required if the number type is Geographic. |
| administrativeDivision | string | no | The name of the state or province in which to search for the area code. |
| api-version | string | no | Version of API to invoke |
| accept-language | string | no | The locale to display in the localized fields in the response. e.g. 'en-US' |

### Gets the list of supported countries.
`GET https://zieapi.vercel.app/v1/cloud:azure-communication-phone-numbers/phone-numbers-list-available-countries` (byok)

| Parameter | Type | Required | Description |
|---|---|---|---|
| endpoint | string | yes | The communication resource, for example https://resourcename.communication.azure.com |
| skip | integer | no | An optional parameter for how many entries to skip, for pagination purposes. The default value is 0. |
| maxPageSize | integer | no | An optional parameter for how many entries to return, for pagination purposes. The default value is 100. |
| api-version | string | no | Version of API to invoke |
| accept-language | string | no | The locale to display in the localized fields in the response. e.g. 'en-US' |

### Browses for available phone numbers to purchase.
`POST https://zieapi.vercel.app/v1/cloud:azure-communication-phone-numbers/phone-numbers-browse-available-numbers` (byok)

| Parameter | Type | Required | Description |
|---|---|---|---|
| endpoint | string | yes | The communication resource, for example https://resourcename.communication.azure.com |
| api-version | string | no | Version of API to invoke |
| countryCode | string | yes | The ISO 3166-2 country code, e.g. US. |
| body | object | yes | JSON request body |

### Gets the list of cities or towns with available phone numbers.
`GET https://zieapi.vercel.app/v1/cloud:azure-communication-phone-numbers/phone-numbers-list-available-localities` (byok)

| Parameter | Type | Required | Description |
|---|---|---|---|
| endpoint | string | yes | The communication resource, for example https://resourcename.communication.azure.com |
| countryCode | string | yes | The ISO 3166-2 country code, e.g. US. |
| skip | integer | no | An optional parameter for how many entries to skip, for pagination purposes. The default value is 0. |
| maxPageSize | integer | no | An optional parameter for how many entries to return, for pagination purposes. The default value is 100. |
| administrativeDivision | string | no | An optional parameter for the name of the state or province in which to search for the area code. |
| api-version | string | no | Version of API to invoke |
| accept-language | string | no | The locale to display in the localized fields in the response. e.g. 'en-US' |
| phoneNumberType | string | no | Filter by numberType, e.g. Geographic, TollFree, Mobile. |

### List available offerings of capabilities with rates for the given country.
`GET https://zieapi.vercel.app/v1/cloud:azure-communication-phone-numbers/phone-numbers-list-offerings` (byok)

| Parameter | Type | Required | Description |
|---|---|---|---|
| endpoint | string | yes | The communication resource, for example https://resourcename.communication.azure.com |
| countryCode | string | yes | The ISO 3166-2 country code, e.g. US. |
| skip | integer | no | An optional parameter for how many entries to skip, for pagination purposes. The default value is 0. |
| maxPageSize | integer | no | An optional parameter for how many entries to return, for pagination purposes. The default value is 100. |
| phoneNumberType | string | no | Filter by numberType, e.g. Geographic, TollFree, Mobile. |
| assignmentType | string | no | Filter by assignmentType, e.g. Person, Application. |
| api-version | string | no | Version of API to invoke |
| accept-language | string | no | The locale to display in the localized fields in the response. e.g. 'en-US' |

### Lists all reservations.
`GET https://zieapi.vercel.app/v1/cloud:azure-communication-phone-numbers/phone-numbers-list-reservations` (byok)

| Parameter | Type | Required | Description |
|---|---|---|---|
| endpoint | string | yes | The communication resource, for example https://resourcename.communication.azure.com |
| api-version | string | no | Version of API to invoke |
| maxPageSize | integer | no | An optional parameter for how many entries to return, for pagination purposes. The default value is 100. |

### Gets a reservation by its ID.
`GET https://zieapi.vercel.app/v1/cloud:azure-communication-phone-numbers/phone-numbers-get-reservation` (byok)

| Parameter | Type | Required | Description |
|---|---|---|---|
| endpoint | string | yes | The communication resource, for example https://resourcename.communication.azure.com |
| api-version | string | no | Version of API to invoke |
| reservationId | string | yes | The id of the reservation. |

### Creates or updates a reservation by its ID.
`POST https://zieapi.vercel.app/v1/cloud:azure-communication-phone-numbers/phone-numbers-create-or-update-reservation` (byok)

| Parameter | Type | Required | Description |
|---|---|---|---|
| endpoint | string | yes | The communication resource, for example https://resourcename.communication.azure.com |
| api-version | string | no | Version of API to invoke |
| reservationId | string | yes | The id of the reservation. |
| body | object | yes | JSON request body |

### Deletes a reservation by its ID.
`POST https://zieapi.vercel.app/v1/cloud:azure-communication-phone-numbers/phone-numbers-delete-reservation` (byok)

| Parameter | Type | Required | Description |
|---|---|---|---|
| endpoint | string | yes | The communication resource, for example https://resourcename.communication.azure.com |
| api-version | string | no | Version of API to invoke |
| reservationId | string | yes | The id of the reservation. |

### Starts the purchase of all phone numbers in the reservation.
`POST https://zieapi.vercel.app/v1/cloud:azure-communication-phone-numbers/phone-numbers-purchase-reservation` (byok)

| Parameter | Type | Required | Description |
|---|---|---|---|
| endpoint | string | yes | The communication resource, for example https://resourcename.communication.azure.com |
| api-version | string | no | Version of API to invoke |
| reservationId | string | yes | The id of the reservation. |
| body | object | no | JSON request body |

### Search for available phone numbers to purchase.
`POST https://zieapi.vercel.app/v1/cloud:azure-communication-phone-numbers/phone-numbers-search-available-phone-numbers` (byok)

| Parameter | Type | Required | Description |
|---|---|---|---|
| endpoint | string | yes | The communication resource, for example https://resourcename.communication.azure.com |
| countryCode | string | yes | The ISO 3166-2 country code, e.g. US. |
| api-version | string | no | Version of API to invoke |
| body | object | yes | JSON request body |

### Gets a phone number search result by search id.
`GET https://zieapi.vercel.app/v1/cloud:azure-communication-phone-numbers/phone-numbers-get-search-result` (byok)

| Parameter | Type | Required | Description |
|---|---|---|---|
| endpoint | string | yes | The communication resource, for example https://resourcename.communication.azure.com |
| searchId | string | yes | The search Id. |
| api-version | string | no | Version of API to invoke |

### Purchases phone numbers.
`POST https://zieapi.vercel.app/v1/cloud:azure-communication-phone-numbers/phone-numbers-purchase-phone-numbers` (byok)

| Parameter | Type | Required | Description |
|---|---|---|---|
| endpoint | string | yes | The communication resource, for example https://resourcename.communication.azure.com |
| api-version | string | no | Version of API to invoke |
| body | object | yes | JSON request body |

### Gets an operation by its id.
`GET https://zieapi.vercel.app/v1/cloud:azure-communication-phone-numbers/phone-numbers-get-operation` (byok)

| Parameter | Type | Required | Description |
|---|---|---|---|
| endpoint | string | yes | The communication resource, for example https://resourcename.communication.azure.com |
| operationId | string | yes | The id of the operation |
| api-version | string | no | Version of API to invoke |

### Cancels an operation by its id.
`POST https://zieapi.vercel.app/v1/cloud:azure-communication-phone-numbers/phone-numbers-cancel-operation` (byok)

| Parameter | Type | Required | Description |
|---|---|---|---|
| endpoint | string | yes | The communication resource, for example https://resourcename.communication.azure.com |
| operationId | string | yes | The id of the operation |
| api-version | string | no | Version of API to invoke |

### Updates the capabilities of a phone number.
`POST https://zieapi.vercel.app/v1/cloud:azure-communication-phone-numbers/phone-numbers-update-capabilities` (byok)

| Parameter | Type | Required | Description |
|---|---|---|---|
| endpoint | string | yes | The communication resource, for example https://resourcename.communication.azure.com |
| phoneNumber | string | yes | The phone number id in E.164 format. The leading plus can be either + or encoded as %2B, e.g. +11234567890. |
| api-version | string | no | Version of API to invoke |
| body | object | no | JSON request body |

### Gets the details of the given purchased phone number.
`GET https://zieapi.vercel.app/v1/cloud:azure-communication-phone-numbers/phone-numbers-get-by-number` (byok)

| Parameter | Type | Required | Description |
|---|---|---|---|
| endpoint | string | yes | The communication resource, for example https://resourcename.communication.azure.com |
| phoneNumber | string | yes | The purchased phone number whose details are to be fetched in E.164 format, e.g. +11234567890. |
| api-version | string | no | Version of API to invoke |

### Releases a purchased phone number.
`POST https://zieapi.vercel.app/v1/cloud:azure-communication-phone-numbers/phone-numbers-release-phone-number` (byok)

| Parameter | Type | Required | Description |
|---|---|---|---|
| endpoint | string | yes | The communication resource, for example https://resourcename.communication.azure.com |
| phoneNumber | string | yes | Phone number to be released, e.g. +11234567890. |
| api-version | string | no | Version of API to invoke |

### Gets the list of all purchased phone numbers.
`GET https://zieapi.vercel.app/v1/cloud:azure-communication-phone-numbers/phone-numbers-list-phone-numbers` (byok)

| Parameter | Type | Required | Description |
|---|---|---|---|
| endpoint | string | yes | The communication resource, for example https://resourcename.communication.azure.com |
| skip | integer | no | An optional parameter for how many entries to skip, for pagination purposes. The default value is 0. |
| top | integer | no | An optional parameter for how many entries to return, for pagination purposes. The default value is 100. |
| api-version | string | no | Version of API to invoke |

### Searches for number format and operator information for a given list of phone numbers.
`POST https://zieapi.vercel.app/v1/cloud:azure-communication-phone-numbers/phone-numbers-operator-information-search` (byok)

| Parameter | Type | Required | Description |
|---|---|---|---|
| endpoint | string | yes | The communication resource, for example https://resourcename.communication.azure.com |
| api-version | string | no | Version of API to invoke |
| body | object | yes | JSON request body |

## Example
```
curl "https://zieapi.vercel.app/v1/cloud:azure-communication-phone-numbers/phone-numbers-list-area-codes" \
  -H "x-api-key: $APIZIE_KEY" \
  -H "x-upstream-key: $PROVIDER_KEY"
```

## FAQ

### How do I call the PhoneNumbersClient API?
Create a free Apizie key, then send GET https://zieapi.vercel.app/v1/cloud:azure-communication-phone-numbers/phone-numbers-list-area-codes with the header x-api-key. Every endpoint returns { project, data, timestamp }.

### Is the PhoneNumbersClient API free on Apizie?
Yes. The Free plan includes 1,000 requests a month at 100 requests a minute, no credit card. PhoneNumbersClient itself also needs your own key from azure.com.

### Can AI agents use the PhoneNumbersClient API?
Yes. Add the Apizie MCP server (https://zieapi.vercel.app/mcp) to Claude, ChatGPT, Cursor or VS Code, then ask in plain language. The agent calls run_scraper with project key cloud:azure-communication-phone-numbers.

### What is the status of the PhoneNumbersClient API?
Needs your own provider key (bring your own key)