---
title: "List the caller's dedicated numbers"
method: GET
path: "/dedicated/numbers"
tags: ["Dedicated Numbers"]
---

# List the caller's dedicated numbers

`GET /dedicated/numbers`

## Request

- Base URL: `https://dashboard.voidmob.com/api/v1`
- URL: `https://dashboard.voidmob.com/api/v1/dedicated/numbers`
- Auth: HTTP bearer

Returns all dedicated numbers owned by the authenticated user, including
numbers purchased via the dashboard or the legacy US-only endpoint.
Paginated via keyset cursor on `id` (descending). Pass the returned
`next_cursor` as the `cursor` query parameter to fetch the next page.

## Query parameters

- `status` 'active' | 'expired'
- `country` string
- `limit` integer
- `cursor` string

## Response `200`

Paginated list of the caller's dedicated numbers.

- object
  - `success` true, required
  - `data` object[], required
    - `id` string, required: Dedicated number id prefixed `ded_`.
    - `display_id` string, nullable: Human-readable display id.
    - `status` 'active' | 'expired', required
    - `phone_number` string, required: Full E.164 phone number.
    - `country` string, required: Lowercase ISO-2 country code.
    - `country_name` string, required: Human-readable country name.
    - `billing_period` 'monthly', required
    - `nickname` string, nullable: User-set nickname for this number.
    - `quoted_price_cents` integer, required: Price quoted at purchase time in USD cents.
    - `charged_price_cents` integer, required: Price actually charged in USD cents.
    - `next_renewal_price_cents` integer, required: Price that will be charged on next renewal in USD cents.
    - `payment_due` PaymentDue, required: A renewal that landed before it could be paid. The term is renewed but owed; the amount is collected automatically as soon as the balance covers it. SMS received meanwhile are withheld (`content_withheld`) until it is paid, and stay withheld if the term ends unpaid.
      - `amount_cents` integer, required: Amount owed, in USD cents.
      - `since` string, date-time, required: When the renewal landed unpaid.
    - `auto_renew` boolean, required: Whether this number auto-renews at period end.
    - `created_at` string, date-time, required
    - `paid_until` string, date-time, required: Date through which the number is paid.
    - `expires_at` string, date-time, required
    - `messages` object[], required: Always empty in list responses - fetch GET /v1/dedicated/numbers/{id} for messages.
      - `id` string, required
      - `code` string, nullable
      - `text` string, nullable, required
      - `content_withheld` true
      - `received_at` string, date-time, required
  - `has_more` boolean, required: Whether there are more results after this page.
  - `next_cursor` string, nullable, required: Cursor to pass as `cursor` to fetch the next page. Null when no more pages.
  - `request_id` string, required

## Other responses

- `400`: 400 - Request failed validation.
- `401`: 401 - Authentication required.
- `429`: 429 - Rate limit exceeded. Retry after the indicated interval.

---

[API](https://skmtc.dev/voidmob/apis/voidmob-public-api.md) · [All operations](https://skmtc.dev/voidmob/apis/voidmob-public-api/llms.txt) · [OpenAPI document](https://skmtc.dev/voidmob/apis/voidmob-public-api/revisions/066023313ebe?raw)