Introduction
Welcome to the BloomSMS Reseller API. Our unified REST API provides a professional-grade interface for managing short-term SMS activations and long-term rentals through a consistent JSON protocol.
Base API URL
https://bloomsms.com/api/v1Rate Limits
60 requests/min per API key.
Response Format
All responses use the { status, data, errors } envelope.
Authentication
Include your API key as a Bearer token in every request. Generate it from the API Management page.
curl -X GET "https://bloomsms.com/api/v1/balance" \
-H "Authorization: Bearer sk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
-H "Content-Type: application/json"Error Codes
Standard error codes returned across all endpoints:
| HTTP | Code | Description |
|---|---|---|
| 401 | INVALID_API_KEY | Missing or invalid Bearer token |
| 402 | INSUFFICIENT_FUNDS | Account balance too low |
| 403 | ACCOUNT_SUSPENDED | Account is disabled |
| 404 | ACTIVATION_NOT_FOUND | Activation or rental not found |
| 404 | SERVICE_NOT_FOUND | Service does not exist |
| 400 | NO_NUMBERS_AVAILABLE | No stock for service/country |
| 400 | MAX_RENTALS_EXCEEDED | Active rental limit reached |
| 422 | INVALID_PARAMETER | Missing or invalid parameter |
| 429 | RATE_LIMITED | Too many requests |
| 502 | PROVIDER_ERROR | Upstream provider failure |
| 503 | MAINTENANCE | Service temporarily unavailable |
{
"status": "error",
"data": null,
"errors": { "code": "INSUFFICIENT_FUNDS", "message": "Insufficient balance." }
}Account Balance
GET https://bloomsms.com/api/v1/balance{
"status": "success",
"data": { "balance": "125.50", "currency": "USD" },
"errors": null
}Countries
List all available countries for short-term activations.
GET https://bloomsms.com/api/v1/countries{
"status": "success",
"data": {
"countries": [
{ "id": "0", "name": "Russia" },
{ "id": "187", "name": "United States" }
]
},
"errors": null
}Services & Pricing
Get available services with real-time prices and stock. Defaults to country 187 (US).
GET https://bloomsms.com/api/v1/services?country=187{
"status": "success",
"data": {
"services": [
{ "code": "wa", "name": "WhatsApp", "price": "0.55", "stock": 980 },
{ "code": "tg", "name": "Telegram", "price": "0.45", "stock": 1200 }
]
},
"errors": null
}GET https://bloomsms.com/api/v1/prices?country=0&service=waRent Number (Short-Term)
Request a temporary virtual number for SMS verification.
| Parameter | Type | Required | Description |
|---|---|---|---|
| service | string | Yes | Service code (e.g. "wa") |
| country | string | No | Country ID or "any" (default) |
| max_price | float | No | Maximum price in USD |
POST https://bloomsms.com/api/v1/activations
Content-Type: application/json
{ "service": "wa", "country": "187" }{
"status": "success",
"data": {
"activation_id": "38496653",
"phone_number": "+19001234567",
"service": "wa",
"country": "187",
"price": "0.55",
"currency": "USD",
"expires_at": "2026-05-05T14:20:00+00:00",
"new_balance": "124.95"
},
"errors": null
}Get / Update Activation Status
Poll for incoming SMS codes or update the activation (cancel, complete, request another SMS).
GET https://bloomsms.com/api/v1/activations/{activation_id}{
"status": "success",
"data": {
"activation_id": "38496653",
"activation_status": "code_received",
"phone_number": "+19001234567",
"sms": { "code": "852508", "full_text": "Your WhatsApp code is 852508" }
},
"errors": null
}waiting → code_received → completed.cancel.| Parameter | Type | Required | Description |
|---|---|---|---|
| status | string | Yes | "cancel" | "complete" | "request_another_sms" |
PATCH https://bloomsms.com/api/v1/activations/{activation_id}
Content-Type: application/json
{ "status": "cancel" }Re-Rent Number
Rent the same phone number again for another SMS on the same service.
POST https://bloomsms.com/api/v1/activations/{activation_id}/re-rent{
"status": "success",
"data": {
"activation_id": "38496700",
"phone_number": "+19001234567",
"service": "wa",
"price": "0.55",
"expires_at": "2026-05-05T14:40:00+00:00",
"new_balance": "124.40"
},
"errors": null
}Webhooks
Webhooks allow you to receive real-time HTTP notifications when events occur in your account, such as receiving an SMS. This eliminates the need to constantly poll the API.
You can configure webhooks in your Dashboard under the API Management page.
Event: sms.received
Fired when a new SMS or OTP code is received for one of your rented numbers.
{
"event": "sms.received",
"timestamp": "2025-05-05T14:30:00+00:00",
"data": {
"activation_id": "123456789",
"phone_number": "1234567890",
"service": "wa",
"sms": {
"code": "852508",
"full_text": "Your WhatsApp code: 852508"
},
"status": "code_received"
}
}