REST API Documentation – Soft Viral Boost

API Quickstart

The Soft Viral Boost REST API uses standard HTTP response codes, JSON payloads, and Bearer token authorization. You can test directly against the live environment.

Base Production Endpoint

https://softviralboost.com.ng/api/v2

Automated 3-Step Verification Cycle

Order Number: Send POST /api/v2/order with desired country (e.g. us or gb) and service (e.g. whatsapp). Receive back the phone number and order ID.
Poll Live SMS: Call GET /api/v2/order/{order_id}/poll every 3–5 seconds until SMS status changes to RECEIVED and contains the OTP code.
Cancel & Refund: If no SMS arrives, cancel within 20 minutes via POST /api/v2/order/{order_id}/cancel for an immediate 100% wallet refund.

Authentication

Authenticate your requests by including your secret API token in the Authorization header as a Bearer token.

HTTP Request Header

Authorization: Bearer svb_live_YOUR_API_KEY_HERE

Alternatively, you can pass your API key as a query parameter: ?api_key=svb_live_YOUR_API_KEY_HERE

GET /countries Global Catalog

Retrieve the catalog of 100+ supported countries, ISO codes, international dial codes, flags, and base SMS rates.

curl -X GET "https://softviralboost.com.ng/api/v2/countries" \
  -H "Authorization: Bearer svb_live_YOUR_API_KEY_HERE"

import requests

url = "https://softviralboost.com.ng/api/v2/countries"
headers = {"Authorization": "Bearer svb_live_YOUR_API_KEY_HERE"}
response = requests.get(url, headers=headers)
print(response.json())

const res = await fetch("https://softviralboost.com.ng/api/v2/countries", {
  headers: { "Authorization": "Bearer svb_live_YOUR_API_KEY_HERE" }
});
const data = await res.json();
console.log(data);

<?php
$ch = curl_init("https://softviralboost.com.ng/api/v2/countries");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, ["Authorization: Bearer svb_live_YOUR_API_KEY_HERE"]);
$response = json_decode(curl_exec($ch), true);
curl_close($ch);
print_r($response);

200 OK Response:

{
  "status": "success",
  "code": 200,
  "count": 73,
  "timestamp": "2026-09-08 00:00:00",
  "countries": [
    {
      "id": 187,
      "code": "us",
      "iso": "USA",
      "name": "United States",
      "dial": "+1",
      "flag": "https://flagcdn.com/w40/us.png",
      "network": "Direct USA Route",
      "base_rate": 0.25
    },
    {
      "id": 16,
      "code": "gb",
      "iso": "GBR",
      "name": "United Kingdom",
      "dial": "+44",
      "flag": "https://flagcdn.com/w40/gb.png",
      "network": "Direct Global Route",
      "base_rate": 0.30
    },
    {
      "id": 19,
      "code": "ng",
      "iso": "NGA",
      "name": "Nigeria",
      "dial": "+234",
      "flag": "https://flagcdn.com/w40/ng.png",
      "network": "Direct Global Route",
      "base_rate": 0.18
    }
  ]
}

GET /services?country={code} USA Dedicated Route Global Tier-1 Route

Fetch available services, live available number stock count, and price per SMS for a specified country in Nigerian Naira (NGN).

Parameter	Type	Status	Description
country	string	Required	ISO-2 code (e.g. `us` for USA, `gb` for UK, `ng` for Nigeria)

curl -X GET "https://softviralboost.com.ng/api/v2/services?country=us" \
  -H "Authorization: Bearer svb_live_YOUR_API_KEY_HERE"

import requests

url = "https://softviralboost.com.ng/api/v2/services?country=us"
headers = {"Authorization": "Bearer svb_live_YOUR_API_KEY_HERE"}
response = requests.get(url, headers=headers)
print(response.json())

const res = await fetch("https://softviralboost.com.ng/api/v2/services?country=us", {
  headers: { "Authorization": "Bearer svb_live_YOUR_API_KEY_HERE" }
});
const data = await res.json();
console.log(data);

<?php
$ch = curl_init("https://softviralboost.com.ng/api/v2/services?country=us");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, ["Authorization: Bearer svb_live_YOUR_API_KEY_HERE"]);
$response = json_decode(curl_exec($ch), true);
curl_close($ch);
print_r($response);

200 OK Response:

