BoostBeast Developer API — Documentation

🌐 Overview

The BoostBeast API lets you programmatically order phone numbers and retrieve SMS/OTP codes. It is designed for developers who want to automate integrations or build tools on top of our platform.

What this API does:
✅ Provide fresh phone numbers from multiple countries
✅ Return received SMS/OTP codes for those numbers
✅ Check account balance and available stock

What this API does NOT provide:
❌ Session files (.session)
❌ Cookies or login tokens
❌ Exported accounts or tdata archives

The API only delivers: Phone Number → SMS Code. Nothing else.

API Discount

All orders placed through the API automatically receive a 5% discount off standard retail prices. No coupon codes needed.

🔑 Authentication

Every API request must include your API key in the Authorization header using Bearer token format:

Authorization: Bearer tgx_live_your_api_key_here

Security: Never expose your API key in client-side code, public repositories, or logs. If your key is compromised, regenerate it immediately from the Telegram bot.

How to Get Your API Key

Open the @YourBotUsername on Telegram
Type /api to open the Developer API Dashboard
Tap ➕ Generate Key
Copy the key shown — it's only displayed once
Use it in your requests as shown above

API keys are managed exclusively through the Telegram bot. There is no web-based key management portal. You can enable/disable or regenerate your key at any time via /api in the bot.

🚀 Quick Start

Make your first API call in under 60 seconds. Replace YOUR_API_KEY with your actual key.

curl https://boostbeast.xyz/v1/account \
  -H "Authorization: Bearer YOUR_API_KEY"

import requests

API_KEY = "YOUR_API_KEY"
BASE_URL = "https://boostbeast.xyz/v1"
HEADERS = {"Authorization": f"Bearer {API_KEY}"}

r = requests.get(f"{BASE_URL}/account", headers=HEADERS)
print(r.json())

const API_KEY = "YOUR_API_KEY";
const BASE_URL = "https://boostbeast.xyz/v1";
const HEADERS = { Authorization: `Bearer ${API_KEY}` };

const res = await fetch(`${BASE_URL}/account`, { headers: HEADERS });
const data = await res.json();
console.log(data);

🔗 Base URL

https://boostbeast.xyz/v1

All API endpoints are prefixed with this base URL. All requests and responses use application/json.

Response Format

Every response follows this consistent schema:

{
  "success": true,
  "data": { ... },
  "message": "Success"
}

{
  "success": false,
  "error": {
    "code": "INVALID_API_KEY",
    "message": "The provided API key is invalid."
  }
}

📊 Endpoints

GET /v1/account Get Balance

Returns your account balance, API discount, and current mode (live or mock).

Headers

Header	Type	Description
Authorization	string	required Bearer token with your API key

Example Request

curl https://boostbeast.xyz/v1/account \
  -H "Authorization: Bearer YOUR_API_KEY"

import requests
r = requests.get("https://boostbeast.xyz/v1/account",
    headers={"Authorization": "Bearer YOUR_API_KEY"})
print(r.json())

const r = await fetch("https://boostbeast.xyz/v1/account", {
  headers: { Authorization: "Bearer YOUR_API_KEY" }
});
console.log(await r.json());

Example Response

{
  "success": true,
  "data": {
    "user_id": 123456789,
    "username": "your_username",
    "balance_usd": 45.20,
    "currency": "USD",
    "api_discount_pct": 5.0,
    "mock_mode_enabled": false,
    "created_at": "2025-01-01T00:00:00"
  },
  "message": "Success"
}

Error Responses

// 401 — Invalid key
{ "success": false, "error": { "code": "INVALID_API_KEY", "message": "The provided API key is invalid." } }

// 401 — API disabled
{ "success": false, "error": { "code": "API_DISABLED", "message": "Your API key is disabled. Enable it via /api in the bot." } }

GET /v1/countries Get Countries

Returns a list of all available countries with live stock counts and API-discounted prices.

Headers

Header	Type	Description
Authorization	string	required Bearer token

Example Request

curl https://boostbeast.xyz/v1/countries \
  -H "Authorization: Bearer YOUR_API_KEY"

import requests
r = requests.get("https://boostbeast.xyz/v1/countries",
    headers={"Authorization": "Bearer YOUR_API_KEY"})
