Shadow OTP
Login Get Started
RESTful API
Unlimited Requests
No Rate Limits
Free Numbers API

Powerful API Documentation

Complete API reference for Shadow OTP services. Build SMS verification, rental numbers, temporary email, and free number functionality into your applications with our easy-to-use REST APIs.

Get Started View on GitHub
Getting Started

Authentication

All API requests require an API key for authentication. Your API key uniquely identifies your account and should be kept secure.

Get Your API Key

Sign up for a free account to get your API key. No credit card required. You can generate and manage API keys from your dashboard.

GET
/?api_key=YOUR_API_KEY&action=getBalance

Include your API key as a query parameter in every request. The API key must be included in the api_key parameter.

PHP Example 
<?php
$apiKey = 'YOUR_API_KEY';
$url = "https://shadowotp.com/stubs/handler_api.php?api_key=$apiKey&action=getBalance";

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $url);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$response = curl_exec($ch);
curl_close($ch);

echo $response;
?>
Getting Started

Base URLs

Different services use different base endpoints. Choose the appropriate base URL for the API you're using.

SMS OTP API

https://shadowotp.com/stubs/handler_api.php

For temporary phone numbers and SMS verification

Rental Number API

https://shadowotp.com/stubs/rental_handler.php

For long-term number rentals

Temporary Email API

https://shadowotp.com/stubs/email_handler.php

For temporary email addresses

Free Number API

https://shadowotp.com/stubs/free_handler.php

For free phone numbers with lifetime subscription

SMS OTP API

Virtual Numbers API

Purchase temporary phone numbers for one-time SMS verification. Perfect for account verification, testing workflows, and OTP-based authentication.

Understanding Server IDs

Different server IDs (1-4) represent different SMS providers. Each server may have different countries, services, pricing, and availability. Always check the available options for each server before making requests.

GET
/?action=getBalance

Get Balance

Retrieve your account balance in real-time in PKR currency.

Parameter Type Required Description
api_key String Yes Your unique API key
action String Yes Must be "getBalance"
Full URL Example 
GET https://shadowotp.com/stubs/handler_api.php?api_key=YOUR_API_KEY&action=getBalance
Success Response
{ "status": "200", "balance": 1500.00, "currency": "PKR" }
GET
/?action=getCountries

Get Countries

Retrieve all available countries organized by server/provider.

Parameter Type Required Description
api_key String Yes Your API key
action String Yes Must be "getCountries"
server Integer No Server ID (1-4). Empty for all servers.
Full URL Example 
GET https://shadowotp.com/stubs/handler_api.php?api_key=YOUR_API_KEY&action=getCountries&server=1
Success Response
{ "status": "200", "countries": { "1": [ {"code": "0", "name": "Russia"}, {"code": "7", "name": "Kazakhstan"} ], "2": [ {"code": "0", "name": "Russia"}, {"code": "1", "name": "Ukraine"} ] } }
GET
/?action=getServices

Get Services

Get available services and pricing for a specific country and server.

Parameter Type Required Description
api_key String Yes Your API key
action String Yes Must be "getServices"
country String/Integer Yes Country ID (e.g., "0" for Russia)
server Integer Yes Server ID (1-4)
Full URL Example 
GET https://shadowotp.com/stubs/handler_api.php?api_key=YOUR_API_KEY&action=getServices&country=0&server=1
Success Response
{ "status": "200", "services": { "tg": "Telegram - 45 PKR", "wa": "WhatsApp - 60 PKR", "go": "Google - 35 PKR" } }
GET
/?action=getNumber

Get Number

Purchase a temporary phone number to receive SMS verification codes.

Parameter Type Required Description
api_key String Yes Your API key
action String Yes Must be "getNumber"
service String Yes Service ID (e.g., "tg", "wa", "go")
country String/Integer Yes Country ID
server Integer Yes Server ID (1-4)
Full URL Example 
GET https://shadowotp.com/stubs/handler_api.php?api_key=YOUR_API_KEY&action=getNumber&service=tg&country=0&server=1
Success Response
{ "status": "ACCESS_NUMBER", "order_id": "12345678", "phone": "+79001234567", "country": "0", "service": "tg", "price": 45.00, "balance": 1455.00 }
Important

