SmsBuyz API Documentation

The SmsBuyz API allows you to programmatically purchase virtual phone numbers, receive SMS verification codes, and manage your orders. All responses are in JSON format.

Authentication

All user endpoints require a Bearer token in the Authorization header. Get your API key from Settings → API. Guest endpoints do not require authentication.

GET /v1/user/profile

Get current user profile information including balance.

Headers

cURL Example

curl "https://smsbuyz.com/v1/user/profile" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Accept: application/json"

Response 200

{
  "id": 1,
  "email": "[email protected]",
  "balance": 10.50,
  "rating": 0,
  "default_operator": "any"
}

GET /v1/user/orders

Get order history for authenticated user.

Query Parameters

curl "https://smsbuyz.com/v1/user/orders?category=activation&limit=10" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Accept: application/json"

Response 200

[
  {
    "id": 123,
    "phone": "79001234567",
    "operator": "Virtual1",
    "product": "microsoft",
    "price": 0.4118,
    "status": "FINISHED",
    "country": "ru",
    "created_at": "2026-01-15T12:00:00",
    "sms": [
      {
        "created_at": "2026-01-15T12:01:30",
        "code": "123456",
        "text": "Your code is 123456"
      }
    ]
  }
]

GET /v1/user/payments

Get payment / transaction history.

curl "https://smsbuyz.com/v1/user/payments" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Accept: application/json"

GET /v1/guest/products/{country}/{operator}

Get available products for a specific country and operator. No authentication required.

Path Parameters

curl "https://smsbuyz.com/v1/guest/products/russia/any" \
  -H "Accept: application/json"

Response 200

{
  "microsoft": {
    "Category": "activation",
    "Qty": 45832,
    "Price": 0.4118
  },
  "amazon": {
    "Category": "activation",
    "Qty": 12004,
    "Price": 0.5147
  }
}

GET /v1/guest/prices

Get prices by product, country, and operator. No authentication required.

Query Parameters

curl "https://smsbuyz.com/v1/guest/prices?product=microsoft&country=ru"

Response 200

{
  "ru": {
    "Virtual1": {
      "cost": 0.4118,
      "count": 45832
    }
  }
}

GET /v1/user/buy/activation/{country}/{operator}/{product}

Purchase a virtual number for SMS activation. Deducts the price from your balance.

Path Parameters

curl "https://smsbuyz.com/v1/user/buy/activation/ru/Virtual1/microsoft" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Accept: application/json"

Response 200

{
  "id": 123,
  "phone": "79001234567",
  "operator": "Virtual1",
  "product": "microsoft",
  "price": 0.4118,
  "status": "PENDING",
  "expires": "2026-01-15T12:20:00",
  "sms": [],
  "created_at": "2026-01-15T12:00:00",
  "country": "ru"
}

GET /v1/user/check/{id}

Check order status and receive SMS code. Poll this endpoint every 3-5 seconds until SMS arrives.

curl "https://smsbuyz.com/v1/user/check/123" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Accept: application/json"

Response 200 (SMS received)

{
  "id": 123,
  "phone": "79001234567",
  "operator": "Virtual1",
  "product": "microsoft",
  "price": 0.4118,
  "status": "RECEIVED",
  "country": "ru",
  "sms": [
    {
      "created_at": "2026-01-15T12:01:30",
      "code": "123456",
      "text": "Your code is 123456",
      "sender": "Microsoft"
    }
  ]
}

GET /v1/user/finish/{id}

Mark order as finished after successfully using the SMS code. Only works on RECEIVED orders.

curl "https://smsbuyz.com/v1/user/finish/123" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Accept: application/json"

GET /v1/user/cancel/{id}

Cancel a PENDING order. The full price will be refunded to your balance.

curl "https://smsbuyz.com/v1/user/cancel/123" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Accept: application/json"

GET /v1/user/ban/{id}

Ban the phone number from being assigned to you again. Works on PENDING or RECEIVED orders.

curl "https://smsbuyz.com/v1/user/ban/123" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Accept: application/json"

Error Codes & Order Statuses

HTTP Status Codes

Order Statuses