for c in r.json()["data"]["countries"]:
    print(c["country_code"], c["stock"], c["price_usd"])

const r = await fetch("https://boostbeast.xyz/v1/countries", {
  headers: { Authorization: "Bearer YOUR_API_KEY" }
});
const { data } = await r.json();
console.log(data.countries);

Example Response

{
  "success": true,
  "data": {
    "countries": [
      { "country_code": "IN", "name": "India",          "flag": "🇮🇳", "stock": 450, "price_usd": 0.28 },
      { "country_code": "US", "name": "United States",  "flag": "🇺🇸", "stock": 312, "price_usd": 0.95 },
      { "country_code": "PK", "name": "Pakistan",       "flag": "🇵🇰", "stock": 211, "price_usd": 0.19 },
      { "country_code": "GB", "name": "United Kingdom", "flag": "🇬🇧", "stock": 89,  "price_usd": 1.14 }
    ],
    "total": 4
  },
  "message": "Success"
}

Response Fields

Field	Type	Description
country_code	string	ISO 3166 country code (e.g. `IN`, `US`)
name	string	Country name
flag	string	Country flag emoji
stock	integer	Number of numbers currently available
price_usd	float	Price per number in USD (5% API discount already applied)

POST /v1/orders Get Number

Request one or more phone numbers for a given country. Returns phone numbers and hash codes used to poll for SMS codes.

Headers

Header	Type	Description
Authorization	string	required Bearer token
Content-Type	string	required `application/json`

Request Body

Field	Type	Description
country_code	string	required Country code from `/v1/countries` (e.g. `IN`)
quantity	integer	optional Numbers to request (1–50). Default: `1`

Example Request

curl -X POST https://boostbeast.xyz/v1/orders \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"country_code": "IN", "quantity": 1}'

import requests
r = requests.post("https://boostbeast.xyz/v1/orders",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
    json={"country_code": "IN", "quantity": 1})
order = r.json()["data"]
print("Order ID:", order["order_id"])
print("Phone:", order["items"][0]["phone"])

