SmsBuyz SMS Verification API: Developer Guide

If you verify accounts regularly as part of authorized work, such as QA for apps your team operates or onboarding accounts your organisation owns, clicking through the dashboard every time gets slow. The SmsBuyz v1 REST API exposes the same order flow as the website: buy a number, check the order until the SMS arrives, then finish or cancel. This guide walks through authentication, the endpoints, the order lifecycle and the errors your code should handle.

What can you do with the SmsBuyz API?

You can do everything the order panel does, from code. The documented endpoints are:

How do you authenticate API requests?

You authenticate by sending your API key as a Bearer token in the Authorization header. Get the key from Settings, then API, in your SmsBuyz account. A missing or malformed header returns 401; a key that does not match an account returns 403. Treat the key like a password: keep it on your server or in a secrets manager, never in front-end JavaScript or a public repository, and rotate it if it leaks.

How do you find valid country and product values?

Use the guest endpoints, which need no key. /v1/guest/products/{country}/any returns the products available for that country, each with a quantity and price, and /v1/guest/prices?product=...&country=... returns prices for a product. The country can be an ISO code such as us or a country name; the product can be a product name or its ID. For the operator segment, any lets SmsBuyz pick the available route. Prices and stock change, so read them close to the time you buy rather than hard-coding them.

How does the buy, check and finish flow work?

Every verification follows the same lifecycle. Here it is with curl (replace the order ID 123 with the id returned by the buy call):

TOKEN="your_api_key"

# 1. Check your balance
curl -s "https://smsbuyz.com/v1/user/profile" \
  -H "Authorization: Bearer $TOKEN" -H "Accept: application/json"

# 2. See what is available in a country (no key needed)
curl -s "https://smsbuyz.com/v1/guest/products/us/any" \
  -H "Accept: application/json"

# 3. Buy a number (country / operator / product)
curl -s "https://smsbuyz.com/v1/user/buy/activation/us/any/telegram" \
  -H "Authorization: Bearer $TOKEN" -H "Accept: application/json"

# 4. Check the order every few seconds until "sms" is not empty
curl -s "https://smsbuyz.com/v1/user/check/123" \
  -H "Authorization: Bearer $TOKEN" -H "Accept: application/json"

# 5a. Code used successfully: finish the order
curl -s "https://smsbuyz.com/v1/user/finish/123" \
  -H "Authorization: Bearer $TOKEN"

# 5b. No code and you no longer need it: cancel (refunds a PENDING order)
curl -s "https://smsbuyz.com/v1/user/cancel/123" \
  -H "Authorization: Bearer $TOKEN"

The buy response contains the order id, the phone number to enter in the target app, the status (PENDING), an expires timestamp and an empty sms array. When a message arrives, check returns status RECEIVED and each entry in sms has a code, the full text and a sender.

Which order statuses should your code handle?

Which errors should you handle?

Errors come back as JSON with an error message and an HTTP status code:

• 400: bad request, for example an unknown service or country, insufficient balance, or an invalid state change such as finishing an order that is not RECEIVED. Fix the input or top up; do not retry blindly.
• 401 / 403: missing or invalid key. Stop and fix credentials.
• 404: the order does not exist or does not belong to your account.
• 409: the order is busy with another request or is no longer pending. Wait a moment and check the order again.
• 503: no numbers available right now, or a cancellation could not be confirmed yet. Back off and retry later, or try another country.

What are good polling and cancellation practices?

Check each order every 3 to 5 seconds, as the documentation recommends; faster polling does not make the SMS arrive sooner. Stop checking at the expires time. If the target app rejects the number outright, cancel straight away rather than waiting. Note that a cancel request can return an order that already has a code, if the SMS arrived at the last moment; always read the status in the response. If a platform refuses a number, ban on a pending order closes it and stops that number being assigned to you again.

How do you test your integration safely?

Start with the guest endpoints, which need no key and cost nothing, to confirm that your country and product values resolve. Then place one real order by hand with curl and step through check and finish or cancel, so you can see every response before you write automation. Keep your test balance small. Log each order ID together with its status changes, and add a cleanup step that cancels any order still PENDING when your process exits. Finally, plan for a crash between buying and saving the order ID: on restart, list recent orders with /v1/user/orders and reconcile them with your records.

How should you use the API responsibly?

Use the API only for accounts you are authorized to create or manage, and follow each platform's terms and rate limits. Do not use it for fake accounts, spam or ban evasion. For running many orders at once, read our guide to high-volume verification. Common targets include Telegram, WhatsApp and Discord; check current costs with the prices endpoint before buying. Moving from another panel? The buy, check and finish-or-cancel flow is similar to the one described in our 5sim comparison.