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 /

MethodEndpointRequest and result
GET/countriesReturns an array of country_code and country_name.
GET/servicesLists 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/getbalanceReturns email, balance and currency.
POST/order-serviceSend country_code, service_code, amount and numeric order_source: 2. Returns orderid, number, start_time, end_time, status and amount_deducted.
POST/cancel-orderSend orderid and reason. Read the returned status to determine whether the order was refunded or completed.
POST/complete-orderSend 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

MethodActionRequest and result
GETgetCountriesLists numeric country IDs with their English names.
GETgetServicesListList service codes and names. Supply country to filter.
GETgetPricesSupply country and service for one quote, or omit them for a catalog of prices and counts.
GETgetBalanceReturns ACCESS_BALANCE followed by a colon and the USD balance.
GETgetNumberSupply country and service, optionally maxPrice. Returns ACCESS_NUMBER:<id>:<phone>.
GETgetNumberV2Takes the same order parameters. Returns JSON including activationId, phoneNumber and activationCost.
GETsetStatusSupply 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/

MethodEndpointRequest and result
GETgetTariffs.phpReturns countries, services and prices. Set country to show its services. Filter with filter_country or filter_service. Use page and count for pagination.
GETgetBalance.phpReturns response, balance and zbalance. balance is a USD string and zbalance is zero.
GETgetNum.phpSupply country and service. Add number=true to include the assigned phone number alongside tzid.
GETsetOperationOk.phpSupply 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

MethodEndpointRequest and result
GET/country/retrieve_allLists ID, name and ISO short_name.
GET/service/retrieve_allLists service IDs and names. Optionally supply country.
GET/request/pricingReturns country, service and price rows. Optionally filter by country, service or max_price.
GET/sms/all_stockReturns pricing rows and the stock count for each service.
GET/request/priceSupply country and service to get a single price.
GET/sms/stockSupply country and service. Add include_price=1 for a quote alongside the available amount.
GET/request/balanceReturns your available USD balance.
POST/purchase/smsSupply country and service, optionally max_price. Returns success, order_id, number, cc, phonenumber, cost, expiration and expires_in.
POST/sms/cancelPass the returned UUID in orderid. A refunded cancellation returns success: 1.
POST/sms/completePass 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.