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
getServer1Number Server 1 API
Request a temporary USA phone number specifically from Server 1 (Getatext) for premium verification services.
GET /stubs/handler_api.php?api_key={api_key}&action=getServer1Number&service={service}
Parameters:
- api_key (required): Your DS SMS HUB API key.
- action (required): Set to getServer1Number.
- service (required): The service code (e.g. google, whatsapp, telegram, facebook).
Response:
- Success: ACCESS_NUMBER:{rental_id}:{phone_number}
- Error Responses: NO_BALANCE, NO_NUMBERS, BAD_SERVICE
Example call:
GET https://dssmshub.com.ng/stubs/handler_api.php?api_key=abc123&action=getServer1Number&service=google
Response: ACCESS_NUMBER:200981:+14155552671
💡 Drop-in PHP/cURL Template Available
We have created a ready-to-run PHP integration script for Server 1. You can review and copy it here: server1_integration.php
getServer2Number Server 2 API
Request a virtual phone number specifically from Server 2 (SMSPool). This server supports multiple countries dynamically.
GET /stubs/handler_api.php?api_key={api_key}&action=getServer2Number&service={service}&country={country}
Parameters:
- api_key (required): Your DS SMS HUB API key.
- action (required): Set to getServer2Number.
- service (required): The service code (e.g. google, whatsapp, telegram, facebook).
- country (optional): Country numeric ID (e.g. 1 = United States, 2 = United Kingdom). Defaults to 1.
Response:
- Success: ACCESS_NUMBER:{rental_id}:{phone_number}
- Error Responses: NO_BALANCE, NO_NUMBERS, BAD_SERVICE
Example call:
GET https://dssmshub.com.ng/stubs/handler_api.php?api_key=abc123&action=getServer2Number&service=whatsapp&country=1
Response: ACCESS_NUMBER:392019:+16505559812
💡 Drop-in PHP/cURL Template Available
We have created a ready-to-run PHP integration script for Server 2. You can review and copy it here: server2_integration.php
getServer3Number Server 3 API
Request a temporary USA phone number specifically from Server 3 (Textverified) for secure verification services.
GET /stubs/handler_api.php?api_key={api_key}&action=getServer3Number&service={service}
Parameters:
- api_key (required): Your DS SMS HUB API key.
- action (required): Set to getServer3Number.
- service (required): The service code (e.g. google, whatsapp, telegram, facebook).
Response:
- Success: ACCESS_NUMBER:{rental_id}:{phone_number}
- Error Responses: NO_BALANCE, NO_NUMBERS, BAD_SERVICE
Example call:
GET https://dssmshub.com.ng/stubs/handler_api.php?api_key=abc123&action=getServer3Number&service=telegram
Response: ACCESS_NUMBER:481029:+17025553018
💡 Drop-in PHP/cURL Template Available
We have created a ready-to-run PHP integration script for Server 3. You can review and copy it here: server3_integration.php
getNumber Legacy Integration
Legacy fallback route to request virtual phone numbers. (We recommend using the Server-specific endpoints above for better control).
GET /stubs/handler_api.php?api_key={api_key}&action=getNumber&service={service}&server={server}&country={country}
Parameters:
- api_key (required): Your DS SMS HUB API key.
- action (required): Set to getNumber.
- service (required): The service (e.g., google, facebook).
- server (optional): Server number (1, 2, or 3). Defaults to 1.
- country (optional): Country numeric ID (mainly for Server 2). Defaults to 1.
Response:
- Success: ACCESS_NUMBER:{rental_id}:{phone_number}
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. |
ERROR: IP_BANNED |
403 | IP address explicitly blocked by firewall due to manual ban or abuse. |
ERROR: RATE_LIMIT_EXCEEDED |
429 | Exceeded requests/minute rate limits. Dynamic rate protection triggered. |
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.