# Get SMS API v1: integration instructions for developers and AI agents

Authoritative base: https://get-sms.io/api/v1
Machine-readable contract: https://get-sms.io/developers/openapi.json
Human guide and key management: https://get-sms.io/developers
Contact: support@get-sms.io

This is NOT drop-in 5sim compatibility. Do not infer endpoint paths, use upstream credentials or IDs, mutate through GET, or implement unsupported hosting/rebuy/ban/callback endpoints.

## Authentication and customer ownership

Create a normal Get SMS customer account, add funds through the website, and create a named API key in /developers. Maximum three active keys. A key is `gs_live_` followed by64hexadecimalcharacters, returned only once; backend stores only its SHA-256 hash. Send `Authorization: Bearer KEY` on every endpoint. Never put it in URLs or ship it to frontend/mobile code. No CORS allowance is provided. Cookies cannot authenticate API calls. Revocation blocks future admissions, but an already authorized in-flight operation may finish.

All keys for one customer share its wallet, rate limits and order history, including website orders. You must implement authorization in your own application to keep different end-customers' orders private. Get SMS checks ownership on every lookup/action. Blocked users, admins and revoked keys cannot call the customer API. No API identity can use the upstream owner-funded balance.

## Required purchase algorithm

1. GET /catalog. Use exact canonical IDs. UK country is `england`, not `uk`. No Türkiye. No activation/hosting interchangeability.
2. GET /prices?country=COUNTRY&service=SERVICE. New quotes offer only the explicit price-protected `any` operator. Select `any` from `data.prices`; a specific operator is not guaranteed. Use its current `price` (USD string, four decimals). Add your own resale margin separately; Get SMS manages your customer wallet, not your end-customer billing.
3. Persist one fresh UUID (versions 1–5 accepted; generate UUIDv4), the exact body, and your end-customer purchase mapping BEFORE POST. Body fields are ONLY `country`, `service`, `operator`, `max_price`. max_price is a positive decimal string, up to four decimals. Example values are not current quotes.
4. POST /orders with `Idempotency-Key: PERSISTED_UUID`, `Content-Type: application/json`, and the persisted body. Allow at least120seconds for the response; acquisition can take approximately70seconds plus network/DB work. Proxy timeouts can still happen.
5. Success HTTP202 contains `data` order and `request_id`. Inspect order status. 202 does NOT guarantee number assignment or SMS arrival. Persist `data.id` (Get SMS UUID, never upstream numeric ID).
6. If the response is lost, malformed, 429 or any5xx: first GET /requests/PERSISTED_UUID. If an order exists, continue that order. If404, the earlier request may still be in preflight; retry the SAME POST with exactly the same key/body. Never create another UUID to escape an unknown outcome.
7. Repeating same key/body across key rotation returns the same order. Different fields for the same UUID produce409 IDEMPOTENCY_CONFLICT. Requests whose preflight failed can retain intent without an order; do not treat404 as a completed cancellation.
8. GET /orders/ORDER_UUID every5seconds or slower, within the SHARED 30polls/minute account budget; stagger polling. Display E.164 phone (including+). Each `sms` object contains `code`, `body`, `received_at` UTC. Preserve chronological messages; do not log them or send them to analytics.
9. POST /orders/ORDER_UUID/finish with `{}` after code use. Or cancel with POST /orders/ORDER_UUID/cancel and `{}` after `cancel_available_at`, before SMS. Use POST /orders/ORDER_UUID/stop and `{}` to stop an unassigned search after15seconds. An in-flight number purchase may still finish.
10. Always inspect returned status and GET /balance before promising a refund to your end-customer. A network error, UI cancel, elapsed timer or stop intent is not proof of refund.

## Pricing is dynamic

GET /prices and new purchase validation read current site markup and provider conversion rate directly; there is no API-specific frozen markup. If Get SMS markup changes20%→30%, subsequent quotes and new purchases use30%. Prices round upward to four decimals. Price is checked again at purchase; if above max_price reject409 before buying. A second quote race also rejects409 ORDER_CONFLICT. Wallet reservation and purchase ownership are committed in one transaction, using one pricing context; a concurrent retry cannot replace that context. Read prices again, obtain end-customer approval and create a genuinely new intent for a newly approved quote. Already reserved orders keep their agreed amount. Stock and success rate are non-guaranteed estimates. No upstream cost is exposed.

## States and balance semantics

- created, purchasing: reservation exists; purchase may still be running. No second intent.
- reconciliation: ambiguous provider result. Funds remain protected/reserved until authoritative resolution. Do not rebuy or refund based on this status.
- pending: number assigned, awaiting SMS.
- received: SMS observed; cannot cancel for a refund. Reserved price remains until settlement.
- finished: terminal, charged; may be automatic after saved SMS and provider closure. SMS remains readable even if the provider closed the order as cancelled, timed out or banned.
- cancelled, timeout, banned, failed: terminal; unused reservations released only by settlement. Observed SMS can make a terminal order chargeable. Inspect balance and history.

