---
title: "Purchase a dedicated phone number"
method: POST
path: "/dedicated/numbers"
tags: ["Dedicated Numbers"]
---

# Purchase a dedicated phone number

`POST /dedicated/numbers`

## Request

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

Purchase a dedicated phone number for the specified country. Requires an
`Idempotency-Key` header. If the resolved per-user price exceeds
`max_price_cents`, the server returns `PRICE_OVER_CAP` (409) without
touching your wallet - retry with a fresh key or a higher cap.

## Headers

- `Idempotency-Key` string, required

## Request body

- object
  - `country` string, required: Lowercase ISO-2 country code (e.g. "de", "us", "ca").
  - `auto_renew` boolean: Automatically renew this number at the end of each billing period.
  - `max_price_cents` integer: Optional price ceiling in cents. If the resolved per-user price is above this value the request returns PRICE_OVER_CAP (409) without charging. Defaults to the quoted price - effectively no cap.
  - `webhook_endpoint_id` string: Deliver `rental.created` to this endpoint instead of the default.

## Response `201`

Dedicated number purchased successfully.

- 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: SMS messages received on this number.
      - `id` string, required
      - `code` string, nullable
      - `text` string, nullable, required
      - `content_withheld` true
      - `received_at` string, date-time, required

## Other responses

- `400`: 400 - Request failed validation.
- `401`: 401 - Authentication required.
- `402`: 402 - Your wallet balance is too low for this purchase.
- `404`: 404 - Dedicated numbers are not available for this country.
- `409`: 409 - Current price exceeds the supplied max_price_cents.
- `429`: 429 - Rate limit exceeded. Retry after the indicated interval.
- `502`: 502 - Service error. Please retry shortly.
- `503`: 503 - This service is temporarily unavailable. Please try again shortly.
- `504`: 504 - Request timed out. Funds have been refunded.

---

[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)