OnaySIM Developer & Reseller API Documentation
Connect OnaySIM's infrastructure to your web panels, SMS reseller sites, Telegram/WhatsApp bots or custom software in seconds. 100% compatible with the universal standard SMS protocol and REST architecture.
API Endpoints
Send all of your GET and POST requests to the following endpoints:
Connecting Web Panels & Reseller Systems
Integrate OnaySIM into your web panels and reseller platforms in 1 minute, no coding required:
- In your panel, go to the Add Provider page.
- Select Standard SMS API Protocol as the protocol or module type.
- Enter
https://onaysim.com/api/v1/handler.phpin the API URL field. - Enter your personal OnaySIM key (found in your profile) in the API Key field and save.
- All countries, services and wholesale reseller prices will be listed automatically right away.
Quick Start & Code Samples
Pick your favorite programming language and run test requests right away.
# 1. Check Balance
curl -X GET "https://onaysim.com/api/v1/handler.php?api_key=YOUR_API_KEY&action=getBalance"
# 2. Buy a WhatsApp (Turkey) Number
curl -X GET "https://onaysim.com/api/v1/handler.php?api_key=YOUR_API_KEY&action=getNumber&service=wa&country=62"
# 3. Check for the Incoming SMS Code (by activation_id)
curl -X GET "https://onaysim.com/api/v1/handler.php?api_key=YOUR_API_KEY&action=getStatus&id=123456"
# 4. Cancel the Number & Get a Balance Refund
curl -X GET "https://onaysim.com/api/v1/handler.php?api_key=YOUR_API_KEY&action=setStatus&id=123456&status=8"
API Parameter & Action Reference
All endpoints, parameters and standard response codes.
Required Parameters: api_key, action=getBalance
Optional: format=json
Returns: ACCESS_BALANCE:15.50 (as JSON: {"status":"ACCESS_BALANCE","balance":15.50,"currency":"USDT"})
Required Parameters: api_key, action=getPrices
Optional Filters: country=62, service=wa
Returns: A JSON price and stock matrix broken down by country and service.
Parameters:
service (e.g. wa, tg, go, ig, tw, dr),
country (e.g. 62=Turkey, 12=USA, 16=UK),
maxPrice (Optional price cap)
Success Response: ACCESS_NUMBER:ACTIVATION_ID:PHONE_NUMBER
Error Codes: NO_BALANCE (Insufficient balance), NO_NUMBERS (No numbers in stock), BAD_SERVICE (Invalid service)
Parameters: id (activation ID returned by getNumber)
Possible Responses:
STATUS_WAIT_CODE: No code yet, still waiting (poll again every 3-5 seconds).STATUS_OK:123456: The SMS code has arrived! The part after the colon is the received SMS code.STATUS_CANCEL: The number was canceled, or closed automatically when the 20-minute window expired, and the balance was refunded.
Parameters: id (Activation ID), status (Status code)
Status Codes:
status=8: Cancels the number, releases it at the provider and instantly issues a 100% refund of the amount spent to the user's balance (ACCESS_CANCEL).status=6: Marks the activation as successfully completed (ACCESS_ACTIVATION).status=1: Reports that the SMS has been sent to the number and you are ready to receive the code (ACCESS_READY).status=3: Requests another SMS code (ACCESS_RETRY_GET).
Standard Error Responses
| Error Code | Description | Solution |
|---|---|---|
| BAD_KEY | Invalid or missing API key. | Check the current API key in your profile. |
| ERROR_IP_NOT_ALLOWED | The IP address of the requesting server is not on your whitelist. | Update or remove the IP restriction on your profile page. |
| NO_BALANCE | Your balance is too low to buy this number. | Top up your balance with USDT (TRC-20). |
| NO_NUMBERS | No numbers are currently in stock for the selected country and service. | Choose a different country or try again in 1-2 minutes. |
| BAD_SERVICE | An invalid service code was specified. | Use a supported service code (wa, tg, go, etc.). |
| NO_ACTIVATION | No activation was found for the specified ID. | Make sure the order ID belongs to your account. |