Public API reference
Find a number, check a price, and manage a short rental from your application. Your mysmsline public API key works with all four interfaces.
- Gateway URL
https://api.mysmsline.com
Making requests
Set API_BASE to the public gateway URL and PUBLIC_KEY to your integration key on your server. The examples use those shell variables. Keep credentials out of client-side JavaScript, access logs, and source control.
Read the catalog for the interface you use. Country IDs and service identifiers vary between formats. The values in the examples illustrate a response and can differ from live availability.
Send an Idempotency-Key header with each purchase. Choose a unique value for each intended order and reuse it on a retry of that same order. HTTP 202 means allocation is still under review. Keep the order ID and check its outcome before starting another purchase. For compatibility requests, the UUID is returned in x-mysmsline-order-id on this response.
Native API
Use the native JSON interface when building a new integration. Send your customer public key in x-api-key. Money values are decimal strings in USD.
Base path /
| Method | Endpoint | Request and result |
|---|---|---|
GET | /countries | Returns an array of country_code and country_name. |
GET | /services | Lists service_name, short_code, country_code, actual_price, offer_price and available_count. |
GET | /services/{country} | Lists services and current stock for one country code. |
GET | /services/{country}/{service} | Returns one service object. Use its offer_price when present, otherwise actual_price. |
GET | /getbalance | Returns email, balance and currency. |
POST | /order-service | Send country_code, service_code, amount and numeric order_source: 2. Returns orderid, number, start_time, end_time, status and amount_deducted. |
POST | /cancel-order | Send orderid and reason. Read the returned status to determine whether the order was refunded or completed. |
POST | /complete-order | Send orderid. Returns orderid and the final status. |
Look up a service
curl "$API_BASE/services/usaphysical/wa" -H "x-api-key: $PUBLIC_KEY"
Example response
{"country_code":"usaphysical","service_name":"WhatsApp","short_code":"wa","actual_price":"1.00","offer_price":"0.85","available_count":1000}
Create a rental
Use the price from your latest service lookup and a fresh purchase key. This request places a paid order.
curl -X POST "$API_BASE/order-service" \
-H "x-api-key: $PUBLIC_KEY" \
-H "Idempotency-Key: $PURCHASE_KEY" \
-H "Content-Type: application/json" \
-d '{"country_code":"usaphysical","service_code":"wa","amount":"0.85","order_source":2}'
POST requests take application/json. A native error typically contains error and request_id. For a price change, fetch the current service quote before deciding whether to place a new order.
compactable1
Send GET requests to the handler with an action parameter. Use x-api-key or the api_key parameter. Prices and service lists return JSON. Balance and basic number allocation return plain text.
Base path /compactable1/stubs/handler_api.php
| Method | Action | Request and result |
|---|---|---|
GET | getCountries | Lists numeric country IDs with their English names. |
GET | getServicesList | List service codes and names. Supply country to filter. |
GET | getPrices | Supply country and service for one quote, or omit them for a catalog of prices and counts. |
GET | getBalance | Returns ACCESS_BALANCE followed by a colon and the USD balance. |
GET | getNumber | Supply country and service, optionally maxPrice. Returns ACCESS_NUMBER:<id>:<phone>. |
GET | getNumberV2 | Takes the same order parameters. Returns JSON including activationId, phoneNumber and activationCost. |
GET | setStatus | Supply the returned numeric id and status=8 to cancel, or status=6 to complete. |
Get price and stock
curl "$API_BASE/compactable1/stubs/handler_api.php?action=getPrices&country=187&service=wa" -H "x-api-key: $PUBLIC_KEY"
Example response
{"187":{"wa":{"cost":0.85,"count":1000}}}
Read the body even on HTTP 200. BAD_KEY indicates an invalid credential. NO_NUMBERS can indicate unavailable stock or a price above maxPrice. EARLY_CANCEL_DENIED means the cancellation window has not opened.
compact2
Use the named PHP methods with your public key in x-api-key or the apikey parameter. The methods return JSON. Save the numeric tzid from each successful allocation.
Base path /compact2/api/
| Method | Endpoint | Request and result |
|---|---|---|
GET | getTariffs.php | Returns countries, services and prices. Set country to show its services. Filter with filter_country or filter_service. Use page and count for pagination. |
GET | getBalance.php | Returns response, balance and zbalance. balance is a USD string and zbalance is zero. |
GET | getNum.php | Supply country and service. Add number=true to include the assigned phone number alongside tzid. |
GET | setOperationOk.php | Supply tzid and ban=1 to cancel, or ban=0 to complete. Returns response and tzid. |
Check your balance
curl "$API_BASE/compact2/api/getBalance.php" -H "x-api-key: $PUBLIC_KEY"
Example response
{"response":"1","balance":"12.000000000000000000","zbalance":0}
Tariffs and balance return the string "1" in response on success. Allocation and completion return the number 1. Errors use a descriptive string such as ERROR_WRONG_KEY or WARNING_LOW_BALANCE.
compact3
Send your public key in x-api-key, as a bearer token, or in the key parameter. The routes accept GET query parameters and POST bodies encoded as a form or JSON. Examples below use POST for purchases and order changes.
Base path /compact3
| Method | Endpoint | Request and result |
|---|---|---|
GET | /country/retrieve_all | Lists ID, name and ISO short_name. |
GET | /service/retrieve_all | Lists service IDs and names. Optionally supply country. |
GET | /request/pricing | Returns country, service and price rows. Optionally filter by country, service or max_price. |
GET | /sms/all_stock | Returns pricing rows and the stock count for each service. |
GET | /request/price | Supply country and service to get a single price. |
GET | /sms/stock | Supply country and service. Add include_price=1 for a quote alongside the available amount. |
GET | /request/balance | Returns your available USD balance. |
POST | /purchase/sms | Supply country and service, optionally max_price. Returns success, order_id, number, cc, phonenumber, cost, expiration and expires_in. |
POST | /sms/cancel | Pass the returned UUID in orderid. A refunded cancellation returns success: 1. |
POST | /sms/complete | Pass orderid to mark the rental complete. This is a mysmsline extension. |
Check availability
curl "$API_BASE/compact3/sms/stock?country=US&service=WhatsApp&include_price=1" -H "Authorization: Bearer $PUBLIC_KEY"
Example response
{"success":1,"amount":1000,"price":"0.85"}
Country accepts a mapped numeric ID or ISO code. Service accepts a catalog ID, display name, or short code. Check success and message on purchase and finish responses. Stock and prices can change between lookup and purchase.