---
title: "List the external numbers the company owns"
method: GET
path: "/api/v1/phone-numbers"
tags: ["Phone numbers"]
---

# List the external numbers the company owns

`GET /api/v1/phone-numbers`

## Request

- Base URL: `https://wardenpoint.com` (the document declares no server; this is the origin it was published from)
- URL: `https://wardenpoint.com/api/v1/phone-numbers`
- Auth: API key in header `X-API-Key`

The numbers the company already has, together with the plan quota and the credit balance the monthly charges come out of. Numbers awaiting provider confirmation and suspended ones are included — leaving them out would hide exactly the numbers that need attention. Buying is not part of this API; see the catalogue endpoints for what could be bought and the dashboard for buying it.

## Response `200`

The numbers, the quota and the balance.

- object
  - `data` PhoneNumber[]
    - `uuid` string, uuid: Stable identifier — every phone-number endpoint takes this.
    - `number` string: E.164.
    - `country_code` string, nullable
    - `city` string, nullable
    - `number_type` 'local' | 'mobile' | 'tollfree' | 'national', nullable: Kind of number, as classified when it was bought.
    - `status` 'assigned' | 'pending_purchase' | 'suspended': `assigned` — live. `pending_purchase` — the provider has not confirmed yet. `suspended` — three renewal charges in a row failed; the number no longer carries calls and cannot be made the default caller ID until it is paid for. Those three are the only ones the listing returns; the column also holds `available`, `reserved` and `retired`, which mean the number is not the company's any more.
    - `monthly_cost` number, float: Charged to the company credit balance every month while `auto_renew` is on.
    - `currency` string
    - `auto_renew` boolean: True keeps charging `monthly_cost` to the credit balance each month. False lets the number lapse at `expires_at`, after which it stops carrying calls and leaves the company.
    - `is_default` boolean: Whether outbound calls present this number. Exactly one number per company can hold it.
    - `expires_at` string, date-time, nullable: End of the paid period. With auto_renew on this is the next charge date, not a deadline; with it off, the moment the number stops working.
    - `is_expiring_soon` boolean: True within five days of expiry.
    - `renewal_failures` integer: Consecutive failed renewal charges. At three the number goes `suspended`. A non-zero value means the credit balance did not cover the charge.
    - `created_at` string, date-time
  - `meta` object
    - `limits` object
      - `max` integer, nullable: Plan cap on owned numbers. Null means the plan sets no cap.
      - `current` integer
      - `can_purchase` boolean: Whether the plan still has room for another number. Says nothing about the credit balance, and does not open buying through this API — a human buys in the dashboard.
    - `credit_balance` number, float: What monthly renewals are charged against. A balance below the sum of the monthly costs means numbers will start failing renewal.
    - `credit_currency` string
    - `fallback_caller_id` string, nullable: What outbound calls present when no owned number is marked default. Null on a deployment that has none configured.

## Other responses

- `401`: API key missing, invalid, revoked or expired.
- `403`: API key lacks the config.read ability.

---

[API](https://skmtc.dev/wardenpoint/apis/wardenpoint-api.md) · [All operations](https://skmtc.dev/wardenpoint/apis/wardenpoint-api/llms.txt) · [OpenAPI document](https://skmtc.dev/wardenpoint/apis/wardenpoint-api/revisions/259ee445728e?raw)