const r = await fetch("https://boostbeast.xyz/v1/orders", {
  method: "POST",
  headers: {
    Authorization: "Bearer YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ country_code: "IN", quantity: 1 }),
});
const { data } = await r.json();
console.log("Order ID:", data.order_id);
console.log("Phone:", data.items[0].phone);

Example Response

{
  "success": true,
  "data": {
    "order_id": "9f4a2c81-...",
    "order_number": "API-A9F23B",
    "country_code": "IN",
    "quantity": 1,
    "price_usd": 0.28,
    "discount_applied": "5% (API)",
    "items": [
      {
        "phone": "+919876543210",
        "hash_code": "5wVFjE3tXVmEl7Fq",
        "status": "WAITING_FOR_SMS"
      }
    ],
    "mock_mode": false,
    "created_at": "2025-08-01T12:00:00"
  },
  "message": "Order created successfully."
}

Error Responses

// 404 — Country not available
{ "success": false, "error": { "code": "COUNTRY_NOT_FOUND", "message": "Country 'XX' is not available." } }

// 400 — Out of stock
{ "success": false, "error": { "code": "OUT_OF_STOCK", "message": "Insufficient stock for 'US'. Available: 0." } }

// 402 — Insufficient balance
{ "success": false, "error": { "code": "INSUFFICIENT_BALANCE", "message": "Required: $0.28, Available: $0.10" } }

GET /v1/orders/{order_id} Order Status

Retrieve the status and details of an existing order using the order_id returned when the order was created.

Path Parameters

Parameter	Type	Description
order_id	string	required UUID from `POST /v1/orders` response

Example Request

curl https://boostbeast.xyz/v1/orders/9f4a2c81-... \
  -H "Authorization: Bearer YOUR_API_KEY"

order_id = "9f4a2c81-..."
r = requests.get(f"https://boostbeast.xyz/v1/orders/{order_id}",
    headers={"Authorization": "Bearer YOUR_API_KEY"})
print(r.json())

const orderId = "9f4a2c81-...";
const r = await fetch(`https://boostbeast.xyz/v1/orders/${orderId}`, {
  headers: { Authorization: "Bearer YOUR_API_KEY" }
});
console.log(await r.json());

Example Response

{
  "success": true,
  "data": {
    "order_id": "9f4a2c81-...",
    "order_number": "API-A9F23B",
    "status": "PROCESSING",
    "country_code": "IN",
    "quantity": 1,
    "price_usd": 0.28,
    "items": [
      { "phone": "+919876543210", "hash_code": "5wVFjE3tXVmEl7Fq", "status": "WAITING_FOR_SMS" }
    ],
    "mock_mode": false,
    "created_at": "2025-08-01T12:00:00"
  },
  "message": "Success"
}

GET POST /v1/orders/{order_id}/otp Fetch Live SMS / OTP Code

Poll live verification codes for any phone number in an order. Supports both GET (with query parameter ?index=0) and POST (with JSON body {"index": 0}). Returns real-time status and the is_live boolean flag indicating if the session is currently active and awaiting SMS.

Path Parameters

Parameter	Type	Description
order_id	string	required Order UUID or Order Number (e.g., `API-B366E81A`)

Query / Body Parameters

Field	Type	Description
index	integer	optional Phone item index in the order (0-based). Default: `0`

Example Requests

# Option 1: Quick GET request
curl -X GET "https://boostbeast.xyz/v1/orders/API-B366E81A/otp?index=0" \
  -H "Authorization: Bearer tgx_live_YOUR_KEY"

# Option 2: POST request
curl -X POST "https://boostbeast.xyz/v1/orders/API-B366E81A/otp" \
  -H "Authorization: Bearer tgx_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"index": 0}'

import time, requests

order_id = "API-B366E81A"
headers = {"Authorization": "Bearer tgx_live_YOUR_KEY"}

# Poll every 4 seconds until code arrives or session expires
while True:
    res = requests.get(f"https://boostbeast.xyz/v1/orders/{order_id}/otp?index=0", headers=headers)
    data = res.json().get("data", {})
    status = data.get("status")
    
    if status == "RECEIVED":
        print(f"✅ OTP Code: {data['otp']} for phone {data['phone']}")
        break
    elif status == "EXPIRED":
        print("❌ Phone number session has expired.")
        break
    else:
        print(f"⏳ Number is active (is_live: {data.get('is_live')}). Waiting for SMS...")
        time.sleep(4)

const orderId = "API-B366E81A";
const headers = { "Authorization": "Bearer tgx_live_YOUR_KEY" };

const poll = setInterval(async () => {
  const res = await fetch(`https://boostbeast.xyz/v1/orders/${orderId}/otp?index=0`, { headers });
  const { data } = await res.json();
  
  if (data.status === "RECEIVED") {
    console.log(`✅ OTP Code: ${data.otp}`);
    clearInterval(poll);
  } else if (data.status === "EXPIRED") {
    console.log("❌ Number session expired.");
    clearInterval(poll);
  } else {
    console.log(`⏳ Number is active. Awaiting SMS... (is_live: ${data.is_live})`);
  }
}, 4000);

Response — 1. Code Received (🟢 Active)

{
  "success": true,
  "data": {
    "status": "RECEIVED",
    "otp": "58783",
    "phone": "+18142258970",
    "is_live": true,
    "mock_mode": false
  },
  "message": "OTP code received successfully."
}

Response — 2. Awaiting SMS (🟢 Active)

{
  "success": true,
  "data": {
    "status": "WAITING",
    "otp": null,
    "phone": "+18142258970",
    "is_live": true,
    "mock_mode": false
  },
  "message": "Number is active. Waiting for SMS code. Please request the code in Telegram and poll again."
}

Response — 3. Session Closed (🔴 Expired)

{
  "success": true,
  "data": {
    "status": "EXPIRED",
    "otp": "58783",
    "phone": "+18142258970",
    "is_live": false,
    "mock_mode": false
  },
  "message": "This phone number session has expired."
}

🔄 Delivery Flow

The complete lifecycle from requesting a number to receiving the SMS code:

1

Request a Number

POST /v1/orders with your country_code. Balance is deducted immediately.

2

Receive Phone Number

API returns phone number(s) and hash code(s). Share the number with the service you want to verify.

3

Wait for SMS

Use the phone number to trigger an SMS from the service. The number is live and ready.

4

Poll for OTP

POST /v1/orders/{order_id}/otp every 3–5 seconds. Returns status: WAITING until SMS arrives.

5

OTP Received

Response returns status: RECEIVED with the 6-digit OTP code. Use it immediately.

🧪 Mock Mode

Mock Mode lets you test your integration safely without spending real balance or reserving real phone numbers.

Enable Mock Mode
Open the bot → /api → tap 🧪 Enable Mock Mode

What changes in Mock Mode

✅ No balance is deducted from your account
✅ No real phone numbers are reserved or allocated
✅ No real SMS requests are made to the supplier
✅ API returns realistic fake phone numbers and order IDs
✅ OTP endpoint returns a simulated 6-digit code immediately
✅ The same response structure as live mode — easy to switch

Mock Response Example

{
  "success": true,
  "data": {
    "order_id": "MOCK-A1B2C3D4",
    "country_code": "US",
    "items": [
      { "phone": "+11234567", "hash_code": "MOCK_ABC123DEF456", "status": "WAITING_FOR_SMS" }
    ],
    "mock_mode": true
  },
  "message": "Mock order created. No balance deducted."
}

Tip: All mock order IDs start with MOCK-. When you switch back to live mode, simply re-run your code — the logic is identical.

⚠️ Error Codes

All errors follow the standard response schema with a code and message.

Code	HTTP	Description
INVALID_API_KEY	401	The API key does not exist
API_DISABLED	401	Your API key is disabled — enable via /api in bot
UNAUTHORIZED	401	Missing or malformed Authorization header
INSUFFICIENT_BALANCE	402	Account balance too low for the requested order
COUNTRY_NOT_FOUND	404	Country code is invalid or not currently active
OUT_OF_STOCK	400	No numbers available for this country right now
ORDER_NOT_FOUND	404	Order ID not found or belongs to another account
OTP_NOT_READY	503	Error retrieving OTP from supplier — retry
INVALID_INDEX	400	Item index out of range for this order
RATE_LIMIT_EXCEEDED	429	Too many requests — back off and retry
SUPPLIER_ERROR	503	Upstream supplier error — retry after a few seconds
MOCK_MODE_DISABLED	400	Attempted to access a mock order with mock mode off

⏱️ Rate Limits

Each API key is limited to 120 requests per minute across all endpoints combined.

Limit	Value
Requests/minute per key	120 rpm
Max order quantity per request	50

When the limit is exceeded you'll receive a 429 RATE_LIMIT_EXCEEDED error. Implement exponential backoff in your code:

import time, requests

def api_call_with_retry(url, headers, json=None, method="GET", max_retries=5):
    for attempt in range(max_retries):
        r = requests.request(method, url, headers=headers, json=json)
        if r.status_code == 429:
            wait = 2 ** attempt
            print(f"Rate limited. Retrying in {wait}s...")
            time.sleep(wait)
            continue
        return r
    raise Exception("Max retries exceeded")

❓ FAQ

Do I receive session files or account data through the API? ▼

No. The API only provides phone numbers and SMS codes. It does not deliver session files, cookies, tdata archives, or any account credentials. The sole purpose is phone number verification automation.

How long do I have to use the phone number before it expires? ▼

Phone numbers are typically valid for 10–20 minutes from the time of allocation. You should request the OTP as soon as possible after creating the order. Numbers are not rechargeable — each order allocates a fresh number.

What if the OTP never arrives? ▼

If no SMS is received within 10 minutes, the number is considered expired. Create a new order to get a fresh number. We recommend contacting support if this happens frequently.

Is Mock Mode safe for production testing? ▼

Yes. Mock Mode is completely isolated from production. No real numbers are allocated, no supplier API calls are made, and no balance is deducted. Use it freely to test your integration before going live.

Can I have multiple API keys? ▼

Each Telegram account can have one active API key at a time. Regenerating a key immediately invalidates the previous one. If you need multiple keys for different projects, use separate Telegram accounts.

Where do I manage my API key? ▼

All key management (generate, reveal, regenerate, enable/disable, mock mode toggle) is done exclusively through the Telegram bot — type /api to open the Developer Dashboard.