### SMS delivery during cancellation or expiry

`finished` does not necessarily mean your application called `/finish`. A valid stored SMS plus provider closure is automatically settled as a paid `finished` order, even if the provider's terminal result was cancellation, expiry or ban. The agreed Get SMS price is charged once and SMS remains readable. This is not a refund.

1. Cancellation HTTP 200: inspect `data.status`, then GET `/balance`. An already terminal order can return `finished`; do not interpret HTTP 200 as cancellation/refund confirmation.
2. Cancellation HTTP 409 `ORDER_CONFLICT`: SMS may have arrived and been saved during the cancellation attempt. GET `/orders/{id}` with the SAME Get SMS order UUID. A `received` or `finished` response retains SMS; display all messages and their arrival times. Do not create a new order or refund your end-customer from the conflict alone.
3. If the state is still active or uncertain, keep following that order within rate limits. A timeout or local timer is not proof that funds were released.

Illustrative race (not live requests): pending -> cancel attempt -> SMS saved -> provider reports closure -> cancel may return409 -> GET the same order returns `finished` with SMS. If the order was already closed before the cancel action, the response can instead be200 with that saved terminal state.

This rule processes unresolved orders going forward. Historical terminal records were not rewritten by the fix; inspect their saved state and balance and contact support for a discrepancy.


GET /balance returns `currency: USD`, `balance` (total), `reserved`, `available` (spendable); all money values are decimal strings. Maximum five active/resolving orders across API and website. The shared wallet is locked before reservation; concurrent requests cannot spend the same available funds. Cancellation normally unlocks60seconds after provider purchase time; account-specific exemption is reflected in cancel_available_at. No manual local refund on uncertain provider cancellation. Finishing requires SMS. Repeat terminal actions return recorded terminal state, not a fabricated success for the requested action.

## Pagination and errors

GET /orders?page=1&limit=20 returns data.page, limit, total, orders; limit1–50, page1–100000, newest first. All account orders are visible. Offset pagination can shift when new orders arrive; deduplicate by id. GET order can refresh provider status; list returns saved state.

Success: `{ "data": ..., "request_id": "UUID" }`.
Failure: `{ "error": { "code": "...", "message": "...", "retry_after": 30 }, "request_id": "UUID" }` (retry_after optional). `X-Request-ID` and `X-API-Version: 1` headers.

-400INVALID_REQUEST: fix validation, no blind retry.
-401UNAUTHORIZED: fix/revoke key or account status.
-404NOT_FOUND: wrong endpoint/ownership or not-yet-recorded request.
-409PRICE_PROTECTION_REQUIRED, PRICE_CHANGED, NO_STOCK, IDEMPOTENCY_CONFLICT, WAIT_REQUIRED, ORDER_CONFLICT: inspect code, message and current order/balance. WAIT_REQUIRED includes retry_after and Retry-After for cancellation/search-stop waits. Do not automatically change key.
-413body too large (max2048bytes),415unsupported media type.
-429RATE_LIMITED: Retry-After seconds; exponential backoff with jitter.
-503PROVIDER_UNAVAILABLE or SERVICE_UNAVAILABLE: retain key and recover recorded order, do not buy again.

Per-account and per-key general ceiling120/min; additional per-account10purchase attempts/min,30order polls/min,30actions/min. Fixed-window limits; retries count. API-wide and trusted-proxy IP safeguards can impose lower limits. Respect headers. Do not poll in tight loops or rotate keys to evade limits.

## Working examples (backend only)

```python
import os, uuid, requests
base = 'https://get-sms.io/api/v1'
s = requests.Session()
s.headers['Authorization'] = 'Bearer ' + os.environ['GETSMS_API_KEY']
r = s.get(base + '/prices', params={'country':'usa','service':'telegram'}, timeout=25)
r.raise_for_status()
quote = next(p for p in r.json()['data']['prices'] if p['stock'] > 0)
intent = {'key':str(uuid.uuid4()), 'body':{'country':'usa','service':'telegram',
          'operator':quote['operator'], 'max_price':quote['price']}}
# REQUIRED: persist intent to your database BEFORE calling below.
# This snippet shows transport only. Implement durable persistence + recovery
# above; do not regenerate intent on timeout or service errors.
r = s.post(base + '/orders', json=intent['body'],
           headers={'Idempotency-Key':intent['key']}, timeout=120)
r.raise_for_status()
order = r.json()['data']
```

