API Documentation

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/v1

Rate 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.

GETExample Request

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

Error Response Example

{
  "status": "error",
  "data": null,
  "errors": { "code": "INSUFFICIENT_FUNDS", "message": "Insufficient balance." }
}

Account Balance

GETRequest

GET https://bloomsms.com/api/v1/balance

Response

{
  "status": "success",
  "data": { "balance": "125.50", "currency": "USD" },
  "errors": null
}

Countries

List all available countries for short-term activations.

GETRequest

GET https://bloomsms.com/api/v1/countries

Response

{
  "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).

GETList Services

GET https://bloomsms.com/api/v1/services?country=187

Response

{
  "status": "success",
  "data": {
    "services": [
      { "code": "wa", "name": "WhatsApp", "price": "0.55", "stock": 980 },
      { "code": "tg", "name": "Telegram", "price": "0.45", "stock": 1200 }
    ]
  },
  "errors": null
}

GETGet Prices by Country

GET https://bloomsms.com/api/v1/prices?country=0&service=wa

Rent 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

POSTRequest

POST https://bloomsms.com/api/v1/activations
Content-Type: application/json

{ "service": "wa", "country": "187" }

Response (201)

{
  "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).

GETGet Status

GET https://bloomsms.com/api/v1/activations/{activation_id}

Response — Code Received

{
  "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
}

Status flow: waiting → code_received → completed.

Cancel anytime with cancel.

Parameter	Type	Required	Description
status	string	Yes	"cancel" \| "complete" \| "request_another_sms"

PATCHUpdate Status

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.

POSTRequest

POST https://bloomsms.com/api/v1/activations/{activation_id}/re-rent

Response (201)

{
  "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
}

Long Rental Prices

Get pricing for service-specific long-term rentals. Available periods: 1d, 3d, 7d, 14d, 30d.

GETRequest

GET https://bloomsms.com/api/v1/long-rentals/prices

Response

{
  "status": "success",
  "data": {
    "services": [
      {
        "service_name": "WhatsApp",
        "service_code": "whatsapp",
        "periods": [
          { "period": "1d", "price": "1.65" },
          { "period": "7d", "price": "5.50" },
          { "period": "30d", "price": "16.50" }
        ]
      }
    ]
  },
  "errors": null
}

Long Rentals

Create and list your long-term number rentals.

GETList My Rentals

GET https://bloomsms.com/api/v1/long-rentals

Parameter	Type	Required	Description
service	string	Yes	Service code (e.g. "whatsapp")
period	string	Yes	"1d", "3d", "7d", "14d", or "30d"
auto_renew	boolean	No	Enable auto-renewal (default: false)

POSTCreate Long Rental

POST https://bloomsms.com/api/v1/long-rentals
Content-Type: application/json

{ "service": "whatsapp", "period": "7d", "auto_renew": true }

Response (201)

{
  "status": "success",
  "data": {
    "id": 1,
    "phone_number": "1234567890",
    "service_name": "WhatsApp",
    "service_code": "whatsapp",
    "status": "active",
    "period": "7d",
    "price": "5.50",
    "auto_renew": true,
    "new_balance": "119.50"
  },
  "errors": null
}

Long Rental Actions

Cancel, renew, toggle auto-renew, and fetch messages for an existing long rental.

POSTCancel Rental

POST https://bloomsms.com/api/v1/long-rentals/{id}/cancel

Cancel Response

{
  "status": "success",
  "data": {
    "id": 1,
    "status": "cancelled",
    "refund_amount": "3.30",
    "new_balance": "122.80"
  },
  "errors": null
}

POSTRenew Rental

POST https://bloomsms.com/api/v1/long-rentals/{id}/renew

Renew Response

{
  "status": "success",
  "data": {
    "id": 1,
    "status": "active",
    "price_charged": "5.50",
    "new_balance": "114.00"
  },
  "errors": null
}

Parameter	Type	Required	Description
auto_renew	boolean	Yes	true to enable, false to disable

PATCHToggle Auto-Renew

PATCH https://bloomsms.com/api/v1/long-rentals/{id}/auto-renew
Content-Type: application/json

{ "auto_renew": false }

GETGet Messages

GET https://bloomsms.com/api/v1/long-rentals/{id}/messages

Messages Response

{
  "status": "success",
  "data": {
    "rental_id": 1,
    "phone_number": "1234567890",
    "messages": [
      { "text": "Your WhatsApp code is 123456", "sender": "8888", "received_at": "2026-05-05T12:39:32-04:00" }
    ]
  },
  "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.

Example Payload

{
  "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"
  }
}

Introduction

Base API URL

Rate Limits

Response Format

Authentication

Error Codes

Account Balance

Countries

Services & Pricing

Rent Number (Short-Term)

Get / Update Activation Status

Re-Rent Number

Long Rental Prices

Long Rentals

Long Rental Actions

Webhooks

Event: sms.received

Ready to start integrating?

Event: `sms.received`