SMS API Documentation

Authentication

All API requests require your API key. You can pass it in two ways:

Option 1 — Authorization Header (Recommended):

Authorization: Bearer YOUR_API_KEY

Option 2 — Request Parameter:

?api_key=YOUR_API_KEY

Log in to auto-fill your API key in the test forms.

Usage Flow

One-Time SMS Purchase

1

Get Services — Fetch available services (WhatsApp, Telegram, etc.)

2

Check Price — Check the price and availability before purchasing.

3

Buy Number — Purchase a number for the chosen service. You receive an activation_id and phone_number.

4

Use the Number — Register/verify on the target service using the phone number.

5

Check Status — Poll the status endpoint until sms_code is returned.

6

Cancel (optional) — If no code arrives, cancel within the allowed window to get a refund.

Rental SMS Flow

1

Check Rental Price — Get pricing for the service and number of days.

2

Rent Number — Rent a number. You get an activation_id and rental period.

3

Wakeup — Activate the number so it can receive SMS messages.

4

Check Status — Poll for the SMS code.

5

Extend (Next Code) — After receiving a code, call extend to prepare for the next one. If it returns waiting, call wakeup again.

6

Repeat 4–5 — Continue checking status and extending for each new code during your rental period.

Error Handling

All errors return this JSON structure with an appropriate HTTP status code:

{
    "success": false,
    "message": "Human-readable error description",
    "error_code": "MACHINE_READABLE_CODE"
}

HTTP Code	Meaning
200	Success
400	Bad request / Business logic error
401	Missing or invalid API key
405	Wrong HTTP method

Get Balance

GET /api/sms/balance

Retrieve your current account balance.

Parameters

No additional parameters required.

Example Request

curl -X GET "https://www.submall.com.ng.teleco.com.ng/api/sms/balance" \
  -H "Authorization: Bearer YOUR_API_KEY"

Example Response

{
    "success": true,
    "data": {
        "balance": 15000.00,
        "currency": "NGN"
    }
}

Try It

API Key

Get Services

GET /api/sms/services

Retrieve the list of available SMS services (e.g., WhatsApp, Telegram, Instagram).

Parameters

No additional parameters required.

Example Response

{
    "success": true,
    "data": {
        "services": [
            { "service_code": "tg", "name": "Telegram" },
            { "service_code": "wa", "name": "WhatsApp" },
            { "service_code": "ig", "name": "Instagram" }
        ],
        "total_count": 3
    }
}

Try It

API Key

Check Price

GET /api/sms/price

Check the price of a one-time SMS number before purchasing. Returns the price in NGN based on your account level.

Parameters

Parameter	Type	Required	Description
service_code	string	Required	Service code from the services endpoint (e.g., `tg`)
country_code	string	Optional	Country code. Default: `187` (United States)

Example Request

curl -X GET "https://www.submall.com.ng.teleco.com.ng/api/sms/price?service_code=tg&country_code=187" \
  -H "Authorization: Bearer YOUR_API_KEY"

Success Response

{
    "success": true,
    "data": {
        "service_code": "tg",
        "country_code": "187",
        "service_name": "Telegram",
        "price": 850.00,
        "available_numbers": 45
    }
}

Try It

API Key

Service Code

Country Code

Buy SMS Number

POST /api/sms/buy

Purchase a one-time SMS number. Your account balance will be charged. Price depends on your account level (smart/vendor/api).

Parameters

Parameter	Type	Required	Description
service_code	string	Required	Service code from the services endpoint (e.g., `tg`)
country_code	string	Optional	Country code. Default: `187` (United States)
max_price	float	Optional	Maximum price in USD. Default: `10.0`

Example Request

curl -X POST "https://www.submall.com.ng.teleco.com.ng/api/sms/buy" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d "service_code=tg&country_code=187"

Success Response

{
    "success": true,
    "data": {
        "activation_id": "123456789",
        "phone_number": "+12025551234",
        "service_name": "Telegram",
        "country_name": "United States",
        "amount_paid": 850.00,
        "transaction_ref": "SMS2_1706345678_42_A1B2C3",
        "balance_after": 14150.00,
        "status": "active"
    }
}

Try It (Charges your balance)

API Key

Service Code

Country Code

Check SMS Status

GET /api/sms/status

Check the status of a purchased or rented number. Poll this endpoint until sms_code appears in the response.

Parameters

Parameter	Type	Required	Description
activation_id	string	Required	The activation ID from buy or rent response

Success Response (waiting for code)

{
    "success": true,
    "data": {
        "activation_id": "123456789",
        "phone_number": "+12025551234",
        "service_name": "Telegram",
        "status": "waiting"
    }
}

Success Response (code received)

