Logo

DS SMS HUB API

DS SMS HUB API Documentation

Seamlessly integrate with our API to access temporary USA phone numbers for SMS verification. All prices in NGN, with responses in plain text or JSON.

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 OK status.
  • 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.