Balance is deducted automatically upon successful purchase. Save the order_id for checking status.

GET
/?action=getStatus

Get Status

Check SMS status and retrieve verification codes for an order. Returns plain text responses.

Parameter Type Required Description
api_key String Yes Your API key
action String Yes Must be "getStatus"
id String/Integer Yes Order ID from getNumber
server Integer Yes Server ID used when purchasing
Full URL Example 
GET https://shadowotp.com/stubs/handler_api.php?api_key=YOUR_API_KEY&action=getStatus&id=12345678&server=1
Code Received
STATUS_OK:123456
Waiting for SMS
STATUS_WAIT_CODE
Polling Strategy

Call this endpoint every 5-10 seconds until you receive STATUS_OK or an error. Typical timeout is 15-20 minutes.

GET
/?action=setStatus

Set Status

Cancel order, request new SMS, or mark as complete.

Parameter Type Required Description
api_key String Yes Your API key
action String Yes Must be "setStatus"
id String/Integer Yes Order ID
status Integer Yes Status code (3=Retry, 6=Complete, 8=Cancel)
server Integer Yes Server ID
3

Request Another SMS

Request a new SMS code if previous one timed out

6

Complete Activation

Mark the order as successfully completed

8

Cancel & Refund

Cancel and refund if no SMS received

Request Another SMS Example 
GET https://shadowotp.com/stubs/handler_api.php?api_key=YOUR_API_KEY&action=setStatus&id=12345678&status=3&server=1
Rental Number API

Rental Numbers API

Rent long-term phone numbers to receive multiple SMS messages over an extended period. Perfect for business accounts and applications requiring extended SMS reception.

GET
/?action=getRentalCountries

Get Rental Countries

List all countries available for long-term number rental.

Parameter Type Required Description
api_key String Yes Your API key
action String Yes Must be "getRentalCountries"
server Integer No Server ID (1-4)
Full URL Example 
GET https://shadowotp.com/stubs/rental_handler.php?api_key=YOUR_API_KEY&action=getRentalCountries&server=1
Success Response
{ "status": "200", "countries": [ {"code": "US", "name": "United States"}, {"code": "UK", "name": "United Kingdom"}, {"code": "PK", "name": "Pakistan"} ] }
GET
/?action=getRentalPricing

Get Rental Pricing

Get available rental durations and pricing for a specific country.

Parameter Type Required Description
api_key String Yes Your API key
action String Yes Must be "getRentalPricing"
country_code String Yes Country code (e.g., "US", "PK")
server Integer No Server ID (1-4)
Full URL Example 
GET https://shadowotp.com/stubs/rental_handler.php?api_key=YOUR_API_KEY&action=getRentalPricing&country_code=US&server=1
Success Response
{ "status": "200", "country_code": "US", "options": [ { "pricing_id": "101", "duration": "24 Hours", "price": 500.00 }, { "pricing_id": "102", "duration": "7 Days", "price": 2500.00 } ] }
GET
/?action=getAvailableRentals

Get Available Rentals

Check real-time stock of rental numbers for a specific country.

Parameter Type Required Description
api_key String Yes Your API key
action String Yes Must be "getAvailableRentals"
country_code String Yes Country code (e.g., "US", "PK")
server Integer No Server ID (1-4)
Full URL Example 
GET https://shadowotp.com/stubs/rental_handler.php?api_key=YOUR_API_KEY&action=getAvailableRentals&country_code=US&server=1
Success Response
{ "status": "200", "country_code": "US", "available": 15 }
GET
/?action=rentNumber

Rent Number

Purchase a long-term rental number using a pricing_id.

