Introduction
Welcome to the DS SMS HUB API! This API provides access to temporary USA phone numbers for SMS verification. All prices are in Nigerian Naira (NGN), and responses are primarily in plain text, with some actions returning JSON. This service is exclusively for USA-based phone numbers.
Authentication
All requests require a valid api_key passed as
a GET parameter. Obtain your API key from your DS SMS HUB account dashboard.
GET https://dssmshub.com.ng/stubs/handler_api.php?api_key=your_api_key&action=getBalance
Note: Keep your API key secure and avoid exposing it in client-side code.
Available Actions
getBalance
Retrieve your account balance in NGN.
GET /stubs/handler_api.php?api_key={api_key}&action=getBalance
Parameters:
- api_key (required): Your API key.
- action (required): Set to getBalance.
Response:
- Success: ACCESS_BALANCE:{balance}
- Error: See Error Codes.
Example:
GET https://dssmshub.com.ng/stubs/handler_api.php?api_key=abc123&action=getBalance
Response: ACCESS_BALANCE:500.00
getNumber
Request a temporary USA phone number for SMS verification.
GET /stubs/handler_api.php?api_key={api_key}&action=getNumber&service={service}&country=US&max_price={max_price}
Parameters:
- api_key (required): Your API key.
- action (required): Set to getNumber.
- service (required): The service (e.g., google, facebook).
- country (required): Set to US (only USA numbers are supported).
- max_price (optional): Maximum price in NGN. If exceeded, returns MAX_PRICE_EXCEEDED.
Response:
- Success: ACCESS_NUMBER:{rental_id}:{number}
- Header: X-Price: {price_in_ngn}
- Error: See Error Codes.
Example:
GET https://dssmshub.com.ng/stubs/handler_api.php?api_key=abc123&action=getNumber&service=google&country=US&max_price=100
Response: ACCESS_NUMBER:12345:+12025550123
Header: X-Price: 50.00
Notes:
- Maximum 20 active rentals per user.
- Numbers are active for 5 minutes.
- Insufficient balance returns NO_MONEY.
getStatus
Check the status of a purchased number and retrieve SMS.
GET /stubs/handler_api.php?api_key={api_key}&action=getStatus&id={rental_id}&text={text}
Parameters:
- api_key (required): Your API key.
- action (required): Set to getStatus.
- id (required): The rental_id from getNumber.
- text (optional): Set to 1 to include SMS text in headers.
Response:
- Success: ACCESS_SMS:{text} or WAITING
- If text=1, header: X-Text: {sms_content}
- Error: See Error Codes.
Example:
GET https://dssmshub.com.ng/stubs/handler_api.php?api_key=abc123&action=getStatus&id=12345&text=1
Response: ACCESS_SMS:Your code is 123456
Header: X-Text: Your code is 123456
setStatus
Update the status of a purchased number.
GET /stubs/handler_api.php?api_key={api_key}&action=setStatus&id={rental_id}&status={status}
Parameters:
- api_key (required): Your API key.
- action (required): Set to setStatus.
- id (required): The rental_id from getNumber.
- status (required): 6 (done) or 8 (cancel).
Response:
- Success: ACCESS_DONE or ACCESS_CANCEL
- Error: See Error Codes.
Example:
GET https://dssmshub.com.ng/stubs/handler_api.php?api_key=abc123&action=setStatus&id=12345&status=8
Response: ACCESS_CANCEL
Notes:
- Canceling (status=8) refunds the price to your balance.
getPrices
Retrieve pricing for USA services in NGN.
GET /stubs/handler_api.php?api_key={api_key}&action=getPrices
Parameters:
- api_key (required): Your API key.
- action (required): Set to getPrices.
Response:
- Success: JSON with prices in NGN.
- Error: See Error Codes.
- Content-Type: application/json
Example:
GET https://dssmshub.com.ng/stubs/handler_api.php?api_key=abc123&action=getPrices
Response: {
"google": {"US": {"price": 50.00}},
"facebook": {"US": {"price": 45.00}}
}
getPricesVerification
Retrieve pricing for USA verification services in NGN.
GET /stubs/handler_api.php?api_key={api_key}&action=getPricesVerification
Parameters:
- api_key (required): Your API key.
- action (required): Set to getPricesVerification.
Response:
- Success: JSON with verification prices in NGN.
- Error: See Error Codes.
- Content-Type: application/json
Example:
GET https://dssmshub.com.ng/stubs/handler_api.php?api_key=abc123&action=getPricesVerification
Response: {
"google": {"price": 50.00},
"facebook": {"price": 45.00}
}
setWebhook
Set a webhook URL for SMS notifications.
GET /stubs/handler_api.php?api_key={api_key}&action=setWebhook&webhook_url={webhook_url}
Parameters:
- api_key (required): Your API key.
- action (required): Set to setWebhook.
- webhook_url (required): HTTPS URL (max 255 characters).
Response:
- Success: ACCESS_WEBHOOK_SET
- Error: See Error Codes.
Example:
GET https://dssmshub.com.ng/stubs/handler_api.php?api_key=abc123&action=setWebhook&webhook_url=https://example.com/webhook
Response: ACCESS_WEBHOOK_SET
getWebhook
Retrieve the set webhook URL.
GET /stubs/handler_api.php?api_key={api_key}&action=getWebhook
Parameters:
- api_key (required): Your API key.
- action (required): Set to getWebhook.
Response:
- Success: ACCESS_WEBHOOK:{url}
- No webhook: NO_WEBHOOK_SET
- Error: See Error Codes.
Example:
GET https://dssmshub.com.ng/stubs/handler_api.php?api_key=abc123&action=getWebhook
Response: ACCESS_WEBHOOK:https://example.com/webhook
Error Codes
| Error Code | HTTP Status | Description |
|---|---|---|
BAD_KEY |
400, 401 | Invalid or missing API key. |
BAD_ACTION |
400 | Invalid or missing action parameter. |
NO_MONEY |
400 | Insufficient balance for purchase. |
TOO_MANY_ACTIVE_RENTALS |
400 | Reached limit of 20 active rentals. |
MAX_PRICE_EXCEEDED |
400 | Price exceeds specified max_price. |
NO_ACTIVATION |
400 | Invalid or non-existent rental ID. |
INVALID_WEBHOOK_URL |
400 | Invalid webhook URL. |
HTTPS_REQUIRED |
400 | Webhook URL must use HTTPS. |
WEBHOOK_URL_TOO_LONG |
400 | Webhook URL exceeds 255 characters. |
USER_NOT_FOUND |
404 | User not found in database. |
INTERNAL_ERROR |
500 | Server-side error (logged). |
BACKEND_ERROR |
500 | Backend provider error. |
DATABASE_ERROR |
500 | Database operation failed. |
Webhook Notifications
If a webhook is set, the API sends POST requests to the specified HTTPS URL when an SMS is received. The payload typically includes:
{
"rental_id": "12345",
"number": "+12025550123",
"service": "google",
"text": "Your verification code is 123456",
"received_at": "2025-10-27 12:30:00"
}
Recommendations:
- Ensure your webhook endpoint is secure and validates requests.
- Respond with a
200 OKstatus. - Handle duplicate notifications gracefully.
Example Usage
Below is a Python example to get a balance, request a USA number, and check its status.
import requests
BASE_URL = "https://dssmshub.com.ng/stubs/handler_api.php"
API_KEY = "your_api_key"
# Get balance
response = requests.get(f"{BASE_URL}?api_key={API_KEY}&action=getBalance")
if response.text.startswith("ACCESS_BALANCE:"):
balance = float(response.text.split(":")[1])
print(f"Balance: {balance} NGN")
else:
print(f"Error: {response.text}")
# Request a USA number
response = requests.get(f"{BASE_URL}?api_key={API_KEY}&action=getNumber&service=google&country=US&max_price=100")
if response.text.startswith("ACCESS_NUMBER:"):
rental_id, number = response.text.split(":")[1:3]
price = float(response.headers.get("X-Price", 0))
print(f"Number: {number}, Rental ID: {rental_id}, Price: {price} NGN")
else:
print(f"Error: {response.text}")
# Check SMS status
response = requests.get(f"{BASE_URL}?api_key={API_KEY}&action=getStatus&id={rental_id}&text=1")
if response.text.startswith("ACCESS_SMS:"):
sms_text = response.headers.get("X-Text", "No SMS")
print(f"SMS: {sms_text}")
else:
print(f"Status: {response.text}")
Example Usage
Below is a PHP example using cURL to get balance, request a USA number, and check SMS status.
"CURL Error", "headers" => []];
$header_size = curl_getinfo($ch, CURLINFO_HEADER_SIZE);
$headers = substr($response, 0, $header_size);
$body = substr($response, $header_size);
curl_close($ch);
$parsed = [];
foreach (explode("\r\n", $headers) as $line) {
if (strpos($line, ":") !== false) {
list($k, $v) = explode(":", $line, 2);
$parsed[trim($k)] = trim($v);
}
}
return ["body" => $body, "headers" => $parsed];
}
// Get Balance
$url = "$base_url?api_key=$api_key&action=getBalance";
$result = apiRequest($url);
if (strpos($result["body"], "ACCESS_BALANCE:") === 0) {
$balance = substr($result["body"], 15);
echo "Balance: $balance NGN\n";
} else {
echo "Error: " . $result["body"];
}
// Request USA Number
$url = "$base_url?api_key=$api_key&action=getNumber&service=google&country=US&max_price=100";
$result = apiRequest($url);
if (strpos($result["body"], "ACCESS_NUMBER:") === 0) {
$parts = explode(":", $result["body"]);
$id = $parts[1]; $num = $parts[2]; $price = $result["headers"]["X-Price"] ?? 0;
echo "Number: $num, ID: $id, Price: $price NGN\n";
// Poll for SMS
$attempts = 0;
while ($attempts++ < 30) {
$surl = "$base_url?api_key=$api_key&action=getStatus&id=$id&text=1";
$res = apiRequest($surl);
if (strpos($res["body"], "ACCESS_SMS:") === 0) {
echo "SMS: " . ($res["headers"]["X-Text"] ?? "Received") . "\n";
break;
} elseif (strpos($res["body"], "STATUS_WAIT") === 0) {
sleep(10);
} else {
echo "Status: " . $res["body"] . "\n";
break;
}
}
} else {
echo "Error: " . $result["body"];
}
?>'); ?>
Support
For assistance, contact us at support@dssmshub.com.ng. Include your API key and issue details.