# Search available phone numbers

> Search for available phone numbers to purchase by country and type.

`GET https://api.zavu.dev/v1/phone-numbers/available`

Search for available phone numbers to purchase by country and type.

## Parameters

- `countryCode` (query, string, required): Two-letter ISO country code.
- `type` (query, string): Type of phone number to search for. One of: `local`, `national`, `tollFree`, `mobile`.
- `contains` (query, string): Search for numbers containing this string: digits, or letters for vanity numbers. Spaces, dashes, dots and parentheses are ignored, so `1-800` searches `1800`.
- `capabilities` (query, string): Comma-separated capabilities the number must have: `sms`, `voice`, `mms`. Numbers missing any of them are dropped.
- `limit` (query, integer): Maximum number of results to return.

## Responses

### 200

List of available phone numbers. An empty `items` means the country is served but nothing matched these filters, including a number type the country does not sell (retry with another `type`) and a `contains` pattern no number matches.

- `items` (object[], required)
  - `phoneNumber` (string, required)
  - `friendlyName` (string)
  - `locality` (string)
  - `region` (string)
  - `capabilities` (object, required)
    - `sms` (boolean)
    - `voice` (boolean)
    - `mms` (boolean)
  - `pricing` (object, required)
    - `monthlyPrice` (number): Monthly price in USD.
    - `upfrontPrice` (number): One-time purchase price in USD.
    - `isFreeEligible` (boolean): Whether this account can claim this number as the one its paid plan includes: a US or Canadian number (a +1 number) costing $20 a month or less. It depends on the account as well as the number: `false` on Free, and once the benefit has been claimed, which is once per account and never again, not even after the number is released.

### 400

Invalid query parameters, or `country_restricted`: phone numbers in this country are not sold self-service and need a minimum commitment. The message names who to contact. A `contains` pattern the inventory refused is answered `invalid_request` with `details.field` set to `contains`; one that only matched nothing is a `200` with empty `items`.

- `code` (string, required)
- `message` (string, required)
- `details` (object)

### 401

Unauthorized.

- `code` (string, required)
- `message` (string, required)
- `details` (object)

### 404

`country_unavailable`: we do not currently stock numbers in this country. Distinct from an empty `items` array, which means the country is served but nothing matched your filters — retry with another `type`.

- `code` (string, required)
- `message` (string, required)
- `details` (object)

### 502

The number inventory could not be reached, or refused a search it should accept. Retry; do not treat this as no stock.

- `code` (string, required)
- `message` (string, required)
- `details` (object)

## Example

```bash
curl -X GET "https://api.zavu.dev/v1/phone-numbers/available?countryCode=US&capabilities=voice%2Csms" \
  -H "Authorization: Bearer $ZAVUDEV_API_KEY"
```

```typescript
import Zavudev from "@zavudev/sdk";

const zavu = new Zavudev({ apiKey: process.env.ZAVUDEV_API_KEY });

const result = await zavu.phoneNumbers.searchAvailable({
  countryCode: "US",
  capabilities: "voice,sms",
});

console.log(result);
```