Parameter Type Required Description
api_key String Yes Your API key
action String Yes Must be "rentNumber"
pricing_id String/Integer Yes Pricing ID from getRentalPricing
Full URL Example 
GET https://shadowotp.com/stubs/rental_handler.php?api_key=YOUR_API_KEY&action=rentNumber&pricing_id=101
Success Response
{ "status": "200", "phone": "+12025551234", "order_id": "abc123", "expiry": "2025-12-01 14:00:00" }
GET
/?action=getMyRentals

Get My Rentals

List all your rental numbers (both active and expired).

Parameter Type Required Description
api_key String Yes Your API key
action String Yes Must be "getMyRentals"
Full URL Example 
GET https://shadowotp.com/stubs/rental_handler.php?api_key=YOUR_API_KEY&action=getMyRentals
Success Response
{ "status": "200", "rentals": [ { "order_id": "abc123", "phone": "+12025551234", "status": "ACTIVE", "expiry": "2025-12-01 14:00:00" } ] }
GET
/?action=getRentalSMS

Get Rental SMS

Fetch all SMS messages received on a rented number.

Parameter Type Required Description
api_key String Yes Your API key
action String Yes Must be "getRentalSMS"
order_id String Yes Order ID from rentNumber
Full URL Example 
GET https://shadowotp.com/stubs/rental_handler.php?api_key=YOUR_API_KEY&action=getRentalSMS&order_id=abc123
Success Response
{ "status": "200", "order_id": "abc123", "messages": [ { "id": "1", "sender": "Google", "text": "G-123456 is your Google verification code.", "received_at": "2025-01-15 10:30:00" } ] }
GET
/?action=renewRental

Renew Rental

Extend an active rental number's expiry by adding more time.

Parameter Type Required Description
api_key String Yes Your API key
action String Yes Must be "renewRental"
rental_id String Yes Rental ID or Order ID
duration Integer Yes Hours to add (e.g., 12, 24, 72)
Full URL Example 
GET https://shadowotp.com/stubs/rental_handler.php?api_key=YOUR_API_KEY&action=renewRental&rental_id=abc123&duration=24
Success Response
{ "status": "200", "message": "Rental extended successfully", "new_expiry": "2025-12-02 14:00:00" }
Temporary Email API

Temporary Email API

Purchase temporary email addresses for OTP verification. Each email is linked to a specific service and domain.

GET
/?action=getEmailServices

Get Email Services

Get list of available email services with pricing and stock.

Parameter Type Required Description
api_key String Yes Your API key
action String Yes Must be "getEmailServices"
domain String Yes Email domain (e.g., "gmail.com")
Full URL Example 
GET https://shadowotp.com/stubs/email_handler.php?api_key=YOUR_API_KEY&action=getEmailServices&domain=gmail.com
Success Response
{ "status": "200", "domain": "gmail.com", "services": [ { "service_id": "ig", "service_name": "Instagram", "price": 120.00, "stock": 50 } ] }
GET
/?action=buyEmail

Buy Email

Purchase a temporary email address for OTP verification.

Parameter Type Required Description
api_key String Yes Your API key
action String Yes Must be "buyEmail"
service_id String Yes Service ID (e.g., "ig", "fb")
domain String Yes Email domain
Full URL Example 
GET https://shadowotp.com/stubs/email_handler.php?api_key=YOUR_API_KEY&action=buyEmail&service_id=ig&domain=gmail.com
Success Response
{ "status": "200", "email_id": "7291834", "email": "temp.abc123@gmail.com", "service": "Instagram", "service_code": "ig", "domain": "gmail.com", "cost": 120.00, "balance": 4880.00, "currency": "PKR", "created_at": "2025-01-15 14:22:00" }
GET
/?action=getEmailCode

Get Email Code

Poll this endpoint to retrieve the verification code sent to the purchased email.