{
  "status": "success",
  "code": 200,
  "country": "us",
  "country_name": "United States",
  "network": "Direct USA Route",
  "currency": "NGN",
  "count": 242,
  "services": [
    {
      "code": "whatsapp",
      "name": "WhatsApp",
      "cost_usd": 0.45,
      "cost": 594.89,
      "cost_formatted": "₦594.89",
      "stock": 4820,
      "network": "Direct USA Route",
      "country": "us"
    },
    {
      "code": "telegram",
      "name": "Telegram",
      "cost_usd": 0.38,
      "cost": 502.35,
      "cost_formatted": "₦502.35",
      "stock": 3190,
      "network": "Direct USA Route",
      "country": "us"
    }
  ]
}

POST /order USA Dedicated Route Global Carrier Hub

Purchase an instant disposable virtual SIM number. If country=us, order is fulfilled via our dedicated high-deliverability USA carrier routes. For all other countries, order is automatically routed to our global telecom carrier network. Cost is deducted from your wallet balance.

Parameter	Type	Status	Description
country	string	Optional	Country code (e.g. `us`, `gb`, `ng`). Default is `us`.
service	string	Required	Service slug or code (e.g. `whatsapp`, `telegram`, `google`).

curl -X POST "https://softviralboost.com.ng/api/v2/order" \
  -H "Authorization: Bearer svb_live_YOUR_API_KEY_HERE" \
  -H "Content-Type: application/json" \
  -d '{"country": "us", "service": "whatsapp"}'

import requests

url = "https://softviralboost.com.ng/api/v2/order"
headers = {
    "Authorization": "Bearer svb_live_YOUR_API_KEY_HERE",
    "Content-Type": "application/json"
}
payload = {"country": "us", "service": "whatsapp"}
response = requests.post(url, json=payload, headers=headers)
print(response.json())

const res = await fetch("https://softviralboost.com.ng/api/v2/order", {
  method: "POST",
  headers: {
    "Authorization": "Bearer svb_live_YOUR_API_KEY_HERE",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({ country: "us", service: "whatsapp" })
});
const data = await res.json();
console.log(data);

<?php
$payload = json_encode(["country" => "us", "service" => "whatsapp"]);
$ch = curl_init("https://softviralboost.com.ng/api/v2/order");
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, $payload);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
  "Authorization: Bearer svb_live_YOUR_API_KEY_HERE",
  "Content-Type: application/json"
]);
$response = json_decode(curl_exec($ch), true);
curl_close($ch);
print_r($response);

200 OK Response:

{
  "status": "success",
  "code": 200,
  "order_id": "ORD-7DF81B4C",
  "provider_order_id": "18492041",
  "phone_number": "+14158904821",
  "service": "whatsapp",
  "service_name": "WhatsApp",
  "country": "us",
  "country_name": "United States",
  "network": "Direct USA Route",
  "cost": 594.89,
  "cost_formatted": "₦594.89",
  "balance_remaining": 4405.11,
  "balance_remaining_formatted": "₦4,405.11",
  "currency": "NGN",
  "expires_in_seconds": 1200,
  "created_at": "2026-09-08 00:01:15"
}

GET /order/{order_id}/poll

Poll the live status of an order. When an SMS arrives from the carrier network, status becomes RECEIVED with sms_code and full sms_text.

curl -X GET "https://softviralboost.com.ng/api/v2/order/ORD-7DF81B4C/poll" \
  -H "Authorization: Bearer svb_live_YOUR_API_KEY_HERE"

import requests

url = "https://softviralboost.com.ng/api/v2/order/ORD-7DF81B4C/poll"
headers = {"Authorization": "Bearer svb_live_YOUR_API_KEY_HERE"}
response = requests.get(url, headers=headers)
print(response.json())

const res = await fetch("https://softviralboost.com.ng/api/v2/order/ORD-7DF81B4C/poll", {
  headers: { "Authorization": "Bearer svb_live_YOUR_API_KEY_HERE" }
});
const data = await res.json();
console.log(data);

<?php
$ch = curl_init("https://softviralboost.com.ng/api/v2/order/ORD-7DF81B4C/poll");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, ["Authorization: Bearer svb_live_YOUR_API_KEY_HERE"]);
$response = json_decode(curl_exec($ch), true);
curl_close($ch);
print_r($response);

200 OK Response (Code Received):

