---
title: "List phone numbers"
method: GET
path: "/v1/phone-numbers"
---

# List phone numbers

`GET /v1/phone-numbers`

## Request

- Base URL: `https://api.zavu.dev`
- URL: `https://api.zavu.dev/v1/phone-numbers`
- Auth: HTTP bearer

List all phone numbers owned by this project.

## Query parameters

- `status` 'active' | 'suspended' | 'pending' | 'releasing' | 'released': 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.
- `limit` integer
- `cursor` string

## Response `200`

List of phone numbers.

- object
  - `items` OwnedPhoneNumber[], required
    - `id` string, required
    - `phoneNumber` string, required
    - `name` string: Optional custom name for the phone number.
    - `capabilities` string[], required
    - `status` 'active' | 'suspended' | 'pending' | 'releasing' | 'released', 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.
    - `senderId` string: Sender ID if the phone number is assigned to a sender.
    - `pricing` OwnedPhoneNumberPricing, 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` 'approved' | 'pending_review' | 'rejected', 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.
    - `nextRenewalDate` string, date-time
    - `createdAt` string, date-time, required
    - `updatedAt` string, date-time
  - `nextCursor` string, nullable

## Other responses

- `401`: Unauthorized.

---

[API](https://skmtc.dev/zavudev/apis/zavu-unified-messaging-layer-api.md) - [All operations](https://skmtc.dev/zavudev/apis/zavu-unified-messaging-layer-api/llms.txt) - [OpenAPI document](https://skmtc.dev/zavudev/apis/zavu-unified-messaging-layer-api/revisions/75bc777b0ffb?raw)