Parameter Type Required Description
api_key String Yes Your API key
action String Yes Must be "getEmailCode"
email_id String/Integer Yes Email ID from buyEmail
Full URL Example 
GET https://shadowotp.com/stubs/email_handler.php?api_key=YOUR_API_KEY&action=getEmailCode&email_id=7291834
Code Received
{ "status": "200", "email_id": "7291834", "messages": [ { "email": "temp.abc123@gmail.com", "subject": "Verification Code", "body": "Your verification code is 847293", "code": "847293" } ] }
Waiting for Email
{ "status": "202", "message": "Waiting for code...", "email_id": "7291834" }
GET
/?action=cancelEmail

Cancel Email

Cancel an email activation. Refund if no OTP received yet.

Parameter Type Required Description
api_key String Yes Your API key
action String Yes Must be "cancelEmail"
email_id String/Integer Yes Email ID from buyEmail
Full URL Example 
GET https://shadowotp.com/stubs/email_handler.php?api_key=YOUR_API_KEY&action=cancelEmail&email_id=7291834
Cancelled & Refunded
{ "status": "200", "message": "Cancelled and refunded", "refunded": 120.00, "balance": 5000.00 }
GET
/?action=getEmailHistory

Get Email History

Retrieve paginated history of all your email purchases.

Parameter Type Required Description
api_key String Yes Your API key
action String Yes Must be "getEmailHistory"
page Integer No Page number for pagination (default: 1)
Full URL Example 
GET https://shadowotp.com/stubs/email_handler.php?api_key=YOUR_API_KEY&action=getEmailHistory&page=1
Success Response
{ "status": "200", "total": 42, "page": 1, "per_page": 20, "total_pages": 3, "history": [ { "email_id": "7291834", "email_address": "temp.abc123@gmail.com", "service_id": "ig", "service_name": "Instagram", "domain": "gmail.com", "status": "received", "code": "847293", "price": 120.00, "created_at": "2025-01-15 14:22:00" } ] }
Free Number API

Free Numbers API

Access free phone numbers for SMS verification with a lifetime subscription. Purchase the subscription once and use the API indefinitely without per-message charges. Perfect for developers and businesses requiring cost-effective OTP verification.

Lifetime Subscription Required

To use the Free Number API, you need to purchase a lifetime subscription for PKR 500.00. Once purchased, you can access unlimited free numbers without any additional charges.

GET
/?action=getBalance

Get Balance

Retrieve your account balance in PKR currency. Check your available funds before purchasing numbers.

Parameter Type Required Description
api_key String Yes Your unique API key
action String Yes Must be "getBalance"
Full URL Example 
GET https://shadowotp.com/stubs/free_handler.php?api_key=YOUR_API_KEY&action=getBalance
Success Response
{ "status": "200", "balance": 1500.00, "currency": "PKR" }
GET
/?action=getServices

Get Services

Get list of available services with pricing and details. Each service corresponds to a different platform with different prices.

Parameter Type Required Description
api_key String Yes Your unique API key
action String Yes Must be "getServices"
Full URL Example 
GET https://shadowotp.com/stubs/free_handler.php?api_key=YOUR_API_KEY&action=getServices
Success Response
{ "status": "200", "services": [ { "server_id": "1", "service_name": "Telegram", "server_type": "1", "price": 5.00, "currency": "PKR" }, { "server_id": "2", "service_name": "WhatsApp", "server_type": "1", "price": 8.00, "currency": "PKR" }, { "server_id": "3", "service_name": "Google", "server_type": "1", "price": 4.00, "currency": "PKR" } ], "total": 3 }
GET
/?action=buyNumber

Buy Number

Purchase a temporary phone number to receive SMS verification codes for a specific service. Your balance will be deducted automatically.

