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 duration (1, 3, 7, 14, 30, 90, or 365 days).

2

Rent Number — Rent a number. You get an activation_id, phone number, and rental period. The number is immediately active.

3

Check Status — Poll GET /api/sms/status with your activation_id to check for incoming SMS codes. All received messages appear automatically.

4

Extend (optional) — If you need more time, call the extend endpoint to add more days to your rental. Extensions are charged separately and are not refundable.

5

Refund (optional) — If the number didn't work, you can refund the initial rental within the refund window shown in the rent response.

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://submall.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://submall.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://submall.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 — Verification (waiting for code)

{
    "success": true,
    "data": {
        "activation_id": "123456789",
        "phone_number": "+12025551234",
        "service_name": "Telegram",
        "country_name": "United States",
        "status": "waiting",
        "created_at": "2025-01-15 10:30:00"
    }
}

Success Response — Verification (code received)

{
    "success": true,
    "data": {
        "activation_id": "123456789",
        "phone_number": "+12025551234",
        "service_name": "Telegram",
        "country_name": "United States",
        "status": "completed",
        "sms_code": "54321",
        "created_at": "2025-01-15 10:30:00"
    }
}

Success Response — Rental (waiting for code)

{
    "success": true,
    "data": {
        "activation_id": "abc123",
        "phone_number": "+12025551234",
        "service_name": "Telegram",
        "status": "active",
        "sms_code": null,
        "full_text": null,
        "rental_info": {
            "rental_type": "rental",
            "ends_at": "2025-01-22T10:30:00Z",
            "days_remaining": 7,
            "can_refund": true,
            "refundable_until": "2025-01-15T12:30:00Z"
        }
    }
}

Success Response — Rental (code received)

{
    "success": true,
    "data": {
        "activation_id": "abc123",
        "phone_number": "+12025551234",
        "service_name": "Telegram",
        "status": "active",
        "sms_code": "54321",
        "full_text": "Your Telegram code is 54321",
        "rental_info": {
            "rental_type": "rental",
            "ends_at": "2025-01-22T10:30:00Z",
            "days_remaining": 7,
            "can_refund": false,
            "refundable_until": "2025-01-15T12:30:00Z"
        }
    }
}

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://submall.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

Get Rental Price

GET /api/sms/rental/price

Check the price for renting an SMS number for a specified duration. Only fixed day values are accepted.

Parameters

Parameter	Type	Required	Description
service_code	string	Required	Service code from the services endpoint
days	integer	Optional	Rental duration. Allowed: `1`, `3`, `7`, `14`, `30`, `90`, `365`. Default: `1`

Success Response

{
    "success": true,
    "data": {
        "service_code": "google",
        "service_name": "Google",
        "days": 7,
        "duration": "sevenDay",
        "total_price": 4500.00,
        "country_name": "United States"
    }
}

Try It

API Key

Service Code

Days

Rent SMS Number

POST /api/sms/rental/rent

Rent a phone number for a specified duration. The number is immediately active and can receive SMS messages throughout the rental period. No wakeup step needed.

Parameters

Parameter	Type	Required	Description
service_code	string	Required	Service code from the services endpoint
days	integer	Optional	Allowed: `1`, `3`, `7`, `14`, `30`, `90`, `365`. Default: `1`

Success Response

{
    "success": true,
    "data": {
        "activation_id": "abc123-def456",
        "phone_number": "+12025559876",
        "service_name": "Google",
        "country_name": "United States",
        "amount_paid": 4500.00,
        "status": "active",
        "rental_info": {
            "days": 7,
            "duration": "sevenDay",
            "start_date": "2026-03-07 14:30:00",
            "end_date": "2026-03-14 14:30:00",
            "can_refund": true,
            "refundable_until": "2026-03-07T14:45:00.000Z"
        }
    }
}

Try It (Charges your balance)

API Key

Service Code

Days

Extend Rental Duration

POST /api/sms/rental/extend

Add more time to an active rental. Your balance will be charged for the extension. Extensions are not refundable.

Extensions cannot be refunded. Make sure you need the extra time before extending.

Parameters

Parameter	Type	Required	Description
activation_id	string	Required	The activation ID from the rent response
days	integer	Required	Extension duration. Allowed: `1`, `3`, `7`, `14`, `30`, `90`, `365`

Success Response

{
    "success": true,
    "data": {
        "activation_id": "abc123-def456",
        "phone_number": "+12025559876",
        "service_name": "Google",
        "extension_days": 7,
        "amount_charged": 4500.00,
        "message": "Rental extended by 7 days. Extensions are not refundable.",
        "rental_info": {
            "days": 14,
            "start_date": "2026-03-07 14:30:00",
            "end_date": "2026-03-21 14:30:00",
            "days_remaining": 14
        }
    }
}

Try It (Charges your balance — not refundable)

API Key

Activation ID

Days

Refund Rental

POST /api/sms/rental/refund

Refund an active rental and get your balance back. Only works within the refund window shown in the rent response (refundable_until). Extensions are never refundable.

Parameters

Parameter	Type	Required	Description
activation_id	string	Required	The activation ID of the rental to refund

Success Response

{
    "success": true,
    "message": "Rental refunded successfully",
    "data": {
        "activation_id": "abc123-def456",
        "refund_amount": 4500.00,
        "refund_reference": "SMS_RENTAL_REFUND_1709850000_42_A1B2C3"
    }
}

Error Response (refund window expired)

{
    "success": false,
    "message": "Refund window has expired. This rental is no longer refundable.",
    "error_code": "REFUND_ERROR"
}

Try It (Will refund the rental)

API Key

Activation ID

SMS API Documentation

Authentication

Usage Flow

One-Time SMS Purchase

Rental SMS Flow

Error Handling

Get Balance

Parameters

Example Request

Example Response

Try It

Get Services

Parameters

Example Response

Try It

Check Price

Parameters

Example Request

Success Response

Try It

Buy SMS Number

Parameters

Example Request

Success Response

Try It (Charges your balance)

Check SMS Status

Parameters

Success Response — Verification (waiting for code)

Success Response — Verification (code received)

Success Response — Rental (waiting for code)

Success Response — Rental (code received)

Try It

Cancel & Refund

Parameters

Example Request

Success Response

Try It (Will cancel the number)

SMS Rental Endpoints

Get Rental Price

Parameters

Success Response

Try It

Rent SMS Number

Parameters

Success Response

Try It (Charges your balance)

Extend Rental Duration

Parameters

Success Response

Try It (Charges your balance — not refundable)

Refund Rental

Parameters

Success Response

Error Response (refund window expired)

Try It (Will refund the rental)