API Documentation

API Documentation

Integrate SMS.SB directly into your software. Automate verifications with our simple, high-performance REST API.

Get API KeySupport

Introduction

The SMS.SB API is organized around REST. Our API has predictable resource-oriented URLs, accepts form-encoded request bodies, returns JSON-encoded responses, and uses standard HTTP response codes, authentication, and verbs.

Base URL

https://sms.sb/api/v1

Authentication

Authenticate your requests using your API Key found in Settings. Pass it via the Authorization header or api_key query parameter.

Authorization Header (Recommended)
Authorization: Bearer sk_live_...

!
Errors

SMS.SB uses conventional HTTP response codes to indicate the success or failure of an API request.

200 - OK

Everything worked as expected.

400 - Bad Request

The request was unacceptable, often due to missing parameters.

401 - Unauthorized

No valid API key provided.

404 - Not Found

The requested resource doesn't exist.

Error Codes

The order and cancel endpoints return structured error codes for programmatic handling:

INVALID_API_KEY401Missing or invalid API key.
INVALID_REQUEST400Missing required parameters (service, country, id, etc.).
NOT_FOUND404Order not found or does not belong to your account.
INVALID_STATE400Order is not in a valid state for this action (e.g. cancelling an already completed order).
NO_NUMBERS409No numbers currently available. Retry after 1-2 seconds.
PRICE_CHANGED409Price has changed since you last checked. Response includes old_price and new_price.
OUT_OF_STOCK409Service is unavailable in this country.
INSUFFICIENT_BALANCE402Not enough balance. Response includes required and balance fields.
TRANSIENT_ERROR503Temporary issue. Safe to retry immediately.
TOO_EARLY400Cannot cancel before 2 minutes have passed since purchase.
NO_CODE_YET409Cannot complete order before SMS code is received. Keep polling /status.
CANCEL_FAILED400The cancellation request was rejected by the provider.
SERVER_ERROR500Unexpected server error. Contact support if persistent.
GET

/api/v1/balance

Get Balance

Retrieve your current account balance.

curl -H "Authorization: Bearer YOUR_API_KEY" \
  https://sms.sb/api/v1/balance
Response
{
  "balance": 125.50,
  "currency": "USD"
}
GET

/api/v1/services

Get Services

Get a list of available services and their prices for a specific country.

Parameters
countrynumber- Country ID (default: 0 for Russia)
curl "https://sms.sb/api/v1/services?country=0" \
  -H "Authorization: Bearer YOUR_API_KEY"
Response
{
  "success": true,
  "country": 0,
  "services": [
    { "id": "vk", "name": "VKontakte", "price": 0.15, "currency": "USD" },
    { "id": "tg", "name": "Telegram", "price": 0.25, "currency": "USD" }
  ]
}
GET

/api/v1/countries

Get Countries

Get a list of all supported countries.

curl "https://sms.sb/api/v1/countries" \
  -H "Authorization: Bearer YOUR_API_KEY"
Response
{
  "success": true,
  "countries": [
    { "id": 0, "name": "Russia" },
    { "id": 1, "name": "Ukraine" }
  ]
}
POST

/api/v1/order

Buy Number

Purchase a number for a specific service.

Parameters
servicestringrequired- Service ID (e.g. "tg", "wa")
countrynumberrequired- Country ID
operatorstring- Specific operator or "any"
max_pricenumber- Maximum price you are willing to pay (USD). Order is rejected if price exceeds this.
curl -X POST "https://sms.sb/api/v1/order" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"service": "tg", "country": 0, "max_price": 0.50}'
Response
// Success
{
  "success": true,
  "id": "order_uuid_...",
  "phone": "79991234567",
  "service": "Telegram",
  "cost": 0.25,
  "status": "active"
}

// Error (structured)
{
  "success": false,
  "code": "PRICE_CHANGED",
  "error": "Price has changed",
  "old_price": 0.25,
  "new_price": 0.35
}
GET

/api/v1/status

Get Order Status

Get the status and SMS code for an order. If no ID provided, returns all active orders.

Parameters
idstringrequired- Order ID received from order endpoint
curl "https://sms.sb/api/v1/status?id=ORDER_ID" \
  -H "Authorization: Bearer YOUR_API_KEY"
Response
{
  "success": true,
  "status": "completed",
  "code": "12345",
  "phone": "79991234567"
}
POST

/api/v1/complete

Complete Order

Confirm that you received the SMS code and release the number. This can only be called after the code has been received. If no code has arrived yet, you'll get a NO_CODE_YET error — keep polling /status instead.

Parameters
idstringrequired- Order ID to complete
curl -X POST "https://sms.sb/api/v1/complete" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"id": "ORDER_ID"}'
Response
// Success (code already known)
{
  "success": true,
  "status": "completed"
}

// Success (code found during complete)
{
  "success": true,
  "status": "completed",
  "code": "12345"
}

// No code received yet
{
  "success": false,
  "code": "NO_CODE_YET",
  "error": "Cannot complete order before SMS code is received."
}
POST

/api/v1/cancel

Cancel Order

Cancel an active order and get a full refund. Note: cancellation is only possible after 2 minutes have passed since purchase. If you try earlier, you'll get a TOO_EARLY error code.

Parameters
idstringrequired- Order ID to cancel
curl -X POST "https://sms.sb/api/v1/cancel" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"id": "ORDER_ID"}'
Response
// Success
{
  "success": true,
  "status": "cancelled",
  "refunded": 0.25
}

// Too early
{
  "success": false,
  "code": "TOO_EARLY",
  "error": "Cannot cancel before 2 minutes have passed"
}
GET

/api/v1/services/stats

Get Service Stats

Get detailed availability and deliverability statistics for a service.

Parameters
servicestringrequired- Service ID (e.g. "tg", "wa")
countrynumber- Country ID (default: 0)
curl "https://sms.sb/api/v1/services/stats?service=tg&country=0" \
  -H "Authorization: Bearer YOUR_API_KEY"
Response
{
  "success": true,
  "service": "tg",
  "country": 0,
  "stats": {
    "quantity": 1429,
    "price": 0.25,
    "deliverability": 25.82,
    "cheapest_countries": [
        { "country_id": 6, "country_name": "Indonesia", "price": "0.10" }
    ]
  }
}