The future of
OTP verification.
Integrate the world's most reliable virtual & long-term rental number API. One endpoint, JSON everywhere.
The API works exactly like the one your users are already used to: same parameters, same actions, same reply formats. If you are moving an existing integration (or your own panel / bot) to OtpGet, you only change two things — nothing else in your code.
- Base URL — point your requests to the URL of the service you use (table below).
- API key — use your OtpGet API key in
api_key. View it in your dashboard under API Tool or Profile (you verify first with an emailed code or your password). - Test first (optional) — put your Sandbox key in
api_keyinstead. Same URL, fake numbers, no money. Swap to the real key when you go live. See Sandbox.
Base URLs
| Service | Base URL |
|---|---|
| Temp numbers (SMS OTP) | https://otpget.com/stubs/handler_api.php |
| Rentals | https://otpget.com/stubs/rental-handler.php |
| Cheap numbers | https://otpget.com/stubs/cheap_handler.php |
| Premium (SMS & Call) | https://otpget.com/stubs/premium-handler.php |
| Email OTP | https://otpget.com/stubs/email-handler.php |
Requirement: the account that owns the API key must have a verified email and a phone number. Otherwise every call is refused with ACCOUNT_NOT_VERIFIED — finish it once at Complete your account.
The API is plain REST over HTTPS with simple GET endpoints, so any system that can make a web request can use it — no SDK required. One API key works everywhere.
| Platform | How to call the API |
|---|---|
| iOS app (Swift) | URLSession — see the Swift example below. |
| Android app (Kotlin/Java) | OkHttp or HttpURLConnection — see the Kotlin example below. |
| Website | Your backend, or the browser with fetch — see the JavaScript example below. |
| POS system | Any terminal or till app that can make an HTTPS request; same endpoints as everywhere else. |
| Telegram bot | Call the same endpoints from your bot code; set your own prices and sell numbers to your users. |
Prefer push over polling? Set up a webhook and every received SMS is POSTed to your server the moment it arrives. Test first with a sandbox key — same URL, fake numbers, no money.
Swift (iOS) — order a number, poll for the code
Kotlin (Android) — order a number, poll for the code
JavaScript (web / POS) — order a number, poll for the code
Every request — temp number or rental — must include your API Key in the query string.
Response shapes differ by endpoint and by action — the SMS OTP API below is a mix of plain text and JSON, not one single format. Always check what each action's example on this page actually shows before parsing.
SMS OTP API — /stubs/handler_api.php
getBalance, getNumber, getStatus and setStatus reply in plain text (a legacy colon-separated protocol) — getServers, getCountries and getServices reply in JSON. See each action below for its exact shape.
Cheap Numbers API — /stubs/cheap_handler.php
Same plain-text protocol as the SMS OTP API. getServers and getServices reply in JSON; buyNumber replies with one CSV line.
Premium API — /stubs/premium-handler.php
Same plain-text protocol as the Cheap Numbers API. getServers and getServices reply in JSON; buyNumber replies with one CSV line. The code is delivered by SMS or call.
Rental API — /stubs/rental-handler.php
SUCCESSRental and Email OTP always reply in JSON with a status field — the SMS OTP API is the one endpoint with the mixed plain-text/JSON behaviour described above, kept for backward compatibility.
All prices and balances are in PKR by default. Add the optional currency parameter to any request to receive amounts converted into another currency. The rates are the same ones used by the OTPGet website currency converter. Use Get Currencies to see the supported codes.
How it works
| Case | Behaviour |
|---|---|
| currency missing / empty / PKR | Nothing changes — amounts are returned in PKR exactly as before. |
| currency=USD (valid code) | Amounts in the response are converted to that currency. Codes are case-insensitive. |
| Unknown code | Actions that return amounts reply with an error (BAD_CURRENCY on the plain-text protocol, status 400 on JSON endpoints). Actions that carry no amounts ignore the parameter, so a typo can never block a cancel or refund. |
| Decimals | PKR amounts keep 2 decimals. Converted amounts use 4 decimals so small prices stay accurate. |
| Charging | Display only. Your wallet is always charged, refunded and held in PKR; the converted figure is what the PKR amount is worth at the current rate. |
Examples
Responses
Lists every currency code you can pass as currency, with its rate. The list is sorted A–Z by currency name. rate is how many units of that currency equal 1 PKR. Works identically on every endpoint (SMS OTP, Cheap, Premium, Rental, Email) and always replies in JSON.
$url = 'https://otpget.com/stubs/handler_api.php?api_key=' . $apiKey . '&action=getCurrencies';
$data = json_decode(file_get_contents($url), true);
print_r($data['currencies']);
url = "https://otpget.com/stubs/handler_api.php"
params = {"api_key": "YOUR_KEY", "action": "getCurrencies"}
print(requests.get(url, params=params).json()["currencies"])
Request Parameters
| Parameter | Required | Description |
|---|---|---|
| api_key | Required | Your API key |
| action | Required | getCurrencies |
Response Fields
| Field | Description |
|---|---|
| status | "200" |
| default | The default currency (PKR) used when currency is not sent |
| count | Number of currencies returned |
| currencies[].code | The value to pass as currency |
| currencies[].name | Currency name |
| currencies[].symbol | Currency symbol |
| currencies[].rate | Units of this currency per 1 PKR |
Responses
Test your whole integration without spending money. In your dashboard open API Tool (or Profile), enter your account password and generate a Sandbox Key (it starts with sbx_). Keys are hidden until you confirm your password. Use it in place of your real key in api_key — everything else (URLs, parameters, reply formats) stays exactly the same. Your real key always does real purchases.
How to test, step by step
- Create the key — Dashboard → API Tool (or Profile) → Generate Sandbox Key. It starts with
sbx_. - Keep your real URL — nothing changes except the key:
api_key=sbx_.... - Run the whole flow — list servers/prices → buy a number → poll the status until the code arrives (~10 s) → finish or cancel.
- Try the errors — add
&scenario=no_numbers,low_balanceorno_codeto a buy request. - Start clean — Reset Sandbox Orders & Balance on the API Tool page.
- Go live — replace the sandbox key with your real key. That is the only change.
The sandbox can never spend your real balance or reach a provider, and a sandbox key cannot be used for real purchases.
How the sandbox behaves
| Area | Behaviour |
|---|---|
| Lists & prices | Servers, countries, services, rental pricing and prices are the real ones (including your discount), so you can build against live data. |
| Numbers | Fake numbers. No provider is called and nothing is charged to your real balance. |
| Balance | A virtual balance of 5000 (PKR). Buying lowers it, cancelling / expiry refunds it. getBalance shows the virtual balance. Use the Reset button on the API Tool page to start over. |
| Code | Arrives about 10 seconds after the purchase (poll getStatus / getEmailCode / getRentalSMS). The same cancel rules apply: for SMS, cancel is refused in the first 2 minutes (EARLY_CANCEL_DENIED). |
| Expiry | An order that never completes is cancelled and refunded after 20 minutes. |
| Test errors | Add &scenario=no_numbers, &scenario=low_balance or &scenario=no_code to a buy request (getNumber, buyNumber, rentNumber, buyEmail) to test those replies. no_code never delivers the code. |
| Email prices | Email stock is priced live, so sandbox email orders use a fixed sample price (15.00 before your discount). |
Every sandbox reply carries the header X-Sandbox: 1. Switch to your real key when you go live — no other change is needed.
If a discount has been set on your account, every price you receive through the API — getServices, getPrice, rental pricing, email and cheap/premium lists, and the price returned when you buy — is already reduced by that percentage, and that is the amount charged (and refunded on cancel). There is nothing to send or calculate on your side. The discount is applied in PKR before any currency conversion.
Temporary phone numbers for receiving a single SMS/OTP. Legacy colon-separated protocol — most actions reply in plain text, the listing actions reply in JSON.
Required in every request
| Parameter | Required | Description |
|---|---|---|
| api_key | Required | Your API key from the dashboard |
| action | Required | The operation to run (see the table below) |
| currency | Optional | Return amounts in this currency instead of PKR — see Currency |
Actions at a glance
| Action | Extra required parameters | Reply |
|---|---|---|
| getBalance | — | Plain text |
| getCurrencies | — | JSON |
| getServers | — | JSON |
| getCountries | — (type optional) | JSON |
| getServices | country (+ type for servers 2–5) | JSON |
| getPrice | country, service (+ type) | JSON |
| getNumber | service, country (+ type for servers 2–5) | Plain text |
| getStatus | id | Plain text |
| setStatus | id, status | Plain text |
| getStatistics | — (type, country, service, limit optional) | JSON |
Response format
Plain-text replies are a single line, fields separated by :. Compare the raw body against the values shown for each action. Prices and balances are in PKR by default — add the optional currency parameter to get them in another currency (see Currency). The type parameter selects the server (1–6); call getServers to see which are active.
Any error is a plain-text code — see Error Codes. An unknown action returns an empty body.
Typical flow
getCountries → getServices → getNumber → poll getStatus until STATUS_OK → setStatus (status=6 to finish, or 8 to cancel and refund).
Your wallet balance in PKR (or in the currency you request with currency). Replies in plain text.
$url = 'https://otpget.com/stubs/handler_api.php?api_key=' . $apiKey . '&action=getBalance';
echo file_get_contents($url); // plain text
url = "https://otpget.com/stubs/handler_api.php"
params = {"api_key": "YOUR_KEY", "action": "getBalance"}
print(requests.get(url, params=params).text) # plain text
Request Parameters
| Parameter | Required | Description |
|---|---|---|
| api_key | Required | Your API key |
| action | Required | getBalance |
| currency | Optional | Return the balance in this currency instead of PKR (e.g. USD). See Currency |
Responses
Lists every server type (1–5) and whether it is currently active. Check this before assuming a given type has countries/services behind it.
$url = 'https://otpget.com/stubs/handler_api.php?api_key=' . $apiKey . '&action=getServers';
$data = json_decode(file_get_contents($url), true);
print_r($data);
url = "https://otpget.com/stubs/handler_api.php"
params = {"api_key": "YOUR_KEY", "action": "getServers"}
print(requests.get(url, params=params).json())
Request Parameters
| Parameter | Required | Description |
|---|---|---|
| api_key | Required | Your API key |
| action | Required | getServers |
Responses
Countries available for each server type, keyed by type. Use a returned id as country in Get Services and Get Number.
$url = 'https://otpget.com/stubs/handler_api.php?api_key=' . $apiKey . '&action=getCountries&type=1';
$data = json_decode(file_get_contents($url), true);
print_r($data);
url = "https://otpget.com/stubs/handler_api.php"
params = {"api_key": "YOUR_KEY", "action": "getCountries", "type": "1"}
print(requests.get(url, params=params).json())
Request Parameters
| Parameter | Required | Description |
|---|---|---|
| api_key | Required | Your API key |
| action | Required | getCountries |
| type | Optional | 1–5. Omit to get every server type at once |
Responses
Services and prices for a country on a given server. Returns an object keyed by service id; each value is "Name - price PKR" (the code at the end is the currency you requested — PKR by default).
$url = 'https://otpget.com/stubs/handler_api.php?api_key=' . $apiKey . '&action=getServices&country=COUNTRY_ID&type=1';
$data = json_decode(file_get_contents($url), true);
print_r($data);
url = "https://otpget.com/stubs/handler_api.php"
params = {"api_key": "YOUR_KEY", "action": "getServices", "country": "COUNTRY_ID", "type": "1"}
print(requests.get(url, params=params).json())
Request Parameters
| Parameter | Required | Description |
|---|---|---|
| api_key | Required | Your API key |
| action | Required | getServices |
| country | Required | Country id from Get Countries |
| type | Optional | 1–5, default 1. Must match the server the country came from |
| currency | Optional | Return prices in this currency instead of PKR (e.g. USD). See Currency |
Responses
Price of one service: give the server (type), the country and the service id — you get the price back. Replies in JSON; failures reply in plain text like the other SMS OTP actions.
$url = 'https://otpget.com/stubs/handler_api.php?api_key=' . $apiKey . '&action=getPrice&country=COUNTRY_ID&service=SERVICE_ID&type=1';
$data = json_decode(file_get_contents($url), true);
echo $data['price'] . ' ' . $data['currency'];
url = "https://otpget.com/stubs/handler_api.php"
params = {"api_key": "YOUR_KEY", "action": "getPrice", "country": "COUNTRY_ID", "service": "SERVICE_ID", "type": "1"}
print(requests.get(url, params=params).json())
Request Parameters
| Parameter | Required | Description |
|---|---|---|
| api_key | Required | Your API key |
| action | Required | getPrice |
| country | Required | Country id for that server — from getCountries |
| service | Required | Service id — from getServices |
| type | Optional | Server 1–5. Default 1 |
| currency | Optional | Return the price in this currency instead of PKR (e.g. USD). See Currency |
The price returned is the listed price in your account. It is the same figure getServices shows; with currency it is converted using the OTPGet currency converter, without it you always get PKR.
Responses
Orders a phone number. The price is deducted from your wallet. Replies in plain text: ACCESS_NUMBER:order_id:phone:price on success, or an error code.
$url = 'https://otpget.com/stubs/handler_api.php?api_key=' . $apiKey . '&action=getNumber&service=SERVICE_ID&country=COUNTRY_ID&type=1';
echo file_get_contents($url); // plain text
url = "https://otpget.com/stubs/handler_api.php"
params = {"api_key": "YOUR_KEY", "action": "getNumber", "service": "SERVICE_ID", "country": "COUNTRY_ID", "type": "1"}
print(requests.get(url, params=params).text) # plain text
Request Parameters
| Parameter | Required | Description |
|---|---|---|
| api_key | Required | Your API key |
| action | Required | getNumber |
| service | Required | Service id from Get Services |
| country | Required | Country id from Get Countries |
| type | Optional | 1–5, default 1. Must match the server used for Get Countries / Get Services |
| currency | Optional | Return the charged price (and balance) in this currency instead of PKR. Your wallet is still charged in PKR. See Currency |
Responses
Checks whether the SMS for an order has arrived. Poll every few seconds. Replies in plain text.
$url = 'https://otpget.com/stubs/handler_api.php?api_key=' . $apiKey . '&action=getStatus&id=ORDER_ID';
echo file_get_contents($url); // plain text
url = "https://otpget.com/stubs/handler_api.php"
params = {"api_key": "YOUR_KEY", "action": "getStatus", "id": "ORDER_ID"}
print(requests.get(url, params=params).text) # plain text
Request Parameters
| Parameter | Required | Description |
|---|---|---|
| api_key | Required | Your API key |
| action | Required | getStatus |
| id | Required | Order id from getNumber (the first value after ACCESS_NUMBER:) |
Responses
Same as getStatus, but when the SMS has arrived the reply is JSON with the code and the full message text (where the server provides the full text). Use it when you need more than the code. While waiting or when cancelled, the reply is the same plain text as getStatus (STATUS_WAIT_CODE, STATUS_CANCEL, ...).
Responses
text is the full message when the server delivers it; otherwise it is the same as code. If a number receives several messages, code is the latest one and text contains them all. Plain getStatus keeps working exactly as before.
Webhook or polling — your choice. Instead of polling getStatus, you can give us an HTTPS address and we will POST every received SMS to it the moment it arrives. It is optional: if you set nothing, nothing changes — getStatus / getStatusV2 keep working exactly as before, and you can use both together.
Set it up
Dashboard → API page → API Access Control: enter your Webhook URLs — up to 5, one per line (each must be https://, a public address; every URL receives every SMS, signed with the same secret) and your server IPs in Allowed IPs if you want an IP whitelist. A Webhook secret is generated for you on first save. Use Send Test Webhook to check your endpoints (the test goes to every saved URL); the last deliveries are listed on the same page.
Which servers support it
Server (type) | Webhook (push) | What to do |
|---|---|---|
| Server 1 | Supported | SMS is pushed to your webhook. |
| Server 2 | Supported | SMS is pushed to your webhook (full message text included). |
| Server 3 | Supported | SMS is pushed to your webhook. |
| Server 4 | Supported | SMS is pushed to your webhook. |
| Server 5 | Supported | SMS is pushed to your webhook. |
| Email servers | Not supported | Poll getEmailCode. |
| Rentals | Not supported | Poll getRentalSMS. |
Push depends on the server sending us the message, so a webhook is a speed-up, not a guarantee: keep a slow fallback poll (for example every 15–30 seconds) so an order is never missed if a push does not arrive.
What we send
POST with Content-Type: application/json:
activationId is the same id you got from getNumber. text is the full message when the server sends it, otherwise the code.
Verify the request
Every request carries X-OtpGet-Signature: sha256=<hex> — the HMAC-SHA256 of the raw request body using your Webhook secret. Compare it before trusting the call:
Delivery rules
- Answer with any 2xx status within a few seconds. Otherwise we retry that URL up to 3 times (immediately, after ~5 s, after ~20 s); if your endpoint keeps failing we only try once per message until it recovers.
- The same message can in rare cases arrive twice — treat
activationId+codeas idempotent. - HTTPS only. Redirects are not followed. Local / private addresses are rejected.
- If an order receives a second message, you get a second POST with the new code and text.
Finish an order after the SMS arrived, or cancel it for a refund. Replies in plain text.
$url = 'https://otpget.com/stubs/handler_api.php?api_key=' . $apiKey . '&action=setStatus&id=ORDER_ID&status=8';
echo file_get_contents($url); // plain text
url = "https://otpget.com/stubs/handler_api.php"
params = {"api_key": "YOUR_KEY", "action": "setStatus", "id": "ORDER_ID", "status": "8"}
print(requests.get(url, params=params).text) # plain text
Request Parameters
| Parameter | Required | Description |
|---|---|---|
| api_key | Required | Your API key |
| action | Required | setStatus |
| id | Required | Order id from getNumber |
| status | Required | 3 or 6 = complete (only once an SMS was received) · 8 = cancel and refund (allowed 2 minutes after purchase) |
Responses
Shows what is actually being bought across all users, ranked by popularity — the same data as the Statistics page on the website. Use it to check which service / server / country combinations are performing best before you buy. Filter by server (type), country and service. getTopActivations is an alias of getStatistics. The call is read-only — it never touches your balance.
$url = 'https://otpget.com/stubs/handler_api.php?api_key=' . $apiKey . '&action=getStatistics&type=2&service=WhatsApp';
$data = json_decode(file_get_contents($url), true);
print_r($data['data']);
url = "https://otpget.com/stubs/handler_api.php"
params = {"api_key": "YOUR_KEY", "action": "getStatistics", "type": "2", "service": "WhatsApp"}
print(requests.get(url, params=params).json())
Request Parameters
| Parameter | Required | Description |
|---|---|---|
| api_key | Required | Your API key |
| action | Required | getStatistics (or getTopActivations) |
| type | Optional | Server filter, 1–5 (see getServers). Leave out for all servers. |
| country | Optional | Country id from getCountries. Needs type — a country id belongs to one server. |
| service | Optional | Service name, e.g. WhatsApp (the name shown in getServices). |
| limit | Optional | Number of rows, 1–20 (default 20). |
| currency | Optional | Accepted like on every other action — see Currency. The ranking contains no amounts, so the reply is the same with or without it. |
The list groups by whichever of country / service / server you have not filtered, so every filter combination returns a useful ranking. Rows are ordered best first (rank 1 = most popular); purchase counts are not returned. Results are refreshed about once a minute.
Responses
Long-term numbers you keep for days or months, instead of a single OTP. A separate endpoint from the SMS OTP API — same api_key, different base URL and a JSON response shape.
Required in every request
| Parameter | Required | Description |
|---|---|---|
| api_key | Required | Your API key from the dashboard |
| action | Required | The operation to run (see the table below) |
| currency | Optional | Return amounts in this currency instead of PKR — see Currency |
Actions at a glance
| Action | Extra required parameters | Returns |
|---|---|---|
| getCurrencies | — | Currency codes + rates |
| getRentalCountries | — (provider optional) | Countries |
| getRentalPricing | country_code, provider | Durations + prices |
| getPrice | country_code, provider, duration_hours | One price |
| getAvailableRentals | country_code, provider | Live stock |
| rentNumber | country_code, provider, duration_hours | Rented number |
| getMyRentals | — | Your rentals |
| getRentalSMS | order_id | Messages on a rental |
| renewRental | rental_id, duration_hours | New expiry |
| cancelRental | rental_id | Refund (Server 2, 20 min) |
Providers and durations
provider is 1 (Server 1) or 2 (Server 2). Valid duration_hours: 12, 24, 168, 720, 4320, 8640. Server 2 supports only the monthly durations 720, 4320 and 8640. Prices and balances are in PKR by default (optional currency parameter — see Currency).
Response format
Every response is JSON. The HTTP status is always 200 — check the status field in the body (a string).
Errors: see Error Codes.
Typical flow
getRentalCountries → getRentalPricing → rentNumber → getRentalSMS → renewRental or cancelRental.
Countries available for rentals.
$url = 'https://otpget.com/stubs/rental-handler.php?api_key=' . $apiKey . '&action=getRentalCountries';
$data = json_decode(file_get_contents($url), true);
print_r($data);
url = "https://otpget.com/stubs/rental-handler.php"
params = {"api_key": "YOUR_KEY", "action": "getRentalCountries"}
print(requests.get(url, params=params).json())
Request Parameters
| Parameter | Required | Description |
|---|---|---|
| api_key | Required | Your API key |
| action | Required | getRentalCountries |
| provider | Optional | 1 or 2. Omit to list both servers |
Responses
Available durations and prices for one country on one server.
$url = 'https://otpget.com/stubs/rental-handler.php?api_key=' . $apiKey . '&action=getRentalPricing&country_code=ca&provider=1';
$data = json_decode(file_get_contents($url), true);
print_r($data);
url = "https://otpget.com/stubs/rental-handler.php"
params = {"api_key": "YOUR_KEY", "action": "getRentalPricing", "country_code": "ca", "provider": "1"}
print(requests.get(url, params=params).json())
Request Parameters
| Parameter | Required | Description |
|---|---|---|
| api_key | Required | Your API key |
| action | Required | getRentalPricing |
| country_code | Required | country_code from Get Rental Countries (e.g. ca) |
| provider | Required | 1 or 2 |
| currency | Optional | Return prices in this currency instead of PKR (e.g. USD). See Currency |
Responses
Price of one rental: give the provider (server), the country and the duration — you get the price back. Replies in JSON.
$url = 'https://otpget.com/stubs/rental-handler.php?api_key=' . $apiKey . '&action=getPrice&country_code=ca&provider=1&duration_hours=720';
$data = json_decode(file_get_contents($url), true);
echo $data['price'] . ' ' . $data['currency'];
url = "https://otpget.com/stubs/rental-handler.php"
params = {"api_key": "YOUR_KEY", "action": "getPrice", "country_code": "ca", "provider": "1", "duration_hours": "720"}
print(requests.get(url, params=params).json())
Request Parameters
| Parameter | Required | Description |
|---|---|---|
| api_key | Required | Your API key |
| action | Required | getPrice |
| provider | Required | 1 (Server 1) or 2 (Server 2) |
| country_code | Required | Country code — from getRentalCountries |
| duration_hours | Required | Rental duration — one of the durations returned by getRentalPricing |
| currency | Optional | Return the price in this currency instead of PKR (e.g. USD). See Currency |
The price returned is the listed price in your account. It is the same figure getRentalPricing shows; with currency it is converted using the OTPGet currency converter, without it you always get PKR.
Responses
Live stock for a country on one server.
$url = 'https://otpget.com/stubs/rental-handler.php?api_key=' . $apiKey . '&action=getAvailableRentals&country_code=ca&provider=1';
$data = json_decode(file_get_contents($url), true);
print_r($data);
url = "https://otpget.com/stubs/rental-handler.php"
params = {"api_key": "YOUR_KEY", "action": "getAvailableRentals", "country_code": "ca", "provider": "1"}
print(requests.get(url, params=params).json())
Request Parameters
| Parameter | Required | Description |
|---|---|---|
| api_key | Required | Your API key |
| action | Required | getAvailableRentals |
| country_code | Required | Country code, e.g. ca |
| provider | Required | 1 or 2 |
Responses
Rents a number for the chosen duration. The price is deducted from your wallet immediately.
$url = 'https://otpget.com/stubs/rental-handler.php?api_key=' . $apiKey . '&action=rentNumber&country_code=ca&provider=1&duration_hours=720';
$data = json_decode(file_get_contents($url), true);
print_r($data);
url = "https://otpget.com/stubs/rental-handler.php"
params = {"api_key": "YOUR_KEY", "action": "rentNumber", "country_code": "ca", "provider": "1", "duration_hours": "720"}
print(requests.get(url, params=params).json())
Request Parameters
| Parameter | Required | Description |
|---|---|---|
| api_key | Required | Your API key |
| action | Required | rentNumber |
| country_code | Required | Country code from Get Rental Countries |
| provider | Required | 1 or 2 |
| duration_hours | Required | One of 12, 24, 168, 720, 4320, 8640. Server 2: only 720, 4320, 8640 |
| currency | Optional | Return the charged price (and balance) in this currency instead of PKR. Your wallet is still charged in PKR. See Currency |
Responses
All rentals on your account.
$url = 'https://otpget.com/stubs/rental-handler.php?api_key=' . $apiKey . '&action=getMyRentals';
$data = json_decode(file_get_contents($url), true);
print_r($data);
url = "https://otpget.com/stubs/rental-handler.php"
params = {"api_key": "YOUR_KEY", "action": "getMyRentals"}
print(requests.get(url, params=params).json())
Request Parameters
| Parameter | Required | Description |
|---|---|---|
| api_key | Required | Your API key |
| action | Required | getMyRentals |
| currency | Optional | Return prices in this currency instead of PKR (e.g. USD). See Currency |
Responses
Messages received on a rented number.
$url = 'https://otpget.com/stubs/rental-handler.php?api_key=' . $apiKey . '&action=getRentalSMS&order_id=ord_8f3a91';
$data = json_decode(file_get_contents($url), true);
print_r($data);
url = "https://otpget.com/stubs/rental-handler.php"
params = {"api_key": "YOUR_KEY", "action": "getRentalSMS", "order_id": "ord_8f3a91"}
print(requests.get(url, params=params).json())
Request Parameters
| Parameter | Required | Description |
|---|---|---|
| api_key | Required | Your API key |
| action | Required | getRentalSMS |
| order_id | Required | order_id from Rent Number / Get My Rentals |
Responses
Extends an existing rental. The price is deducted from your wallet.
$url = 'https://otpget.com/stubs/rental-handler.php?api_key=' . $apiKey . '&action=renewRental&rental_id=12&duration_hours=720';
$data = json_decode(file_get_contents($url), true);
print_r($data);
url = "https://otpget.com/stubs/rental-handler.php"
params = {"api_key": "YOUR_KEY", "action": "renewRental", "rental_id": "12", "duration_hours": "720"}
print(requests.get(url, params=params).json())
Request Parameters
| Parameter | Required | Description |
|---|---|---|
| api_key | Required | Your API key |
| action | Required | renewRental |
| rental_id | Required | id from Get My Rentals |
| duration_hours | Required | One of 12, 24, 168, 720, 4320, 8640. Server 2: only 720, 4320, 8640. duration is accepted as an alias |
| currency | Optional | Return the charged price (and balance) in this currency instead of PKR. Your wallet is still charged in PKR. See Currency |
Responses
Cancels a rental and refunds your wallet. Server 2 only, within 20 minutes of purchase, and only if no SMS has been received.
$url = 'https://otpget.com/stubs/rental-handler.php?api_key=' . $apiKey . '&action=cancelRental&rental_id=12';
$data = json_decode(file_get_contents($url), true);
print_r($data);
url = "https://otpget.com/stubs/rental-handler.php"
params = {"api_key": "YOUR_KEY", "action": "cancelRental", "rental_id": "12"}
print(requests.get(url, params=params).json())
Request Parameters
| Parameter | Required | Description |
|---|---|---|
| api_key | Required | Your API key |
| action | Required | cancelRental |
| rental_id | Required | id from Get My Rentals |
| currency | Optional | Return the refunded amount (and balance) in this currency instead of PKR. See Currency |
Responses
Low-price temporary numbers for a single OTP. Each server is a fixed number range at a fixed price — you pick a server and buy, there is no country/service choice. A separate endpoint from the SMS OTP API, but the same plain-text protocol and the same api_key.
Required in every request
| Parameter | Required | Description |
|---|---|---|
| api_key | Required | Your API key from the dashboard |
| action | Required | The operation to run (see the table below) |
| currency | Optional | Return amounts in this currency instead of PKR — see Currency |
Actions at a glance
| Action | Extra required parameters | Reply |
|---|---|---|
| getBalance | — | Plain text |
| getCurrencies | — | JSON |
| getServers | — (type optional) | JSON |
| getServices | server (+ type for type 2) | JSON |
| getPrice | server (+ type for type 2) | JSON |
| buyNumber | server (+ type for type 2) | Plain text (CSV) |
| getStatus | id | Plain text |
| setStatus | id, status | Plain text |
Validity and refunds
A bought number is held for 20 minutes (1200 seconds). Cancel with setStatus status=8 before a code arrives for a full refund. If no code arrives, the order expires and is refunded automatically the next time you call getStatus on it. Once a code has been received there is no refund. Prices and balances are in PKR by default (optional currency parameter — see Currency).
Response format
getServers and getServices reply in JSON; every other action replies in plain text. buyNumber returns one CSV line: order_id,number,validity_seconds. Any error is a plain-text code — see Error Codes.
Typical flow
getServers → buyNumber → poll getStatus until STATUS_OK → setStatus (status=3 to finish, or 8 to cancel and refund).
Your wallet balance in PKR (or in the currency you request with currency). Replies in plain text.
$url = 'https://otpget.com/stubs/cheap_handler.php?api_key=' . $apiKey . '&action=getBalance';
echo file_get_contents($url); // plain text
url = "https://otpget.com/stubs/cheap_handler.php"
params = {"api_key": "YOUR_KEY", "action": "getBalance"}
print(requests.get(url, params=params).text) # plain text
Request Parameters
| Parameter | Required | Description |
|---|---|---|
| api_key | Required | Your API key |
| action | Required | getBalance |
| currency | Optional | Return the balance in this currency instead of PKR (e.g. USD). See Currency |
Responses
Lists the servers you can buy from, with their price. Use a returned id as server in Get Services and Buy Number. Servers are grouped by type.
$url = 'https://otpget.com/stubs/cheap_handler.php?api_key=' . $apiKey . '&action=getServers';
$data = json_decode(file_get_contents($url), true);
print_r($data);
url = "https://otpget.com/stubs/cheap_handler.php"
params = {"api_key": "YOUR_KEY", "action": "getServers"}
print(requests.get(url, params=params).json())
Request Parameters
| Parameter | Required | Description |
|---|---|---|
| api_key | Required | Your API key |
| action | Required | getServers |
| type | Optional | 1 or 2. Omit to list both groups |
| currency | Optional | Return prices in this currency instead of PKR (e.g. USD). See Currency |
Responses
The name and price of one server. Returns an object keyed by the server id; the value is "Name - price".
$url = 'https://otpget.com/stubs/cheap_handler.php?api_key=' . $apiKey . '&action=getServices&server=1';
$data = json_decode(file_get_contents($url), true);
print_r($data);
url = "https://otpget.com/stubs/cheap_handler.php"
params = {"api_key": "YOUR_KEY", "action": "getServices", "server": "1"}
print(requests.get(url, params=params).json())
Request Parameters
| Parameter | Required | Description |
|---|---|---|
| api_key | Required | Your API key |
| action | Required | getServices |
| server | Required | Server id from Get Servers |
| type | Optional | 1 (default) or 2 — the key the server is listed under in Get Servers |
| currency | Optional | Return prices in this currency instead of PKR (e.g. USD). See Currency |
Responses
Price of one server: give the server id (and optionally type) — you get the price back. Replies in JSON.
$url = 'https://otpget.com/stubs/cheap_handler.php?api_key=' . $apiKey . '&action=getPrice&server=1';
$data = json_decode(file_get_contents($url), true);
echo $data['price'] . ' ' . $data['currency'];
url = "https://otpget.com/stubs/cheap_handler.php"
params = {"api_key": "YOUR_KEY", "action": "getPrice", "server": "1"}
print(requests.get(url, params=params).json())
Request Parameters
| Parameter | Required | Description |
|---|---|---|
| api_key | Required | Your API key |
| action | Required | getPrice |
| server | Required | Server id — from getServers |
| type | Optional | 1 or 2 (same as in getServers). Default 1 |
| currency | Optional | Return the price in this currency instead of PKR (e.g. USD). See Currency |
The price returned is the listed price in your account. It is the same figure getServices shows; with currency it is converted using the OTPGet currency converter, without it you always get PKR.
Responses
Buys a number on a server. The price is deducted from your wallet immediately and the number is held for about 20 minutes (the exact time in seconds is the third value of the reply). Replies in plain text: order_id,number,validity_seconds.
$url = 'https://otpget.com/stubs/cheap_handler.php?api_key=' . $apiKey . '&action=buyNumber&server=1';
echo file_get_contents($url); // plain text
url = "https://otpget.com/stubs/cheap_handler.php"
params = {"api_key": "YOUR_KEY", "action": "buyNumber", "server": "1"}
print(requests.get(url, params=params).text) # plain text
Request Parameters
| Parameter | Required | Description |
|---|---|---|
| api_key | Required | Your API key |
| action | Required | buyNumber |
| server | Required | Server id from Get Servers |
| type | Optional | 1 (default) or 2 — the key the server is listed under in Get Servers |
Responses
Checks whether the code for an order has arrived. Poll every few seconds. Replies in plain text.
Several codes on one number: keep polling after the first code — STATUS_OK always returns the newest code. To read every code received on the number, call action=getOtps&id=ORDER_ID (JSON: {"status":"200","count":2,"otps":[{"code":"222222","service":"...","time":"..."},{"code":"111111",...}]}, newest first). The number stays active until you finish it (setStatus 3/6) or its time runs out; it is then completed automatically. A number that never received a code is cancelled and refunded automatically when the time is over.
$url = 'https://otpget.com/stubs/cheap_handler.php?api_key=' . $apiKey . '&action=getStatus&id=ORDER_ID';
echo file_get_contents($url); // plain text
url = "https://otpget.com/stubs/cheap_handler.php"
params = {"api_key": "YOUR_KEY", "action": "getStatus", "id": "ORDER_ID"}
print(requests.get(url, params=params).text) # plain text
Request Parameters
| Parameter | Required | Description |
|---|---|---|
| api_key | Required | Your API key |
| action | Required | getStatus |
| id | Required | order_id from Buy Number (the first value of the CSV reply) |
Responses
One number can receive more than one code while it is active. Get Status always returns the newest code; this call returns every code received on the number, newest first. Replies in JSON.
$orderId = 'ORDER_ID';
$url = 'https://otpget.com/stubs/cheap_handler.php?api_key=' . $apiKey . '&action=getOtps&id=' . $orderId;
$data = json_decode(file_get_contents($url), true);
foreach ($data['otps'] as $o) echo $o['code'] . PHP_EOL;
url = "https://otpget.com/stubs/cheap_handler.php"
params = {"api_key": "YOUR_KEY", "action": "getOtps", "id": "ORDER_ID"}
for o in requests.get(url, params=params).json()["otps"]:
print(o["code"])
Request Parameters
| Parameter | Required | Description |
|---|---|---|
| api_key | Required | Your API key |
| action | Required | getOtps |
| id | Required | The order id returned by Buy Number |
Response fields
| Field | Description |
|---|---|
| status | "200" when the order was found |
| id | Your order id |
| number | The number, without a leading + |
| state | waiting (no code yet), received (one or more codes) or closed (finished / cancelled / expired) |
| count | How many codes were received |
| otps | List of {code, service, time}, newest first |
Responses
Finish an order after the code arrived, or cancel it for a full refund. Replies in plain text. Finishing (3 or 6) stops any further codes on that number; cancelling (8) is only possible while no code has arrived.
$url = 'https://otpget.com/stubs/cheap_handler.php?api_key=' . $apiKey . '&action=setStatus&id=ORDER_ID&status=8';
echo file_get_contents($url); // plain text
url = "https://otpget.com/stubs/cheap_handler.php"
params = {"api_key": "YOUR_KEY", "action": "setStatus", "id": "ORDER_ID", "status": "8"}
print(requests.get(url, params=params).text) # plain text
Request Parameters
| Parameter | Required | Description |
|---|---|---|
| api_key | Required | Your API key |
| action | Required | setStatus |
| id | Required | order_id from Buy Number |
| status | Required | 8 = cancel and refund (only before a code arrived) · 3 or 6 = finish (only after a code arrived) |
Responses
Temporary email addresses for OTP verification. A separate endpoint from SMS OTP and Rental — same api_key, own base URL and response shape.
Required in every request
| Parameter | Required | Description |
|---|---|---|
| api_key | Required | Your API key from the dashboard |
| action | Required | The operation to run (see the table below) |
| currency | Optional | Return amounts in this currency instead of PKR — see Currency |
| server | Optional | 1 (default) or 2 — used by Get Services, Buy Email and Get Domains. Actions on an existing order detect the server from email_id |
Server flows
| Server | Flow |
|---|---|
| 1 | Service-based — e.g. Instagram/Telegram codes on any in-stock domain (gmail.com, icloud.com, mailnestpro.com, hihinail.com, flytempbox.com, mailburstx.com, others). Buy with service_id + domain. |
| 2 | Domain + site based — you pick the mailbox domain (gmail.com, mail.com, gmx.com ...) and the site = the website you will use the email on (instagram.com, telegram.com ...). Supports reorderEmail for a fresh code on the same mailbox. Step-by-step example: see Server 2 Guide. |
Actions at a glance
| Action | Server | Extra required parameters | Returns |
|---|---|---|---|
| getBalance | Both | — | Wallet balance |
| getCurrencies | Both | — | Currency codes + rates |
| getEmailDomains | 1 / 2 | S2: site | S1: domains with stock · S2: domains for a site, with price and stock |
| getEmailServices | 1 / 2 | — | S1: services on a domain · S2: domains for a site |
| getPrice | 1 / 2 | — | Price of one email product (S1: service_id + domain · S2: domain + site) |
| buyEmail | 1 / 2 | S1: service_id · S2: domain | Email address + email_id |
| getEmailCode | Auto | email_id | Verification code |
| cancelEmail | Auto | email_id | Cancel + refund |
| reorderEmail | 2 | email_id | Fresh code on same mailbox |
| getEmailHistory | Both | — | Past orders (paginated) |
Response format
Every response is JSON. The HTTP status is always 200 — check the status field in the body (it is a string). Prices and balances are in PKR by default (optional currency parameter — see Currency).
200 success · 202 still waiting · 300 cancelled · anything else is an error — see Error Codes.
Typical flow
Server 1: getEmailDomains → getEmailServices (domain) → buyEmail (service_id + domain) → poll getEmailCode until 200 (or cancelEmail to refund).
Server 2: getEmailDomains&server=2&site=... or getEmailServices&server=2&site=... (domains for that site, same list) → buyEmail&server=2 (domain + site) → poll getEmailCode until 200 (or cancelEmail to refund) → optionally reorderEmail for another code.
On Server 2 you choose two things:
| Parameter | Meaning | Example |
|---|---|---|
| domain | The mailbox provider you want the address on | gmail.com, mail.com, gmx.com |
| site | The website where you will use this email (where you register / receive the code). Stock and price depend on it | instagram.com, telegram.com |
Always send the same site in Get Services, Get Price and Buy Email. If you leave site out, telegram.com is used — so the email may not match the website you actually register on. server=2 is required in Get Services, Get Price and Buy Email. After the purchase you only need email_id (the server is detected automatically). A full URL such as https://www.instagram.com/ is accepted and reduced to instagram.com.
Currency: add ¤cy=USD (any code from getCurrencies) to show prices and balance in that currency. Without it, everything is shown in PKR. Your wallet is always charged in PKR either way.
Step 1 — See which domains are available for your site
Lists every domain with its price and stock for this site. action=getEmailDomains and action=getEmailServices return the same list on Server 2 — use whichever you like.
Step 2 — Check the price of one domain (optional)
Same domain + site you will buy with.
Step 3 — Buy the email
Charges your wallet and returns the address. Keep the returned email_id — you need it for the next steps.
Step 4 — Use the email, then poll for the code
Enter the email on the website (the same site you bought for), then poll Get Code with the email_id every 3–5 seconds until status is 200. 202 means keep waiting. The code can also contain the full text of the email.
Step 5 — No code? Cancel and get a refund
Works only while the order is still waiting. Orders with no code after 30 minutes are cancelled and refunded automatically.
Step 6 — Need another code on the same email? Reorder
Only after you received the first code. It is billed like a new purchase and returns an email_id — poll Get Code with this new id. Add ¤cy=USD to see the price in USD.
Returns your current wallet balance. Works even if the email service is switched off.
$url = 'https://otpget.com/stubs/email-handler.php?api_key=' . $apiKey . '&action=getBalance';
$data = json_decode(file_get_contents($url), true);
print_r($data);
url = "https://otpget.com/stubs/email-handler.php"
params = {"api_key": "YOUR_KEY", "action": "getBalance"}
print(requests.get(url, params=params).json())
Request Parameters
| Parameter | Required | Description |
|---|---|---|
| api_key | Required | Your API key |
| action | Required | getBalance |
| currency | Optional | Return the balance in this currency instead of PKR (e.g. USD). See Currency |
Responses
Server 1: lists every email domain that currently has stock (gmail.com, icloud.com, mailnestpro.com, hihinail.com, flytempbox.com, mailburstx.com, others). Server 2: lists the domains available for one site (the website you will use the email on) with the price and stock of each. Use a returned domain value in Get Services, Get Price and Buy Email.
$url = 'https://otpget.com/stubs/email-handler.php?api_key=' . $apiKey . '&action=getEmailDomains&server=1';
// Server 2: add the site you will use the email on
// $url = 'https://otpget.com/stubs/email-handler.php?api_key=' . $apiKey . '&action=getEmailDomains&server=2&site=instagram.com';
$data = json_decode(file_get_contents($url), true);
print_r($data);
# Server 2
curl "https://otpget.com/stubs/email-handler.php?api_key=YOUR_API_KEY&action=getEmailDomains&server=2&site=instagram.com"
url = "https://otpget.com/stubs/email-handler.php"
params = {"api_key": "YOUR_KEY", "action": "getEmailDomains", "server": "1"}
# Server 2: params = {"api_key": "YOUR_KEY", "action": "getEmailDomains", "server": "2", "site": "instagram.com"}
print(requests.get(url, params=params).json())
Request Parameters
| Parameter | Required | Description |
|---|---|---|
| api_key | Required | Your API key |
| action | Required | getEmailDomains |
| server | Optional | 1 (default) or 2 |
| site | Server 2 | The website you will use the email on, e.g. instagram.com. Stock and price depend on it. If left out, telegram.com is used — send the same site in Get Price and Buy Email. |
| currency | Optional | Server 2 only (Server 1 has no prices here) — show prices in this currency instead of PKR, see Currency |
| all | Optional | Server 1 only: send 1 to include domains with zero stock |
Responses
Server 1: services (Instagram, Telegram, …) available on a domain, with price and stock. Server 2: domains available for a site, with price and stock. Prices are in PKR.
$url = 'https://otpget.com/stubs/email-handler.php?api_key=' . $apiKey . '&action=getEmailServices&server=1&domain=gmail.com';
$data = json_decode(file_get_contents($url), true);
print_r($data);
url = "https://otpget.com/stubs/email-handler.php"
params = {"api_key": "YOUR_KEY", "action": "getEmailServices", "server": "1", "domain": "gmail.com"}
print(requests.get(url, params=params).json())
Server 2 example — domains for a site
site = the website where you will use the email. The result lists each domain with its price and stock for that site. Use one of these domain values in Get Price / Buy Email with the same site.
$url = 'https://otpget.com/stubs/email-handler.php?api_key=' . $apiKey . '&action=getEmailServices&server=2&site=instagram.com';
$data = json_decode(file_get_contents($url), true);
print_r($data);
url = "https://otpget.com/stubs/email-handler.php"
params = {"api_key": "YOUR_KEY", "action": "getEmailServices", "server": "2", "site": "instagram.com"}
print(requests.get(url, params=params).json())
Request Parameters
| Parameter | Server 1 | Server 2 | Description |
|---|---|---|---|
| api_key | Required | Required | Your API key |
| action | Required | Required | getEmailServices |
| server | Optional | Required | 1 (default) or 2 |
| domain | Optional | Not used | Server 1: a domain from Get Email Domains. Default gmail.com. Invalid value returns 400 |
| site | Not used | Optional | Server 2: the website where you will use this email (e.g. instagram.com). Stock and price depend on it — pass the same site in Get Services and Buy. If omitted, telegram.com is used |
| currency | Optional | Optional | Return prices in this currency instead of PKR (e.g. USD). See Currency |
Responses
Price of one email product. Server 1: service_id + domain. Server 2: domain + site. Prices come live from the server, so the figure is the current price. Replies in JSON.
$url = 'https://otpget.com/stubs/email-handler.php?api_key=' . $apiKey . '&action=getPrice&server=1&service_id=ig&domain=gmail.com';
$data = json_decode(file_get_contents($url), true);
echo $data['price'] . ' ' . $data['currency'];
url = "https://otpget.com/stubs/email-handler.php"
params = {"api_key": "YOUR_KEY", "action": "getPrice", "server": "1", "service_id": "ig", "domain": "gmail.com"}
print(requests.get(url, params=params).json())
Server 2 example — price of one domain on a site
Needs both domain and site. The price is for that exact pair; no money is charged.
$url = 'https://otpget.com/stubs/email-handler.php?api_key=' . $apiKey . '&action=getPrice&server=2&domain=gmail.com&site=instagram.com';
$data = json_decode(file_get_contents($url), true);
print_r($data);
url = "https://otpget.com/stubs/email-handler.php"
params = {"api_key": "YOUR_KEY", "action": "getPrice", "server": "2", "domain": "gmail.com", "site": "instagram.com"}
print(requests.get(url, params=params).json())
Request Parameters
| Parameter | Required | Description |
|---|---|---|
| api_key | Required | Your API key |
| action | Required | getPrice |
| server | Optional | 1 (default) or 2 |
| service_id | Optional | Server 1: service code — from getEmailServices (e.g. ig) |
| domain | Optional | Server 1: default gmail.com. Server 2: required — from getEmailServices&server=2 |
| site | Optional | Server 2 only: the website where you will use this email (e.g. instagram.com). Use the same value you used in Get Services. If omitted, telegram.com is used |
| currency | Optional | Return the price in this currency instead of PKR (e.g. USD). See Currency |
The price returned is the listed price in your account. It is the same figure getEmailServices shows; with currency it is converted using the OTPGet currency converter, without it you always get PKR.
Responses
Purchases a temporary email address. The price is deducted from your wallet immediately. If no code arrives, cancel the order to get a refund.
$url = 'https://otpget.com/stubs/email-handler.php?api_key=' . $apiKey . '&action=buyEmail&server=1&service_id=ig&domain=gmail.com';
$data = json_decode(file_get_contents($url), true);
print_r($data);
url = "https://otpget.com/stubs/email-handler.php"
params = {"api_key": "YOUR_KEY", "action": "buyEmail", "server": "1", "service_id": "ig", "domain": "gmail.com"}
print(requests.get(url, params=params).json())
Server 2 example — buy an email (domain + site)
Send domain and the site where you will use the email — the same pair you checked in Get Services / Get Price. Save the returned email_id: it is used in Get Code, Cancel and Reorder. Your wallet is charged in PKR; currency only changes how the price/balance are shown.
$url = 'https://otpget.com/stubs/email-handler.php?api_key=' . $apiKey . '&action=buyEmail&server=2&domain=gmail.com&site=instagram.com';
$data = json_decode(file_get_contents($url), true);
print_r($data);
url = "https://otpget.com/stubs/email-handler.php"
params = {"api_key": "YOUR_KEY", "action": "buyEmail", "server": "2", "domain": "gmail.com", "site": "instagram.com"}
print(requests.get(url, params=params).json())
Request Parameters
| Parameter | Server 1 | Server 2 | Description |
|---|---|---|---|
| api_key | Required | Required | Your API key |
| action | Required | Required | buyEmail |
| server | Optional | Required | 1 (default) or 2 |
| service_id | Required | Not used | Server 1: service_code from Get Email Services (e.g. ig, tg, fb) |
| domain | Optional | Required | Server 1: default gmail.com, must be a valid domain. Server 2: a domain from Get Email Services |
| site | Not used | Optional | Server 2: the website where you will use this email (e.g. instagram.com). Stock and price depend on it — pass the same site in Get Services and Buy. If omitted, telegram.com is used |
| currency | Optional | Optional | Return the charged price (and balance) in this currency instead of PKR. Your wallet is still charged in PKR. See Currency |
Responses
Poll every 5–10 seconds after buying until the verification code arrives. The server is detected automatically from the email_id, so server is not needed.
$url = 'https://otpget.com/stubs/email-handler.php?api_key=' . $apiKey . '&action=getEmailCode&email_id=7291834';
$data = json_decode(file_get_contents($url), true);
print_r($data);
url = "https://otpget.com/stubs/email-handler.php"
params = {"api_key": "YOUR_KEY", "action": "getEmailCode", "email_id": "7291834"}
print(requests.get(url, params=params).json())
Request Parameters
| Parameter | Required | Description |
|---|---|---|
| api_key | Required | Your API key |
| action | Required | getEmailCode |
| email_id | Required | email_id returned by Buy Email |
Responses
Cancels an activation and refunds your wallet. If the code has already arrived, the order is completed instead and nothing is refunded.
$url = 'https://otpget.com/stubs/email-handler.php?api_key=' . $apiKey . '&action=cancelEmail&email_id=7291834';
$data = json_decode(file_get_contents($url), true);
print_r($data);
url = "https://otpget.com/stubs/email-handler.php"
params = {"api_key": "YOUR_KEY", "action": "cancelEmail", "email_id": "7291834"}
print(requests.get(url, params=params).json())
Request Parameters
| Parameter | Required | Description |
|---|---|---|
| api_key | Required | Your API key |
| action | Required | cancelEmail |
| email_id | Required | email_id returned by Buy Email |
| currency | Optional | Return the refunded amount (and balance) in this currency instead of PKR. See Currency |
Responses
Requests a fresh code on the same mailbox. It is billed like a new purchase and opens a new order that waits for the new code. Allowed only after the code of the current order was received. The response contains a (possibly new) email_id — poll getEmailCode with that id. Server 2 orders only; the server is detected from the email_id.
$url = 'https://otpget.com/stubs/email-handler.php?api_key=' . $apiKey . '&action=reorderEmail&email_id=7291834';
$data = json_decode(file_get_contents($url), true);
print_r($data);
url = "https://otpget.com/stubs/email-handler.php"
params = {"api_key": "YOUR_KEY", "action": "reorderEmail", "email_id": "7291834"}
print(requests.get(url, params=params).json())
Request Parameters
| Parameter | Required | Description |
|---|---|---|
| api_key | Required | Your API key |
| action | Required | reorderEmail |
| email_id | Required | email_id of a Server 2 order |
| currency | Optional | Return the charged price (and balance) in this currency instead of PKR. Your wallet is still charged in PKR. See Currency |
Responses
Your past email purchases, newest first. 20 per page.
$url = 'https://otpget.com/stubs/email-handler.php?api_key=' . $apiKey . '&action=getEmailHistory&page=1';
$data = json_decode(file_get_contents($url), true);
print_r($data);
url = "https://otpget.com/stubs/email-handler.php"
params = {"api_key": "YOUR_KEY", "action": "getEmailHistory", "page": "1"}
print(requests.get(url, params=params).json())
Request Parameters
| Parameter | Required | Description |
|---|---|---|
| api_key | Required | Your API key |
| action | Required | getEmailHistory |
| page | Optional | Page number, default 1 |
| currency | Optional | Return prices in this currency instead of PKR (e.g. USD). See Currency |
Responses
active = waiting for code · received = code delivered · cancelled = cancelled / refundedYour API key spends your wallet, so treat it like a password. These protections apply to every API on this page.
Protect your key
- Never put the key in a website, app or public repository. Call the API from your own server only. Anything in browser or app code can be read by anyone.
- Allowed IPs — Dashboard → API Tool → API Access Control. Add the IP address(es) of your server (one per line, or a range like
203.0.113.0/24). Requests from any other IP are refused withIP_NOT_ALLOWED, so a leaked key is useless. Empty = any IP. - Daily buy limit — the most buy requests (
getNumber,buyNumber,buyEmail,reorderEmail,rentNumber,renewRental) your key may send per rolling 24 hours, across all APIs.0= unlimited. - Recent API activity — the same page lists the IPs that used your key. If one is not yours, generate a new key at once.
- Changing these settings or viewing your key needs your email code or password, so a stolen key alone cannot switch them off.
Limits
| Limit | Value | Reply when exceeded |
|---|---|---|
| Requests per key | 3000 per minute | RATE_LIMITED (HTTP 429) |
| Buy requests per key | 300 per minute | RATE_LIMITED (HTTP 429) |
| Wrong / missing keys per IP | 60 per 10 minutes | RATE_LIMITED (HTTP 429) for every request from that IP until the window ends |
| Your daily buy limit | set by you | DAILY_LIMIT_REACHED (HTTP 429) |
| IP not in your list | — | IP_NOT_ALLOWED (HTTP 403) |
Text APIs return the code as plain text; JSON APIs return {"status":"429","message":"RATE_LIMITED"}. On HTTP 429 wait for the Retry-After seconds and slow your polling (every 3–5 seconds is plenty for getStatus). Sandbox keys are not affected by the IP list or the buy limit.
Error Codes
SMS OTP API — /stubs/handler_api.php
Returned as literal plain text (not JSON) by getBalance, getNumber, getStatus and setStatus — compare the raw response body directly against the values below. Auth errors also apply to the JSON actions.
| Code | Description |
|---|---|
| BAD_KEY | Missing or invalid API key. |
| ACCOUNT_BLOCKED | This account is suspended. |
| ACCOUNT_NOT_VERIFIED | The account owning this key has no verified email or no phone number yet. Complete it once at /complete-account. |
| BAD_COUNTRY / BAD_SERVICE / BAD_TYPE / BAD_ID / BAD_STATUS | A required parameter is missing, invalid, or has no matching record. |
| NO_SERVICE | getPrice: that service does not exist for the given server and country. |
| NO_BALANCE | Insufficient wallet balance for this purchase. |
| NO_BALANCE_FOR_NEW_PRICE:<price> | getNumber only — the live price rose above your balance. The number was released and nothing was charged; top up to at least <price> and try again. |
| NO_NUMBERS | No numbers currently available for that country/service. |
| NO_ACTIVATION | No activation found for this id on this account. |
| EARLY_CANCEL_DENIED | Numbers can only be cancelled 2 minutes after purchase, and only if the server accepts it — nothing is refunded. |
| NO_SMS_RECEIVED | Cannot finish the order — no SMS/code received yet. |
| STATUS_ALREADY_CHANGED | This activation was already finalized (finished or cancelled), or the server had already delivered the code. Check it with getStatus. |
| ERROR_PROVIDER_1-5:Server N error | The server for that type (the number in the code) had a problem, e.g. ERROR_PROVIDER_2:Server 2 error or ERROR_PROVIDER_2:Server 2 is temporarily unavailable. Nothing is charged — try again shortly or use another server. |
| BAD_CURRENCY | The currency value is not a supported code — see Get Currencies. Only returned by actions that return amounts; nothing is charged. |
Rental API — /stubs/rental-handler.php
| status | Example message | When it happens |
|---|---|---|
| 401 | Invalid API key. / API key is required. | Missing or invalid api_key |
| 403 | Account is blocked or inactive. | Account suspended |
| 400 | country_code is required. / provider is required. Use 1 or 2. / Invalid currency. / Cancel window expired… | Missing or invalid parameter, invalid duration for the server, or cancelRental outside the 20-minute window / on a Server 1 rental / after an SMS arrived |
| 402 | Insufficient balance. | Wallet balance too low |
| 404 | No pricing found… / Rental not found… / Order not found or access denied. | No pricing for that country/duration, or wrong rental_id / order_id |
| 502 | Server 1 error / Server 2 error | The upstream server had a problem — try again shortly. Nothing is charged |
| 503 | Server 1 is currently unavailable/disabled. | Server switched off in admin settings |
| 500 | Database error. Please try again. | DB transaction failed — balance not deducted |
Cheap Numbers API — /stubs/cheap_handler.php
Returned as literal plain text (not JSON).
| Code | Description |
|---|---|
| BAD_KEY | Missing or invalid API key. |
| ACCOUNT_BLOCKED | This account is suspended. |
| ACCOUNT_NOT_VERIFIED | The account owning this key has no verified email or no phone number yet. Complete it once at /complete-account. |
| BAD_CURRENCY | currency is not a supported code (see getCurrencies). Only returned by actions that return amounts. |
| BAD_ACTION | Unknown or missing action. |
| BAD_SERVER | server is missing, or that server does not exist / is inactive. |
| NO_SERVERS | getServers: no server is currently available. |
| NO_SERVICES | getServices: the server was not found or is inactive. |
| LOW_BALANCE | Insufficient wallet balance for this purchase. Nothing is charged. |
| NO_NUMBERS | No number could be allocated right now. Nothing is charged — try again shortly. |
| DATABASE_ERROR | The order could not be saved. The charge is reversed. |
| BAD_ID | id is missing. |
| NO_ACTIVATION | No order found for this id on this account. |
| BAD_STATUS | status is not 3, 6 or 8, or you tried to cancel an order that already received a code. |
| NO_SMS_RECEIVED | Cannot finish the order — no code received yet. |
| STATUS_CANCEL | getStatus: the order expired (refunded), was cancelled or was completed without a code — stop polling. |
Premium API — /stubs/premium-handler.php
Returned as literal plain text (not JSON).
| Code | Description |
|---|---|
| BAD_KEY | Missing or invalid API key. |
| ACCOUNT_BLOCKED | This account is suspended. |
| ACCOUNT_NOT_VERIFIED | The account owning this key has no verified email or no phone number yet. Complete it once at /complete-account. |
| BAD_CURRENCY | currency is not a supported code (see getCurrencies). Only returned by actions that return amounts. |
| BAD_ACTION | Unknown or missing action. |
| BAD_SERVER | server is missing, or that country does not exist / is inactive. |
| BAD_SERVICE | service is missing, or not available for that country. |
| NO_SERVICE | getPrice: that service does not exist for the given server. |
| NO_SERVERS | getServers: no country is currently available. |
| NO_SERVICES | getServices: no services found for that country. |
| LOW_BALANCE | Insufficient wallet balance for this purchase. Nothing is charged. |
| NO_NUMBERS | No number could be allocated right now. Nothing is charged — try again shortly. |
| PROVIDER_NOT_CONFIGURED | Premium is not set up or is currently disabled. |
| DATABASE_ERROR | The order could not be saved. The charge is reversed. |
| BAD_ID | id is missing. |
| NO_ACTIVATION | No order found for this id on this account. |
| BAD_STATUS | status is not 3, 6 or 8, or you tried to cancel an order that already received a code. |
| NO_SMS_RECEIVED | Cannot finish the order — no code received yet. |
| STATUS_CANCEL | getStatus: the order expired (refunded) or was closed without a code — stop polling. |
Email OTP API — /stubs/email-handler.php
| status | When it happens | Example message |
|---|---|---|
| 200 | Success (all actions) | {"status":"200", ...} |
| 202 | getEmailCode: no code yet — keep polling | Waiting for code... |
| 300 | Activation was cancelled (by you or automatically). Any charge is refunded | Activation was cancelled |
| 400 | Missing/unknown action, a required parameter is missing (service_id, domain, email_id), invalid Server 1 domain, or the action is not allowed for that order | Invalid domain. Use action=getEmailDomains for the list |
| 401 | Invalid or missing api_key | BAD_KEY |
| 402 | Wallet balance too low for the purchase | Low balance. Need: 120 PKR — Have: 45.5 PKR |
| 403 | Account suspended | ACCOUNT_BLOCKED |
| 404 | Service/domain not available, no stock, or email_id not found | Email activation not found |
| 500 | Upstream connection error or database error — nothing is charged when a purchase fails | Database error. Try again. |
| 503 | Email service disabled or not configured | Server 1 email service is disabled |