```javascript
// Server-side Node.js only; persist key+body before sending.
const headers = {Authorization: `Bearer ${process.env.GETSMS_API_KEY}`};
async function recover(persistedKey) {
  const response = await fetch(`https://get-sms.io/api/v1/requests/${persistedKey}`,
    {headers, signal: AbortSignal.timeout(25000)});
  // Handle404/429/503 according to the recovery rules. Never make a fresh intent.
  if (!response.ok) throw new Error(`Recovery HTTP ${response.status}`);
  return (await response.json()).data;
}
```

## Supported scope and verification limits

v1 supports prepaid SMS activation, polling, finish/cancel/search-stop, wallet reads and paginated history. No sandbox, no free numbers, no callbacks, no automatic rebuy, no separate reseller wallet, and no guaranteed delivery time/stock. Mock contract tests are possible; real purchases consume customer funds. Never claim a mocked SMS as real delivery. Live provider actions were deliberately not induced for API testing. Send support only request ID, UTC time and error code, never secrets, SMS or bulk customer data.


## Complete durable client and multi-order scheduling

Download the backend-only Python standard-library client:
https://get-sms.io/developers/example-client.py
It uses SQLite for durable intent storage, UUIDv4, same-intent recovery before
POST, bounded retries, Retry-After and jitter. Importing it performs no network
request. Protect and back up the intent database; all workers processing a sale
must use the same persistent store/reference. Never replace a reference after a
timeout. A definitive 409 requires an explicit business decision, not a new-key
retry loop. The client intentionally does not implement your customer billing,
authorization, production queue, cross-worker scheduler or refund decisions.

```python
# Save example-client.py as getsms_client.py on your backend.
from getsms_client import Client, poll_interval
client = Client('/private/persistent/getsms-intents.sqlite3')
# approved_body must contain country, service, operator, max_price from a fresh
# quote accepted by your customer. reference is YOUR durable sale identifier.
order = client.purchase(reference, approved_body)
# Persist order['id']; inspect status, including reconciliation/failed.
# Use ONE account-level poll queue across every key/worker.
interval = poll_interval(number_of_active_orders)
client.close()
```

Five active orders at one poll per five seconds require60polls/minute and exceed
the30/minute account ceiling. At five active orders, the example schedules each
every12.5seconds (24polls/minute) to leave six requests for retries/manual checks.
History/request lookups consume general limits too; budget all workers together.
Successful/failed refreshes use a cross-process API lease; losing callers can
receive the most recently saved state. A failed/crashed worker lease expires
within60seconds. Normal completed checks impose a five-second cooldown.
This coordinates API polling; website/maintenance checks remain separate.

### Stop a search while the first purchase response is still pending

1. A separate worker reads the SAME persisted request key, not a new UUID.
2. GET /requests/KEY. On404, wait/back off; validation may still be running.
3. Once data.id exists and at least15seconds since created_at, POST
   /orders/ID/stop with{}. On WAIT_REQUIRED honor Retry-After.
4. Continue reading the same order. An in-flight provider purchase may still
   assign a number; stop is not confirmation of cancellation or refund.
5. If pending, use /cancel after cancel_available_at. If received, no refund
   cancellation is promised. GET /balance before settling your own customer.

Order/request UUIDs accept upper/lowercase and are normalized internally. UUIDv7
is not accepted in v1; use UUIDv4 as demonstrated. Paths are case-sensitive apart
from the UUID value. Terminal repeated actions return the existing terminal state.


## Mandatory provider cost protection (policy update)

New purchases through API v1 require the explicitly chosen `any`
operator. `/prices` returns one price-protected any option per country/service,
using the cheapest positive in-stock cost as the provider ceiling. Stock at that
ceiling is an estimate, not the total stock of more expensive operators. Success
rate is omitted because this route does not promise a particular operator.
Every actual upstream purchase includes `maxPrice` equal to the saved upstream
quote. A price increase above that cap must not trigger an uncapped fallback.
If stock at the cap disappears, the same search may stop without a number.

A new request naming a fixed operator receives409 PRICE_PROTECTION_REQUIRED
before wallet reservation or provider purchase. It is never silently changed to
any. After explicitly accepting any and a fresh price, create a new intent;
first recover the previous request if its outcome was uncertain. Existing orders
are not rewritten: polling, cancellation, finish and exact same-body replay of an
already recorded legacy order continue normally. Do not alter a legacy intent body.

This protects the cost using the provider's documented any-route price cap; it
is not a promise about provider uptime/compliance, stock, SMS arrival or exchange
rate movements. Unexpected receipts remain subject to existing recovery/review.
Provider reference: https://5sim.net/docs (Buy activation number, maxPrice).

The website separately supports explicit fixed-operator selection. It rechecks the
current quote before reservation and requests cancellation/reconciliation for an
above-quote receipt. 5SIM does not enforce its per-request maxPrice for fixed
operators, so that website flow cannot promise an upstream price ceiling. The API
v1 contract above remains any-only; do not infer API support from website choices.

A reconciliation order whose upstream identity is not known returns200 with its
saved reconciliation state when polled. This is not a refund or permission to
buy again. Known upstream identities remain eligible for refresh. Local invalid
selection/policy errors use400 INVALID_REQUEST; connectivity failures use503.

The Python client validates the response envelope and order id/status/currency/
price/SMS container, treats incomplete or invalid responses as ambiguous, and
recovers the same persistent intent. It retries429 and5xx with bounded attempts,
backoff and Retry-After. It never generates a replacement key on those errors.

## Catalog validation and automatic price protection cancellation

Use exact country/service identifiers from `/catalog`. Unknown identifiers are
rejected with400 INVALID_REQUEST before a price lookup or wallet reservation.
A supported selection without inventory returns an empty price list; a catalog
connectivity failure remains503, not an invalid-customer-input response.
If an unexpected provider receipt exceeds its saved ceiling, automatic
cancellation uses the same independent confirmation as customer cancellation.
An acknowledgement alone cannot release funds. An active/unconfirmed result
remains reserved and under review; observed SMS evidence is retained. Never
interpret the automatic cancellation attempt as proof of a refund.

<!-- BEGIN GENERATED ENDPOINT REFERENCE -->
## Complete endpoint reference

Examples are illustrative and use synthetic IDs, prices and SMS. Every endpoint requires a customer Bearer key. Replace sample IDs with your saved IDs. Never paste a live key into documentation, logs or an AI prompt. POST /orders is a real purchase: persist the intent and approve its live quote before sending.

- [GET /catalog](#catalog)
- [GET /prices](#prices)
- [GET /balance](#balance)
- [POST /orders](#create-order)
- [GET /requests/{key}](#recover-request)
- [GET /orders/{id}](#check-order)
- [GET /orders](#order-history)
- [POST /orders/{id}/cancel](#cancel-order)
- [POST /orders/{id}/finish](#finish-order)
- [POST /orders/{id}/stop](#stop-search)

<a id="catalog"></a>
### Catalog — GET /catalog

Read canonical services and countries. Cache identifiers in your application; prices and stock must be read separately. The example is an abbreviated catalog.


```sh
# Replace the example order/request UUID with your saved UUID where applicable.
curl --request GET 'https://get-sms.io/api/v1/catalog' \
  --header "Authorization: Bearer $GETSMS_API_KEY" \
  --connect-timeout 10 --max-time 25