{
    "success": true,
    "data": {
        "activation_id": "123456789",
        "phone_number": "+12025551234",
        "service_name": "Telegram",
        "status": "completed",
        "sms_code": "54321",
        "next_action": "extend",
        "next_action_hint": "Call POST /api/sms/rental/extend..."
    }
}

Try It

API Key

Try It

API Key

Activation ID

Cancel & Refund

POST /api/sms/cancel

Cancel an active number and receive a refund to your balance. A cancellation wait period applies after purchase.

Parameters

Parameter	Type	Required	Description
activation_id	string	Required	The activation ID of the number to cancel

Example Request

curl -X POST "https://www.submall.com.ng.teleco.com.ng/api/sms/cancel" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d "activation_id=123456789"

Success Response

{
    "success": true,
    "message": "Number cancelled successfully",
    "data": {
        "activation_id": "123456789",
        "refund_amount": 850.00,
        "refund_reference": "SMS_REFUND_65A1B2C3D4E5F"
    }
}

Try It (Will cancel the number)

API Key

Activation ID

SMS Rental Endpoints

Get Rental Price

GET /api/sms/rental/price

Check the price for renting an SMS number for a specified number of days. Price includes both the initial number cost and the daily rental fee.

Parameters

Parameter	Type	Required	Description
service_code	string	Required	Service code (e.g., `tg`)
country_code	string	Optional	Default: `187` (United States)
days	integer	Optional	Rental duration in days (1–365). Default: `1`

Success Response

{
    "success": true,
    "data": {
        "service_code": "tg",
        "country_code": "187",
        "service_name": "Telegram",
        "days": 7,
        "initial_number_cost": 850.00,
        "daily_price": 456.00,
        "total_price": 3192.00,
        "combined_total": 4042.00,
        "available_numbers": 45
    }
}

Try It

API Key

Service Code

Country

Days

Rent SMS Number

POST /api/sms/rental/rent

Rent a phone number for a specified number of days. The number can receive multiple SMS codes during the rental period. After receiving a code, call the Extend endpoint to prepare for the next one.

Parameters

Parameter	Type	Required	Description
service_code	string	Required	Service code (e.g., `tg`)
country_code	string	Optional	Default: `187` (United States)
days	integer	Optional	Rental days (1–365). Default: `1`
max_price	float	Optional	Max price in USD. Default: `50.0`

Success Response

{
    "success": true,
    "data": {
        "activation_id": "987654321",
        "phone_number": "+12025559876",
        "service_name": "Telegram",
        "country_name": "United States",
        "amount_paid": 4042.00,
        "status": "active",
        "rental_info": {
            "days": 7,
            "daily_price": 456.00,
            "start_date": "2026-02-27 14:30:00",
            "end_date": "2026-03-06 14:30:00",
            "renewable": true
        }
    }
}

Try It (Charges your balance)

API Key

Service Code

Country

Days

Extend Rental (Next Code)

POST /api/sms/rental/extend

After receiving an SMS code on a rented number, call this endpoint to prepare for the next code. This does not charge your balance — it is included in your rental period. You will receive a new activation_id — use it for all subsequent status checks and wakeup calls.

If the response status is "waiting", you must call the Wakeup endpoint with the new activation_id before the number can receive SMS.

Parameters

Parameter	Type	Required	Description
activation_id	string	Required	Current activation ID of the rental

Success Response (ready)

{
    "success": true,
    "data": {
        "activation_id": "111222333",
        "previous_activation_id": "987654321",
        "phone_number": "+12025559876",
        "service_name": "Telegram",
        "status": "ready",
        "next_action": "check_status",
        "message": "Number is ready. Check status to retrieve the SMS code.",
        "rental_info": {
            "rental_days": 7,
            "rental_start": "2026-02-27 14:30:00",
            "rental_end": "2026-03-06 14:30:00",
            "days_remaining": 5
        }
    }
}

Success Response (needs wakeup)

{
    "success": true,
    "data": {
        "activation_id": "111222333",
        "status": "waiting",
        "ready_at": "1709050000",
        "next_action": "wakeup",
        "message": "Number is asleep. Call wakeup endpoint..."
    }
}

Try It

API Key

Activation ID

Wakeup Rental Number

POST /api/sms/rental/wakeup

Activate a rented number so it can receive SMS messages. Required after renting or when the Extend endpoint returns status: "waiting".

Parameters

Parameter	Type	Required	Description
activation_id	string	Required	The activation ID of the rental (use the latest one from extend)

Success Response

{
    "success": true,
    "message": "Rental number activated successfully",
    "data": {
        "activation_id": "111222333",
        "phone_number": "+12025559876",
        "service_name": "Telegram",
        "status": "active"
    }
}

Try It

API Key

Activation ID

Need help? Contact support.