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"

List Available Services

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

{
  "whatsapp": { "Category": "activation", "Qty": 1250, "Price": 9.50 },
  "telegram": { "Category": "activation", "Qty": 890, "Price": 2.75 },
  "tinder":   { "Category": "activation", "Qty": 430, "Price": 3.20 }
}

Buy a Virtual2 Number

curl "https://smsbuyz.com/v1/user/buy/activation/turkey/Virtual2/whatsapp" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Accept: application/json"

{
  "id": 456,
  "phone": "905321234567",
  "operator": "Virtual2",
  "product": "whatsapp",
  "price": 9.50,
  "status": "PENDING",
  "expires": "2026-01-15T12:20:00",
  "sms": [],
  "created_at": "2026-01-15T12:00:00",
  "country": "tr"
}

Supported Countries (examples)

Step 1: List Available Virtual3 Services

Query products with operator=Virtual3 to see available services and prices for a country.

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

{
  "telegram": { "Category": "activation", "Qty": 5000, "Price": 1.50 },
  "whatsapp": { "Category": "activation", "Qty": 3200, "Price": 2.10 },
  "viber":    { "Category": "activation", "Qty": 1800, "Price": 1.85 }
}

Step 2: Buy a Virtual3 Number

Use the standard buy endpoint with Virtual3 as the operator.

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

{
  "id": 789,
  "phone": "79001234567",
  "operator": "Virtual3",
  "product": "telegram",
  "price": 1.50,
  "status": "PENDING",
  "expires": "2026-01-15T12:20:00",
  "sms": [],
  "created_at": "2026-01-15T12:00:00",
  "country": "ru"
}

Step 3: Check for SMS

Poll the check endpoint every 3-5 seconds to wait for the SMS code.

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

{
  "id": 789,
  "phone": "79001234567",
  "operator": "Virtual3",
  "product": "telegram",
  "price": 1.50,
  "status": "RECEIVED",
  "country": "ru",
  "sms": [
    {
      "created_at": "2026-01-15T12:01:30",
      "code": "485291",
      "text": "Telegram code: 485291",
      "sender": "Telegram"
    }
  ]
}

Step 4: Finish or Cancel

# After using the code successfully:
curl "https://smsbuyz.com/v1/user/finish/789" \
  -H "Authorization: Bearer $TOKEN"

# Or cancel if SMS is not needed (refunds balance):
curl "https://smsbuyz.com/v1/user/cancel/789" \
  -H "Authorization: Bearer $TOKEN"

Error Codes & Order Statuses

HTTP Status Codes

Order Statuses