```

HTTP 200 response; data schema Catalog:

```json
{
  "data": {
    "currency": "USD",
    "services": [
      {
        "id": "telegram",
        "name": "Telegram"
      }
    ],
    "countries": [
      {
        "id": "usa",
        "name": "USA",
        "dial_code": "+1"
      },
      {
        "id": "england",
        "name": "United Kingdom",
        "dial_code": "+44"
      }
    ]
  },
  "request_id": "22222222-2222-4222-8222-222222222222"
}
```

<a id="prices"></a>
### Live prices — GET /prices

Choose one canonical country and service from the catalog. A supported pair without stock returns prices: []; an invalid identifier returns 400. Only an available any-operator quote can fund a new purchase. Values below are illustrative, never a live offer.

- query `country` (required): Canonical catalog country ID; USA is usa, United Kingdom is england. Türkiye is unavailable..
- query `service` (required): Canonical catalog service ID, for example telegram..

```sh
# Replace the example order/request UUID with your saved UUID where applicable.
curl --request GET 'https://get-sms.io/api/v1/prices?country=usa&service=telegram' \
  --header "Authorization: Bearer $GETSMS_API_KEY" \
  --connect-timeout 10 --max-time 25
```

HTTP 200 response; data schema Prices:

```json
{
  "data": {
    "currency": "USD",
    "checked_at": "2026-10-20T12:00:00.000Z",
    "prices": [
      {
        "country": "usa",
        "service": "telegram",
        "operator": "any",
        "price": "1.2000",
        "stock": 100,
        "success_rate": 80
      }
    ]
  },
  "request_id": "22222222-2222-4222-8222-222222222222"
}
```

<a id="balance"></a>
### Account balance — GET /balance

Read the shared customer wallet. available is spendable; balance includes reserved funds. Website and API purchases use this same wallet.


```sh
# Replace the example order/request UUID with your saved UUID where applicable.
curl --request GET 'https://get-sms.io/api/v1/balance' \
  --header "Authorization: Bearer $GETSMS_API_KEY" \
  --connect-timeout 10 --max-time 25
