OTP Verification API in Python: Order a Number and Read the Code

If you build or test sign-up flows, you will eventually want to receive an SMS code from your own script. This guide shows an OTP verification API in Python example for the OtpGet SMS API: order a number, wait for the code and finish or cancel the order.

Short answer: send a GET request with your api_key and action=getNumber, read the order ID and number from the reply, poll getStatus until it returns a code, then call setStatus to complete or cancel. The replies are plain text, so split on the colon.

What you need

• A free account and your API key from the dashboard.
• A service ID and a country ID. The getServices and getCountries actions list them.
• Python 3 and the requests library.

Working example

import time
import requests

API_KEY = "YOUR_API_KEY"
BASE = "https://otpget.com/stubs/handler_api.php"

def call(action, **params):
    params.update({"api_key": API_KEY, "action": action})
    r = requests.get(BASE, params=params, timeout=20)
    return r.text.strip()

def get_code(service_id, country_id, wait_seconds=120):
    reply = call("getNumber", service=service_id, country=country_id, type=1)
    if not reply.startswith("ACCESS_NUMBER"):
        raise RuntimeError("Order failed: " + reply)
    _, order_id, number, price = reply.split(":")
    print("Use this number in the app:", number)
    deadline = time.time() + wait_seconds
    while time.time() < deadline:
        status = call("getStatus", id=order_id)
        if status.startswith("STATUS_OK"):
            code = status.split(":", 1)[1]
            call("setStatus", id=order_id, status=6)
            return code
        if status == "STATUS_CANCEL":
            return None
        time.sleep(5)
    call("setStatus", id=order_id, status=8)
    return None

print(get_code("SERVICE_ID", "COUNTRY_ID"))

How it works

• ACCESS_NUMBER:order_id:number:price is the success reply for an order.
• STATUS_WAIT_CODE means keep polling, and STATUS_OK:123456 carries the code.
• setStatus with 3 or 6 completes the order after an SMS arrived. Status 8 cancels for a refund and is allowed two minutes after purchase.
• Errors come back as short words such as BAD_KEY, NO_BALANCE or BAD_SERVICE.

The exact replies for every action are in the API documentation. Check them before you parse.

Good habits

• Keep the key in an environment variable, not in your code.
• Set a maximum wait and cancel when it passes.
• Stop on NO_BALANCE instead of retrying.
• Log order IDs so you can trace problems.
• Amounts are in PKR by default; add a currency parameter if you prefer another one.

Handling errors properly

A script that works once is not the same as a script that works every day. Wrap the order call so a failure is logged with the exact reply text. Treat NO_BALANCE as a hard stop and alert yourself, because retrying will not help. Treat BAD_SERVICE and BAD_COUNTRY as configuration errors and fix the IDs. If the reply is empty or the request times out, check the order status before you place another order, so that you do not pay for two numbers when one was already issued. Keep the order ID in a log file or a small database table.

Extending the example

• Several orders at once: run each in its own thread or an async task, and cap how many can be open.
• A queue: push order requests to a queue so spikes do not exhaust your balance.
• Webhooks: if your app triggers the SMS, start polling only after the trigger so that the wait window starts at the right moment.
• Testing: record a reply for each status in a test file and run your parser against it before you spend money.

Combine this with the advice in staging OTP testing for a full test strategy.

Frequently Asked Questions

Why is the response not JSON?

The SMS API keeps a plain-text protocol for compatibility. Other endpoints, such as rentals, reply in JSON.

How often should I poll?

Every five seconds is common. Do not poll faster than you need to.

Can I get a refund if no code arrives?

Yes, cancel the order when the rules allow it and the amount returns to your wallet. See the refund policy.

Is this allowed for any use?

Use it lawfully and follow the rules of every service you verify.

Conclusion

Order, poll, complete or cancel. Get your API key and read the OTP API overview for the rest. More guides: OtpGet blog.