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

The server parameter (1, 2, 3, or 4) selects which backend handles your request. Each server may have different countries, services, pricing, and availability — always check the available options for each server before making requests. Server 1 supports instant cancellation; Servers 2, 3, and 4 require a 2-minute wait before an order can be cancelled and refunded.

GET
/?action=getBalance

Get Balance

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

Parameter Type Required Description
api_key String Yes Your 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.

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
Server 4 Example 
GET https://shadowotp.com/stubs/handler_api.php?api_key=YOUR_API_KEY&action=getCountries&server=4
Success Response
{ "status": "200", "countries": { "1": [ {"code": "0", "name": "Russia"}, {"code": "7", "name": "Kazakhstan"} ], "2": [ {"code": "0", "name": "Russia"}, {"code": "1", "name": "Ukraine"} ], "4": [ {"code": "0", "name": "Russia"}, {"code": "6", "name": "Indonesia"} ] } }
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
Server 4 Example 
GET https://shadowotp.com/stubs/handler_api.php?api_key=YOUR_API_KEY&action=getServices&country=0&server=4
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
Server 4 Example 
GET https://shadowotp.com/stubs/handler_api.php?api_key=YOUR_API_KEY&action=getNumber&service=tg&country=0&server=4
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
Server 4 Example 
GET https://shadowotp.com/stubs/handler_api.php?api_key=YOUR_API_KEY&action=getStatus&id=12345678&server=4
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. Instant on Server 1; 2-minute wait on Servers 2, 3, and 4.

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
Cancel, Server 4 Example (2 min delay applies) 
GET https://shadowotp.com/stubs/handler_api.php?api_key=YOUR_API_KEY&action=setStatus&id=12345678&status=8&server=4
Cancel Attempted Too Early
CANCEL_DELAY:87
Cancel Delay Note

If you call status=8 before the required wait time has passed, the response is CANCEL_DELAY:seconds, where seconds is the remaining time before cancellation is allowed.

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. Two server modes are available — see below.

Server 1 vs Server 2

Server 1 (default): select a domain, then a fixed service code (e.g., "ig", "fb"). Server 2: select a domain, then enter any platform URL directly (e.g., "facebook.com", "amazon.com") — more flexible, and gives you access to a separate domain pool. Server 2 orders require a 2-minute wait before cancellation.

GET
/?action=getEmailServices

Get Email Services Server 1

Get list of available email services with pricing and stock for a Server 1 domain.

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 Server 1

Purchase a temporary email address for OTP verification using a service code.

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=getEmailDomains

Get Email Domains Server 2

Get all available domains with pricing and stock for Server 2. Each domain carries its own fixed price, independent of the platform used.

Parameter Type Required Description
api_key String Yes Your API key
action String Yes Must be "getEmailDomains"
Full URL Example 
GET https://shadowotp.com/stubs/email_handler.php?api_key=YOUR_API_KEY&action=getEmailDomains
Success Response
{ "status": "200", "server": 2, "total_domains": 3, "domains": [ { "domain": "domain1.com", "price": 25.00, "stock": 150 }, { "domain": "domain2.com", "price": 30.00, "stock": 85 }, { "domain": "domain3.com", "price": 20.00, "stock": 200 } ] }
Usage Flow

1. Call getEmailDomains to see prices for each domain. 2. Call buyEmail with server=2, your chosen domain, and the platform URL. 3. Poll getEmailCode with the email_id to retrieve the OTP.

GET
/?action=buyEmail&server=2

Buy Email Server 2

Purchase a temporary email address using Server 2. Instead of a fixed service code, you pass a platform URL directly (e.g., "facebook.com", "amazon.com"), and pricing is based on the domain you select.

Parameter Type Required Description
api_key String Yes Your API key
action String Yes Must be "buyEmail"
server Integer Yes Must be "2"
domain String Yes Domain from getEmailDomains (e.g., "domain1.com")
service String Yes Platform URL requiring the OTP (e.g., "facebook.com")
Full URL Example 
GET https://shadowotp.com/stubs/email_handler.php?api_key=YOUR_API_KEY&action=buyEmail&server=2&domain=domain1.com&service=facebook.com
Success Response
{ "status": "200", "server": 2, "email_id": "847291", "email": "randomuser@domain1.com", "service": "facebook.com", "domain": "domain1.com", "cost": 25.00, "balance": 4975.00, "currency": "PKR", "created_at": "2025-01-15 14:22:00" }
Domain Not Found
{ "status": "BAD_SERVICE", "message": "Domain not found. Use getEmailDomains to see available domains." }
GET
/?action=getEmailCode

Get Email Code

Poll this endpoint to retrieve the verification code sent to the purchased email. Works the same regardless of which server the email was purchased on — the server is auto-detected from your order.

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=reorderEmail

Reorder Email Server 2 Only

Request a fresh OTP code for the same email address without purchasing a new one — useful if the previous code expired. Only available for Server 2 orders; no additional balance is deducted.

Parameter Type Required Description
api_key String Yes Your API key
action String Yes Must be "reorderEmail"
email_id String/Integer Yes Email ID from buyEmail (must be a Server 2 order)
Full URL Example 
GET https://shadowotp.com/stubs/email_handler.php?api_key=YOUR_API_KEY&action=reorderEmail&email_id=847291
Reorder Successful
{ "status": "200", "server": 2, "message": "Reorder successful. Waiting for new code...", "email_id": "847291" }
Not Eligible for Reorder
{ "status": "400", "message": "Reorder is only available for Server 2 orders" }
GET
/?action=cancelEmail

Cancel Email

Cancel an email activation. Refund if no OTP received yet. Works for both server modes; the correct server is auto-detected from your order.

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 }
Cancel Delay Active (Server 2)
{ "status": "CANCEL_DELAY", "message": "This server requires a 2-minute wait before cancellation", "wait_seconds_remaining": 85 }
Cancel Delay Note

Emails purchased with server=1 can be cancelled immediately. Emails purchased with server=2 require a 2-minute wait after purchase before cancellation is allowed, and only refund if no OTP has been received.

GET
/?action=getEmailHistory

Get Email History

Retrieve paginated history of all your email purchases across both server modes. Each entry includes a server field so you can tell which server handled it.

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": "847291", "email_address": "randomuser@domain1.com", "service_id": "facebook.com", "domain": "domain1.com", "status": "received", "code": "482917", "price": 25.00, "server": 2, "created_at": "2025-01-15 14:22:00" }, { "email_id": "7291834", "email_address": "temp.abc123@gmail.com", "service_id": "ig", "domain": "gmail.com", "status": "received", "code": "847293", "price": 120.00, "server": 1, "created_at": "2025-01-15 13:45: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

CANCEL_DELAY

Cancel Too Early

Order cannot be cancelled yet; wait for the returned seconds

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