---
title: "Create an order"
method: POST
path: "/api/v1/orders"
tags: ["Orders"]
---

# Create an order

`POST /api/v1/orders`

## Request

- Base URL: `https://virtualsms.io`
- URL: `https://virtualsms.io/api/v1/orders`
- Auth: one of:
  - API key in header `X-API-Key`
  - API key in query parameter `api_key`

Buy a number for one SMS verification. The price is debited from your
balance on success. The order is live until `expires_at`; if no code
arrives, a background job refunds it.

Also served as `POST /api/v1/order`.

## Request body

- OrderCreateRequest
  - `service` string, required: Service id from `GET /api/v1/services`.
  - `country` string, required: Country id from `GET /api/v1/countries`.

## Response `201`

Order created and number assigned

- OrderCreateResponse
  - `success` boolean
  - `order_id` string, uuid
  - `phone_number` string
  - `service` string
  - `service_id` string
  - `service_name` string
  - `country` string
  - `price` number, float
  - `status` string
  - `expires_at` string
  - `created_at` string
  - `can_swap_number` boolean

## Other responses

- `400`: `service` or `country` missing, malformed JSON, or an unknown service.
- `402`: Insufficient balance
- `404`: No number available for that service and country
- `409`: The number was taken between quote and purchase — retry.
- `503`: Temporarily out of stock for that service and country

---

[API](https://skmtc.dev/virtualsms/apis/virtualsms-account-verification-platform-for-developers-and.md) · [All operations](https://skmtc.dev/virtualsms/apis/virtualsms-account-verification-platform-for-developers-and/llms.txt) · [OpenAPI document](https://skmtc.dev/virtualsms/apis/virtualsms-account-verification-platform-for-developers-and/revisions/be89af981be1?raw)