{
  "status": "success",
  "code": 200,
  "order_id": "ORD-7DF81B4C",
  "provider_order_id": "18492041",
  "phone_number": "+14158904821",
  "sms_status": "RECEIVED",
  "sms_code": "849201",
  "sms_text": "Your WhatsApp verification code is 849-201",
  "is_final": true,
  "service": "WhatsApp",
  "country": "us"
}

POST /order/{order_id}/cancel

Cancel an active order that has not yet received an SMS code. Cancels the active number with the telecom carrier and immediately credits 100% of the cost back to your account wallet.

curl -X POST "https://softviralboost.com.ng/api/v2/order/ORD-7DF81B4C/cancel" \
  -H "Authorization: Bearer svb_live_YOUR_API_KEY_HERE"

import requests

url = "https://softviralboost.com.ng/api/v2/order/ORD-7DF81B4C/cancel"
headers = {"Authorization": "Bearer svb_live_YOUR_API_KEY_HERE"}
response = requests.post(url, headers=headers)
print(response.json())

const res = await fetch("https://softviralboost.com.ng/api/v2/order/ORD-7DF81B4C/cancel", {
  method: "POST",
  headers: { "Authorization": "Bearer svb_live_YOUR_API_KEY_HERE" }
});
const data = await res.json();
console.log(data);

<?php
$ch = curl_init("https://softviralboost.com.ng/api/v2/order/ORD-7DF81B4C/cancel");
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, ["Authorization: Bearer svb_live_YOUR_API_KEY_HERE"]);
$response = json_decode(curl_exec($ch), true);
curl_close($ch);
print_r($response);

200 OK Response:

{
  "status": "success",
  "code": 200,
  "message": "Order cancelled successfully. ₦594.89 has been refunded to your wallet.",
  "order_id": "ORD-7DF81B4C",
  "refund_amount": 594.89,
  "refund_amount_formatted": "₦594.89",
  "balance": 5000.00,
  "balance_formatted": "₦5,000.00",
  "currency": "NGN"
}

GET /user/balance

Retrieve the developer's live account details, membership tier, and available wallet balance.

curl -X GET "https://softviralboost.com.ng/api/v2/user/balance" \
  -H "Authorization: Bearer svb_live_YOUR_API_KEY_HERE"

import requests

url = "https://softviralboost.com.ng/api/v2/user/balance"
headers = {"Authorization": "Bearer svb_live_YOUR_API_KEY_HERE"}
response = requests.get(url, headers=headers)
print(response.json())

const res = await fetch("https://softviralboost.com.ng/api/v2/user/balance", {
  headers: { "Authorization": "Bearer svb_live_YOUR_API_KEY_HERE" }
});
const data = await res.json();
console.log(data);

<?php
$ch = curl_init("https://softviralboost.com.ng/api/v2/user/balance");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, ["Authorization: Bearer svb_live_YOUR_API_KEY_HERE"]);
$response = json_decode(curl_exec($ch), true);
curl_close($ch);
print_r($response);

200 OK Response:

{
  "status": "success",
  "code": 200,
  "timestamp": "2026-09-08 00:02:10",
  "user": {
    "id": 42,
    "name": "Alex Morgan",
    "email": "developer@example.com",
    "role": "user",
    "member_since": "2025-11-20"
  },
  "balance": 5000.00,
  "balance_formatted": "₦5,000.00",
  "currency": "NGN",
  "total_otp_used": 142
}

HTTP Error Status Codes

Standard HTTP status codes returned by the API during exception states.

Code	Name	Meaning & Solution
200 OK	Success	Request processed and fulfilled successfully.
400 Bad Request	Validation Error	Missing required parameters (e.g. service, order_id).
401 Unauthorized	Invalid Key	Missing or invalid Bearer API key in Authorization header.
402 Payment Required	Insufficient Funds	Wallet balance is too low for this purchase. Top up your account.
404 Not Found	Not Found	Invalid endpoint path or order ID does not exist.
500 Server Error	Gateway Error	Upstream telecom provider temporarily unreachable. Retry in a few seconds.

Interactive API Playground

Test live requests directly against our production API endpoints in real-time.

Developer Authorization API Key

Request Template

Developer REST API Documentation

API Quickstart

Automated 3-Step Verification Cycle

Authentication

200 OK Response:

200 OK Response:

200 OK Response:

200 OK Response (Code Received):

200 OK Response:

200 OK Response:

HTTP Error Status Codes

Interactive API Playground