Open the Telegram bot, go to 👤 Profile → 🔑 API Access, and activate — you receive an api_key to pass on every request. There's no minimum to activate; you only need enough balance to cover the numbers you buy (getNumber debits the price, so with too little balance it simply returns NO_BALANCE).
https://dev.otpkart.com/stubs/handler_api.phpcountry=<code> (from getCountries) is required to buy - the two-letter code (country=IN), or the numeric id where one is listed (country=22). Prices are in wallet points. Every reply is JSON: success is {"status":"success", …}, failure is {"status":"error","error":"CODE"}.Your current wallet balance (points).
# request GET ?api_key=KEY&action=getBalance # response {"status":"success","balance":100}
The countries you can buy in right now. Pass country (the two-letter code) - or id where it is not null - as country= to getPrices and getNumber.
GET ?api_key=KEY&action=getCountries {"status":"success","countries":[{"country":"IN","id":22,"name":"India","services":310},{"country":"US","id":null,"name":"United States","services":12}, ...]}
All available services as code → name.
GET ?api_key=KEY&action=getServiceList {"status":"success","services":{"go":"Google","wa":"WhatsApp","tg":"Telegram", ...}}
Every server that getNumber can buy from for a service, cheapest first (servers with a proven success rate under the platform's success floor (30% by default) are not listed, and cannot be bought from). getNumber requires one of these server ids. Add service=<code> for one service, or omit it for all services.
GET ?api_key=KEY&action=getPrices&service=go {"status":"success","prices":{"IN":{"go":[{"server":14,"cost":12,"success":95},{"server":10,"cost":13,"success":88}]},"US":{"go":[{"server":9,"cost":71.5,"success":70}]}}} # one country: every service sold there GET ?api_key=KEY&action=getPrices&country=IN # one service in one country GET ?api_key=KEY&action=getPrices&service=go&country=IN
The list has one branch per country (its two-letter code). Pass country=, service= or both - a call with neither is answered BAD_COUNTRY.
Pick a server id (by price and success, the recent delivery rate in %) and pass it to getNumber as server=<id> — it is required.
Buy a number for a service. service is a service code from getServiceList: the short API code, or the code the bot shows as /ser_<code> (every live service is listed). Required: server=<id>, a server id listed by getPrices for that service (provider=<id> is accepted as an alias).
GET ?api_key=KEY&action=getNumber&service=go&country=IN&server=14 # success — activation id, number, and the server it came from {"status":"success","id":40012345,"number":"917xxxxxxxxx","service":"go","server":14} # pick a cheaper server (id from getPrices) GET ?api_key=KEY&action=getNumber&service=go&country=IN&server=10
| Reply | Meaning |
|---|---|
{"status":"success","id":…,"number":…} | Number issued. Keep the id for status/cancel. |
{"error":"NO_NUMBERS"} | No stock right now — retry or try another service/server. |
{"error":"NO_BALANCE"} | Not enough points to buy this number. |
{"error":"BAD_SERVICE"} | Unknown service code - use a code from getServiceList. |
{"error":"BAD_COUNTRY"} | country is missing or unknown - pass a code from getCountries. |
{"error":"SERVER_REQUIRED"} | No server passed. Call getPrices&service=<code>, then pass one of the listed ids as server=<id>. |
{"error":"BAD_SERVER"} | The server you passed is not a positive integer, doesn't offer this service, is off, or is under the success floor. Use a server id listed by getPrices. |
getPrices&service=<code> to see every server's id, price and success%,
pick one, and pass it as server=<id> on getNumber. Only listed servers can be bought from, so the
charge always equals a quoted price. (provider=<id> still works as an alias for server.)
Calls that omit server are being phased out: for a short period they may still be served from a default
server (and are logged); after that they answer SERVER_REQUIRED.
Poll for the SMS. getStatus returns the code and the full SMS; getStatusFull returns the code only (drops the sms field).
GET ?api_key=KEY&action=getStatus&id=40012345 {"status":"success","state":"waiting"} # still waiting {"status":"success","state":"ok","code":"123456","sms":"Your code is 123456"} # delivered {"status":"success","state":"cancel"} # cancelled & refunded
Cancel an activation with status=8. The cancel is queued and processed within ~1 minute; the reply just acknowledges it. You are refunded only if no code ever arrived (a delivered code = number used = no refund). Some servers refuse an early cancel for the first ~2 minutes — the request is retried automatically, and an unused number is refunded at its timeout regardless. Poll getStatus; it returns state:"cancel" once the cancel has resolved. A few servers can't cancel a live number at all — for those the reply adds refund:"on_timeout" plus a message, and the number is auto-refunded when it times out if no code arrived.
GET ?api_key=KEY&action=setStatus&id=40012345&status=8 {"status":"success","state":"cancel"}
# 0. see which servers sell Google numbers, and at what price curl "https://dev.otpkart.com/stubs/handler_api.php?api_key=KEY&action=getPrices&service=go" {"status":"success","prices":{"22":{"go":[{"server":14,"cost":12,"success":95},{"server":10,"cost":13,"success":88}]}}} # 1. buy a Google number from server 14 curl "https://dev.otpkart.com/stubs/handler_api.php?api_key=KEY&action=getNumber&service=go&country=IN&server=14" {"status":"success","id":40012345,"number":"917xxxxxxxxx","service":"go","server":14} # 2. poll until the code arrives curl "https://dev.otpkart.com/stubs/handler_api.php?api_key=KEY&action=getStatus&id=40012345" {"status":"success","state":"ok","code":"123456","sms":"Your Google code is 123456"} # 3. or cancel to get refunded if nothing came curl "https://dev.otpkart.com/stubs/handler_api.php?api_key=KEY&action=setStatus&id=40012345&status=8" {"status":"success","state":"cancel"}
Every error is {"status":"error","error":"<CODE>"} (HTTP 200). The codes:
| error | Meaning |
|---|---|
BAD_KEY | Missing/invalid key, or API not activated for this account. |
BAD_SERVICE | Unknown service code - use a code from getServiceList. |
BAD_COUNTRY | country is missing (it is required to buy) or unknown. Pass the two-letter code from getCountries, or the numeric id where one is listed. |
BAD_ACTION | Unknown action. |
NO_NUMBERS / NO_BALANCE | No stock / not enough points. |
NO_ACTIVATION | Unknown activation id (or not yours). |
SERVER_REQUIRED | getNumber without server=. Pick a server id from getPrices and pass it. |
BAD_SERVER | The server value is not a positive integer, doesn't offer this service, is off, or is under the success floor. Pick one from getPrices. |
BAD_STATUS | setStatus called with an unsupported status value. |
MAINTENANCE | The platform is restarting or under maintenance (any action). Wait a few seconds and send the same request again. |
Paste your api_key to see your own orders. It's remembered in this browser only. Costs are in wallet points.