```

HTTP 200 response; data schema Balance:

```json
{
  "data": {
    "currency": "USD",
    "balance": "10.0000",
    "reserved": "1.2000",
    "available": "8.8000"
  },
  "request_id": "22222222-2222-4222-8222-222222222222"
}
```

<a id="create-order"></a>
### Buy a number — POST /orders

This starts a real, chargeable purchase. Persist one intent UUID and the exact body before sending. HTTP 202 means an order was recorded; inspect its status. A number and SMS are not guaranteed. No live requests run from this documentation.

- header `Idempotency-Key` (required): UUID versions 1–5; uppercase/lowercase accepted. Prefer UUIDv4..

JSON body: exactly country, service, operator, max_price; see CreateOrder schema.

```sh
# Replace the example UUID with your persisted intent UUID and max_price with an approved live quote.
curl --request POST 'https://get-sms.io/api/v1/orders' \
  --header "Authorization: Bearer $GETSMS_API_KEY" \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: 11111111-1111-4111-8111-111111111111' \
  --data '{"country":"usa","service":"telegram","operator":"any","max_price":"1.2000"}' \
  --connect-timeout 10 --max-time 120
```

HTTP 202 response; data schema Order:

```json
{
  "data": {
    "id": "11111111-1111-4111-8111-111111111111",
    "service": "telegram",
    "country": "usa",
    "operator": "any",
    "phone": null,
    "status": "purchasing",
    "currency": "USD",
    "price": "1.2000",
    "created_at": "2026-10-20T12:00:00.000Z",
    "expires_at": null,
    "cancel_available_at": null,
    "last_checked_at": null,
    "sms": []
  },
  "request_id": "22222222-2222-4222-8222-222222222222"
}
```

<a id="recover-request"></a>
### Recover a purchase — GET /requests/{key}

Use the original Idempotency-Key after a timeout or lost response. This lookup does not buy a number. A 404 can mean the original request is still in preflight; retry its same POST and body, not a new key.

- path `key` (required): UUID versions 1–5; uppercase/lowercase accepted. Prefer UUIDv4..

```sh
# Replace the example order/request UUID with your saved UUID where applicable.
curl --request GET 'https://get-sms.io/api/v1/requests/11111111-1111-4111-8111-111111111111' \
  --header "Authorization: Bearer $GETSMS_API_KEY" \
  --connect-timeout 10 --max-time 25
```

HTTP 200 response; data schema Order:

```json
{
  "data": {
    "id": "11111111-1111-4111-8111-111111111111",
    "service": "telegram",
    "country": "usa",
    "operator": "any",
    "phone": "+12025550123",
    "status": "pending",
    "currency": "USD",
    "price": "1.2000",
    "created_at": "2026-10-20T12:00:00.000Z",
    "expires_at": "2026-10-20T12:15:00.000Z",
    "cancel_available_at": "2026-10-20T12:01:00.000Z",
    "last_checked_at": "2026-10-20T12:00:10.000Z",
    "sms": []
  },
  "request_id": "22222222-2222-4222-8222-222222222222"
}
```

<a id="check-order"></a>
### Number and SMS — GET /orders/{id}

Read your order and all received SMS. Eligible checks refresh saved provider state; calls less than five seconds apart may return the cached state. Poll through one account-level queue.

- path `id` (required): UUID versions 1–5; uppercase/lowercase accepted. Prefer UUIDv4..

```sh
# Replace the example order/request UUID with your saved UUID where applicable.
curl --request GET 'https://get-sms.io/api/v1/orders/11111111-1111-4111-8111-111111111111' \
  --header "Authorization: Bearer $GETSMS_API_KEY" \
  --connect-timeout 10 --max-time 25
```

HTTP 200 response; data schema Order:

```json
{
  "data": {
    "id": "11111111-1111-4111-8111-111111111111",
    "service": "telegram",
    "country": "usa",
    "operator": "any",
    "phone": "+12025550123",
    "status": "received",
    "currency": "USD",
    "price": "1.2000",
    "created_at": "2026-10-20T12:00:00.000Z",
    "expires_at": "2026-10-20T12:15:00.000Z",
    "cancel_available_at": "2026-10-20T12:01:00.000Z",
    "last_checked_at": "2026-10-20T12:02:05.000Z",
    "sms": [
      {
        "code": "012345",
        "body": "Example verification code: 012345",
        "received_at": "2026-10-20T12:02:00.000Z"
      }
    ]
  },
  "request_id": "22222222-2222-4222-8222-222222222222"
}
```

<a id="order-history"></a>
### Order history — GET /orders

Newest first, across all API keys and website orders. Listing returns saved state and does not refresh each order. New arrivals can move offset pages; deduplicate by order id.

- query `page` (optional): Current one-based page.. Default 1.
- query `limit` (optional): Page size: 1–50, default 20.. Default 20.

```sh
# Replace the example order/request UUID with your saved UUID where applicable.
curl --request GET 'https://get-sms.io/api/v1/orders?page=1&limit=20' \
  --header "Authorization: Bearer $GETSMS_API_KEY" \
  --connect-timeout 10 --max-time 25
