---
title: "Buy a Czech mobile SMS number"
method: POST
path: "/v1/sms-numbers"
---

# Buy a Czech mobile SMS number

`POST /v1/sms-numbers`

## Request

- Base URL: `https://volai.cz`
- URL: `https://volai.cz/v1/sms-numbers`
- Auth: HTTP bearer

Buys a Czech mobile SMS number for the account. Send no body; we pick the number. The number receives SMS (read them with `GET /v1/messages?direction=in` or the `message.received` webhook event) and you send from it with `fromNumber` on `POST /v1/messages`. It does not make or receive calls. 390.00 CZK excluding VAT is charged from the credit balance right away for the first 30-day period and again every 30 days; the paid period is not refunded when you release the number. An account can hold at most two SMS numbers, and buying requires a first credit top-up. If something fails at the carrier after the purchase, the number is released again and nothing is charged. While another purchase for the account is still running you get 429 `rate_limited`; wait a few seconds and repeat it. Supports `Idempotency-Key`: after a timeout send the same value so a retry cannot buy a second number. Delivery of messages from every sender, including verification codes, is not guaranteed.

## Headers

- `Idempotency-Key` string

## Response `201`

Bought SMS number

- object
  - `smsNumber` object, required
    - `number` string, required: The SMS number in E.164 format, for example +420777123456.
    - `status` 'active' | 'releasing', required: active: the number receives and sends. releasing: the release is in progress or failed and waits for a retry; send DELETE again to finish it.
    - `createdAt` number, required: When the number was bought, as a Unix epoch timestamp in milliseconds.
    - `monthlyFeeHal` number, required: Fee per 30-day period in hellers (1/100 CZK), excluding VAT, charged from the credit balance.
    - `nextChargeAt` number, required: When the next 30-day fee is due, as a Unix epoch timestamp in milliseconds.
    - `dailySendLimit` number, required: How many SMS your account may send from this number in a 24-hour window that starts with the first SMS sent from any SMS number of the account: 20 during the number's first 30 days, 50 afterwards.
    - `dailySendRemaining` number, required: How many more SMS can be sent from this number in the current window. The window is shared by all SMS numbers of the account and also counts attempts over the limit and SMS the carrier rejected. 0 for a number that is being released; sending also requires SMS numbers to be enabled for the account.
    - `dailySendResetsAt` number, nullable, required: When the current 24-hour window ends and the count starts again, as a Unix epoch timestamp in milliseconds. null when no window is running; the next SMS sent from an SMS number starts one.

## Other responses

- `401`: Error codes: unauthorized (request).
- `402`: Error codes: insufficient_credit (account), subscription_cap_reached (account).
- `403`: Error codes: account_suspended (account), sms_numbers_unavailable (account).
- `409`: Error codes: idempotency_in_progress (busy), sms_number_limit (account).
- `429`: Error codes: rate_limited (busy).
- `500`: Error codes: internal_error (service).
- `503`: Error codes: sms_number_out_of_stock (service), ledger_unavailable (service).

---

[API](https://skmtc.dev/volai/apis/volai-rest-api.md) · [All operations](https://skmtc.dev/volai/apis/volai-rest-api/llms.txt) · [OpenAPI document](https://skmtc.dev/volai/apis/volai-rest-api/revisions/12029b05e2fa?raw)