---
title: "Order a number from a region not in the pool"
method: POST
path: "/v1/numbers/orders"
---

# Order a number from a region not in the pool

`POST /v1/numbers/orders`

## Request

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

Orders a number from a region outside the listing (Ostrava, Plzeň, Budějovice...). Address codes must come from `GET /v1/numbers/address-options`. The endpoint waits while we set up an emergency-services address with the carrier and buy the number - usually under a minute; the finished number then comes back in the `e164` field with status `done`. If it doesn't work out on the first try, it returns the order with status `pending` and a cron job finishes it. The 25.00 CZK fee is only charged once the number is ready.

## Headers

- `Idempotency-Key` string

## Request body

- object
  - `psc` string, required: Premises postal code used to look up the address cascade.
  - `obec` string, required: Municipality code returned by GET /v1/numbers/address-options.
  - `cobce` string, required: Municipality-part code returned for the selected municipality.
  - `ulice` string: Street code from the address cascade; omit where the address has no street.
  - `cp` string, required: House-number code returned by the address cascade, not a free-form address.

## Response `200`

Created order

- object
  - `order` object, required
    - `id` string, required
    - `status` 'pending' | 'provisioning' | 'done' | 'failed' | 'cancelled', required
    - `address` string, required
    - `e164` string
    - `error` string
    - `createdAt` number, required
    - `updatedAt` number, required

## Other responses

- `400`: Error codes: validation (request), incomplete_address (request).
- `401`: Error codes: unauthorized (request).
- `402`: Error codes: insufficient_credit (account), subscription_cap_reached (account).
- `403`: Error codes: account_suspended (account).
- `409`: Error codes: idempotency_in_progress (busy), idempotency_conflict (request).
- `429`: Error codes: rate_limited (busy).
- `500`: Error codes: internal_error (service).
- `503`: Error codes: orders_disabled (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)