```

HTTP 200 response; data schema History:

```json
{
  "data": {
    "page": 1,
    "limit": 20,
    "total": 1,
    "orders": [
      {
        "id": "11111111-1111-4111-8111-111111111111",
        "service": "telegram",
        "country": "usa",
        "operator": "any",
        "phone": "+12025550123",
        "status": "pending",
        "currency": "USD",
        "price": "1.2000",
        "created_at": "2026-10-20T12:00:00.000Z",
        "expires_at": "2026-10-20T12:15:00.000Z",
        "cancel_available_at": "2026-10-20T12:01:00.000Z",
        "last_checked_at": "2026-10-20T12:00:10.000Z",
        "sms": []
      }
    ]
  },
  "request_id": "22222222-2222-4222-8222-222222222222"
}
```

<a id="cancel-order"></a>
### Cancel a number — POST /orders/{id}/cancel

Use after cancel_available_at and before SMS. Send {}. Cancellation is independently verified before unused funds are released. HTTP 200 does not prove a refund: inspect data.status and GET /balance. A recorded order can already be finished. If SMS arrives during cancellation, HTTP 409 ORDER_CONFLICT may follow a saved delivery; GET /orders/{id} using the same order UUID to retrieve received or finished state and its SMS. Do not create a new purchase or promise a refund from the cancellation response alone.

- path `id` (required): UUID versions 1–5; uppercase/lowercase accepted. Prefer UUIDv4..

JSON body: exactly `{}`.

```sh
# Replace the example order/request UUID with your saved UUID where applicable.
curl --request POST 'https://get-sms.io/api/v1/orders/11111111-1111-4111-8111-111111111111/cancel' \
  --header "Authorization: Bearer $GETSMS_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{}' \
  --connect-timeout 10 --max-time 25
```

HTTP 200 response; data schema Order:

```json
{
  "data": {
    "id": "11111111-1111-4111-8111-111111111111",
    "service": "telegram",
    "country": "usa",
    "operator": "any",
    "phone": "+12025550123",
    "status": "cancelled",
    "currency": "USD",
    "price": "1.2000",
    "created_at": "2026-10-20T12:00:00.000Z",
    "expires_at": "2026-10-20T12:15:00.000Z",
    "cancel_available_at": "2026-10-20T12:01:00.000Z",
    "last_checked_at": "2026-10-20T12:00:10.000Z",
    "sms": []
  },
  "request_id": "22222222-2222-4222-8222-222222222222"
}
```

<a id="finish-order"></a>
### Finish an order — POST /orders/{id}/finish

Use after an SMS arrives and you have used the code. Send {}. Finishing settles the charge; it is not cancellation. A repeated terminal action returns the recorded state.

- path `id` (required): UUID versions 1–5; uppercase/lowercase accepted. Prefer UUIDv4..

JSON body: exactly `{}`.

```sh
# Replace the example order/request UUID with your saved UUID where applicable.
curl --request POST 'https://get-sms.io/api/v1/orders/11111111-1111-4111-8111-111111111111/finish' \
  --header "Authorization: Bearer $GETSMS_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{}' \
  --connect-timeout 10 --max-time 25
```

HTTP 200 response; data schema Order:

```json
{
  "data": {
    "id": "11111111-1111-4111-8111-111111111111",
    "service": "telegram",
    "country": "usa",
    "operator": "any",
    "phone": "+12025550123",
    "status": "finished",
    "currency": "USD",
    "price": "1.2000",
    "created_at": "2026-10-20T12:00:00.000Z",
    "expires_at": "2026-10-20T12:15:00.000Z",
    "cancel_available_at": "2026-10-20T12:01:00.000Z",
    "last_checked_at": "2026-10-20T12:00:10.000Z",
    "sms": [
      {
        "code": "012345",
        "body": "Example verification code: 012345",
        "received_at": "2026-10-20T12:02:00.000Z"
      }
    ]
  },
  "request_id": "22222222-2222-4222-8222-222222222222"
}
```

<a id="stop-search"></a>
### Stop number search — POST /orders/{id}/stop

Use only for an unassigned search after 15 seconds. Send {}. An in-flight purchase can still finish; funds stay reserved until its outcome is confirmed. If a number arrives, follow the normal cancellation policy.

- path `id` (required): UUID versions 1–5; uppercase/lowercase accepted. Prefer UUIDv4..

JSON body: exactly `{}`.

```sh
# Replace the example order/request UUID with your saved UUID where applicable.
curl --request POST 'https://get-sms.io/api/v1/orders/11111111-1111-4111-8111-111111111111/stop' \
  --header "Authorization: Bearer $GETSMS_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{}' \
  --connect-timeout 10 --max-time 25