Parameter Type Required Description
api_key String Yes Your unique API key
action String Yes Must be "buyNumber"
server String Yes Server ID from getServices (e.g., "1", "2", "3")
type String No Type parameter (default: "1")
Full URL Example (Telegram) 
GET https://shadowotp.com/stubs/free_handler.php?api_key=YOUR_API_KEY&action=buyNumber&server=1&type=1
Success Response
{ "status": "ACCESS_NUMBER", "order_id": "123456789", "phone": "+79001234567", "server_id": "1", "server_name": "Telegram", "price": 5.00, "expires_in": 900, "expires_at": "2025-01-15 15:00:00", "balance": 1495.00, "currency": "PKR", "created_at": "2025-01-15 14:45:00" }
Insufficient Balance
{ "status": "NO_BALANCE", "message": "Insufficient balance to purchase this number", "required_balance": 5.00, "current_balance": 3.00 }
No Numbers Available
{ "status": "NO_NUMBERS", "message": "No numbers available for this service" }
GET
/?action=getStatus

Get Status

Check SMS status and retrieve verification codes for a specific order. Returns plain text responses. Poll every 5-10 seconds.

Parameter Type Required Description
api_key String Yes Your unique API key
action String Yes Must be "getStatus"
id String/Integer Yes Order ID from buyNumber
Full URL Example 
GET https://shadowotp.com/stubs/free_handler.php?api_key=YOUR_API_KEY&action=getStatus&id=123456789
Code Received
STATUS_OK:123456
Waiting for SMS
STATUS_WAIT_CODE
Polling Strategy

Call this endpoint every 5-10 seconds until you receive STATUS_OK or an error. Typical timeout is 15-20 minutes. If STATUS_WAIT_RETRY appears, use setStatus with status=3.

GET
/?action=setStatus

Set Status

Manage your activation order by setting its status. Cancel, request new SMS, or mark as complete.

Parameter Type Required Description
api_key String Yes Your unique API key
action String Yes Must be "setStatus"
id String/Integer Yes Order ID from buyNumber
status Integer Yes Status code (3=Retry, 6=Complete, 8=Cancel)
3

Request Another SMS

Request a new SMS code if previous one timed out

6

Complete Activation

Mark the order as successfully completed

8

Cancel & Refund

Cancel and refund if no SMS received (after 2 minutes)

Request Another SMS (Status 3) 
GET https://shadowotp.com/stubs/free_handler.php?api_key=YOUR_API_KEY&action=setStatus&id=123456789&status=3
Complete Activation (Status 6) 
GET https://shadowotp.com/stubs/free_handler.php?api_key=YOUR_API_KEY&action=setStatus&id=123456789&status=6
Cancel and Refund (Status 8) 
GET https://shadowotp.com/stubs/free_handler.php?api_key=YOUR_API_KEY&action=setStatus&id=123456789&status=8
Cancelled & Refunded
ACCESS_READY
New SMS Requested
ACCESS_RETRY_GET
Activation Completed
ACCESS_FINISH
Important Notes

Status 8 (Cancel) only refunds if NO SMS was received. Cancel is only allowed after 2 minutes from purchase. Always use Status 6 (Complete) after successfully using the code.

Resources

Error Codes

Common error codes that may be returned by any endpoint. Handle these errors gracefully in your application.

NO_ACTIVATION

Not Found

Order ID not found or doesn't belong to your account

BAD_ACTION

Invalid Action

Invalid action parameter or malformed request

NO_BALANCE

Insufficient Balance

Not enough balance to complete this purchase

NO_NUMBERS

No Numbers Available

No numbers available for this country/service

BAD_KEY

Invalid API Key

API key is invalid or expired

ERROR_SQL

Database Error

A database error occurred on the server

BAD_SERVICE

Invalid Service

The specified service ID is not valid

WRONG_EXCEPTION

Server Error

An unexpected server error occurred

Free Number API Specific Errors

The Free Number API may return additional error codes such as BAD_SERVER, ERROR_PROVIDER, ACCOUNT_BLOCKED, EARLY_CANCEL_DENIED. Refer to your dashboard for complete error documentation.

Resources

Need Help?

Our support team is available 24/7 to help you with any questions or issues.

24/7 Support

Contact us via WhatsApp, Email, or Live Chat. Urdu & English support available.

Ready to Integrate?

Get your API key and start building powerful verification features in minutes. Join thousands of developers using Shadow OTP.

Get API Key Contact Support