# List phone numbers

> List all phone numbers owned by this project.

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

List all phone numbers owned by this project.

## Parameters

- `status` (query, string): Filter by phone number status. One of: `active`, `suspended`, `pending`, `releasing`, `released`.
- `limit` (query, integer)
- `cursor` (query, string): Pagination cursor.

## Responses

### 200

List of phone numbers.

- `items` (object[], required)
  - `id` (string, required)
  - `phoneNumber` (string, required)
  - `name` (string): Optional custom name for the phone number.
  - `capabilities` (string[], required)
  - `status` (string, required): Billing state of an owned number, separate from `regulatoryStatus`. `pending` is legacy and is not written to numbers today. The SDKs carry `active`, `suspended` and `pending` only; `releasing` and `released` are returned by the REST API until their next release. One of: `active`, `suspended`, `pending`, `releasing`, `released`.
  - `senderId` (string): Sender ID if the phone number is assigned to a sender.
  - `pricing` (object, required)
    - `monthlyPrice` (number): Monthly price in USD.
    - `upfrontCost` (number): One-time purchase cost in cents.
    - `monthlyCost` (number): Monthly cost in cents.
    - `isFreeNumber` (boolean): Whether this is a free number.
  - `regulatoryStatus` (string, required): Regulatory review state. Numbers that need no review are `approved` immediately. A number bought with regulatory information is owned and billed from purchase and starts `pending_review`; it cannot send messages or place calls until this is `approved`. The state is re-checked every 6 hours: poll `GET /v1/phone-numbers/{phoneNumberId}` to follow it. Assign it to a sender with `PATCH /v1/phone-numbers/{phoneNumberId}` (`senderId`) before or after approval. A number assigned while under review is recorded and connected to that sender when it is approved; the connection is retried until it succeeds. A sender created over the API is set up for SMS as part of the assignment. `rejected` means review refused the information: the number cannot be assigned to a sender. A number that stays `pending_review` may be waiting on information the API cannot supply; contact support. One of: `approved`, `pending_review`, `rejected`.
  - `nextRenewalDate` (string<date-time>)
  - `releaseAt` (string<date-time>): When the number goes back to the carrier, if it is on its way out. Absent otherwise. - **A paid plan ended.** Without a paid plan a team keeps one number: the one chosen in the dashboard when cancelling, else the one the plan included, else the oldest it bought. That number is billed monthly from the balance and has no `releaseAt` unless a renewal fails. Every other number keeps working, unbilled, until this date, 7 days after the plan ended. Numbers you brought yourself are never released. - **A renewal could not be paid.** The number is suspended and released at the end of a 7-day grace. Paying, or returning to a paid plan, before this date keeps the number. A released number cannot be recovered.
  - `createdAt` (string<date-time>, required)
  - `updatedAt` (string<date-time>)
- `nextCursor` (string, nullable)

### 401

Unauthorized.

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

## Example

```bash
curl -X GET "https://api.zavu.dev/v1/phone-numbers" \
  -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.list();

console.log(result);
```