```

HTTP 200 response; data schema Order:

```json
{
  "data": {
    "id": "11111111-1111-4111-8111-111111111111",
    "service": "telegram",
    "country": "usa",
    "operator": "any",
    "phone": null,
    "status": "purchasing",
    "currency": "USD",
    "price": "1.2000",
    "created_at": "2026-10-20T12:00:00.000Z",
    "expires_at": null,
    "cancel_available_at": null,
    "last_checked_at": null,
    "sms": []
  },
  "request_id": "22222222-2222-4222-8222-222222222222"
}
```

## Field schemas

### CreateOrder

```json
{
  "type": "object",
  "properties": {
    "country": {
      "type": "string",
      "description": "Canonical catalog country ID; USA is usa, United Kingdom is england. Türkiye is unavailable."
    },
    "service": {
      "type": "string",
      "description": "Canonical catalog service ID, for example telegram."
    },
    "operator": {
      "type": "string",
      "description": "New intents must explicitly choose any from a current protected quote. No fixed operator guarantee. Exact replay of an already recorded legacy order keeps its original body.",
      "examples": [
        "any"
      ]
    },
    "max_price": {
      "type": "string",
      "pattern": "^(?!0+(?:\\.0+)?$)\\d{1,8}(\\.\\d{1,4})?$",
      "description": "Positive maximum Get SMS charge in USD. Fetch a live quote; no hard-coded prices."
    }
  },
  "required": [
    "country",
    "service",
    "operator",
    "max_price"
  ],
  "additionalProperties": false
}
```

### Balance

```json
{
  "type": "object",
  "properties": {
    "balance": {
      "$ref": "#/components/schemas/Money"
    },
    "reserved": {
      "$ref": "#/components/schemas/Money"
    },
    "available": {
      "$ref": "#/components/schemas/Money"
    },
    "currency": {
      "const": "USD",
      "description": "USD. All wallet and order money is expressed in USD."
    }
  },
  "required": [
    "balance",
    "reserved",
    "available",
    "currency"
  ]
}
```

### Order

```json
{
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "format": "uuid",
      "description": "Get SMS order UUID. Store as a string; do not use an upstream numeric ID."
    },
    "service": {
      "type": "string",
      "description": "Canonical catalog service ID, for example telegram."
    },
    "country": {
      "type": "string",
      "description": "Canonical catalog country ID; USA is usa, United Kingdom is england. Türkiye is unavailable."
    },
    "operator": {
      "type": "string",
      "description": "Use any from a current quote for a new order. A physical operator is not guaranteed."
    },
    "phone": {
      "anyOf": [
        {
          "type": "string",
          "pattern": "^\\+[1-9][0-9]{6,14}$"
        },
        {
          "type": "null"
        }
      ],
      "description": "E.164 phone string with +. Null until a number is assigned. Never convert to a number."
    },
    "status": {
      "type": "string",
      "enum": [
        "created",
        "purchasing",
        "pending",
        "received",
        "reconciliation",
        "finished",
        "cancelled",
        "timeout",
        "banned",
        "failed"
      ],
      "description": "Order lifecycle state. HTTP success alone does not mean a number, SMS, cancellation or refund."
    },
    "currency": {
      "const": "USD",
      "description": "USD. All wallet and order money is expressed in USD."
    },
    "price": {
      "$ref": "#/components/schemas/Money"
    },
    "created_at": {
      "type": "string",
      "format": "date-time",
      "description": "Order creation time, ISO 8601 UTC."
    },
    "expires_at": {
      "anyOf": [
        {
          "type": "string",
          "format": "date-time"
        },
        {
          "type": "null"
        }
      ],
      "description": "Order expiry if known; null before assignment or when unavailable."
    },
    "cancel_available_at": {
      "anyOf": [
        {
          "type": "string",
          "format": "date-time"
        },
        {
          "type": "null"
        }
      ],
      "description": "Earliest cancellation time under the account policy; null if not known. Read this field instead of hard-coding a timer."
    },
    "last_checked_at": {
      "anyOf": [
        {
          "type": "string",
          "format": "date-time"
        },
        {
          "type": "null"
        }
      ],
      "description": "Most recent saved provider check; null if none."
    },
    "sms": {
      "type": "array",
      "items": {
        "$ref": "#/components/schemas/SMS"
      },
      "description": "Chronologically ordered SMS records. More than one SMS can arrive."
    }
  },
  "required": [
    "id",
    "service",
    "country",
    "operator",
    "phone",
    "status",
    "currency",
    "price",
    "created_at",
    "expires_at",
    "cancel_available_at",
    "last_checked_at",
    "sms"
  ]
}
```

### SMS

```json
{
  "type": "object",
  "properties": {
    "code": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "description": "Code as a string (leading zeros preserved), or null if no code was extracted."
    },
    "body": {
      "type": "string",
      "description": "Original SMS text. May contain sensitive data; do not log or send to analytics."
    },
    "received_at": {
      "type": "string",
      "format": "date-time",
      "description": "SMS arrival timestamp in UTC. Use to distinguish multiple messages."
    }
  },
  "required": [
    "code",
    "body",
    "received_at"
  ]
}
```

### Catalog

```json
{
  "type": "object",
  "properties": {
    "currency": {
      "const": "USD",
      "description": "USD. All wallet and order money is expressed in USD."
    },
    "services": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "name": {
            "type": "string"
          }
        },
        "required": [
          "id",
          "name"
        ]
      },
      "description": "Canonical service identifiers and display names."
    },
    "countries": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "name": {
            "type": "string"
          },
          "dial_code": {
            "type": "string"
          }
        },
        "required": [
          "id",
          "name",
          "dial_code"
        ]
      },
      "description": "Canonical country identifiers, display names and dialing codes."
    }
  },
  "required": [
    "currency",
    "services",
    "countries"
  ]
}
```

### Prices

```json
{
  "type": "object",
  "properties": {
    "currency": {
      "const": "USD",
      "description": "USD. All wallet and order money is expressed in USD."
    },
    "checked_at": {
      "type": "string",
      "format": "date-time",
      "description": "Time this price response was produced. Prices can change before purchase."
    },
    "prices": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "country": {
            "type": "string"
          },
          "service": {
            "type": "string"
          },
          "operator": {
            "type": "string"
          },
          "price": {
            "$ref": "#/components/schemas/Money"
          },
          "stock": {
            "type": "number",
            "minimum": 0
          },
          "success_rate": {
            "type": "number"
          }
        },
        "required": [
          "country",
          "service",
          "operator",
          "price",
          "stock"
        ]
      },
      "description": "Available price-protected options. May be empty."
    }
  },
  "required": [
    "currency",
    "checked_at",
    "prices"
  ]
}
```

### History

```json
{
  "type": "object",
  "properties": {
    "page": {
      "type": "integer",
      "description": "Current one-based page."
    },
    "limit": {
      "type": "integer",
      "description": "Page size: 1–50, default 20."
    },
    "total": {
      "type": "integer",
      "description": "Total account orders at query time."
    },
    "orders": {
      "type": "array",
      "items": {
        "$ref": "#/components/schemas/Order"
      },
      "description": "Page of saved orders belonging to this customer."
    }
  },
  "required": [
    "page",
    "limit",
    "total",
    "orders"
  ]
}
```

## Error handling reference

- HTTP 400 `INVALID_REQUEST`: Invalid identifier, UUID, JSON, amount or unsupported field. Correct the input.
- HTTP 400 / 409 `REQUEST_REJECTED / ORDER_CONFLICT`: A domain rule rejected the operation. Inspect message, current order, balance and active orders.
- HTTP 401 `UNAUTHORIZED`: Key missing, invalid, revoked, or customer account unavailable. Check your server configuration.
- HTTP 404 `NOT_FOUND`: Wrong endpoint, missing/foreign order, or purchase intent with no order recorded yet. Recovery 404 is not proof of failure.
- HTTP 409 `IDEMPOTENCY_CONFLICT`: Same intent UUID with a different body. Recover the original request; do not overwrite its mapping.
- HTTP 409 `PRICE_PROTECTION_REQUIRED`: New purchases require operator=any from a live price-protected quote.
- HTTP 409 `PRICE_CHANGED`: Current cost exceeds max_price. Fetch a new quote and obtain approval before starting a genuinely new intent.
- HTTP 409 `NO_STOCK`: No available protected quote. Do not blindly buy repeatedly.
- HTTP 409 `WAIT_REQUIRED`: Action is too early. Honor error.retry_after and Retry-After, then inspect the same order.
- HTTP 413 `REQUEST_REJECTED`: JSON body exceeds 2,048 bytes. Reduce it.
- HTTP 415 `INVALID_REQUEST`: Send Content-Type: application/json for POST.
- HTTP 429 `RATE_LIMITED`: Honor Retry-After; use backoff with jitter. Purchase retries keep their original intent key.
- HTTP 503 `SALES_UNAVAILABLE`: Sales or currency conversion settings are unavailable. Do not start a new intent automatically.
- HTTP 503 `PROVIDER_UNAVAILABLE / SERVICE_UNAVAILABLE`: Recover the same purchase intent. A timeout or 5xx does not prove that no number was bought.
