API

NumVersal API documentation

Order virtual numbers, read OTP codes, buy travel eSIM and top up your balance from your own app, bot or panel. One API key, plain JSON, no SDK required.

Get your API key See pricing eSIM API

Authentication

Create a key in your dashboard under API access. Send it on every request as a bearer token (or in the X-API-Key header). Keys are shown only once — store them securely and never expose them in a browser.

curl https://numversal.com/api/public/v1/balance \
  -H "Authorization: Bearer nv_live_xxxxxxxxxxxx"

Base URL: https://numversal.com/api/public/v1 — all responses are JSON with a success flag; errors return { "success": false, "error": "..." } with status 400, 401 or 404.

Endpoints

GET/api/public/v1/balance

Your wallet balance in IDR and USD, plus the current USD rate.

response { "success": true, "data": { "balance_idr": 250000, "balance_usd": 15.34, "usd_rate": 16300 } }

GET/api/public/v1/countries

All countries available for ordering.

response { "success": true, "data": [ { "id": "6", "name": "Indonesia" } ] }

GET/api/public/v1/services?country_id=6

Services with live stock and your selling price for one country.

response { "success": true, "data": [ { "id": "wa", "name": "WhatsApp", "stock": 42, "price_idr": 4500, "price_usd": 0.28 } ] }

POST/api/public/v1/orders

Buy a number. The price is charged from your balance immediately.

request  { "country_id": "6", "service_id": "wa" }

response { "success": true, "data": { "id": "uuid", "phone_number": "628xxxx", "code": null, "status": "waiting", "price": 4500 } }

GET/api/public/v1/orders/{id}

Poll an order — returns the OTP code as soon as it arrives.

response { "success": true, "data": { "id": "uuid", "code": "123456", "status": "received" } }

POST/api/public/v1/orders/{id}

Close an order. action=cancel refunds your balance (only before a code arrives), action=finish completes it.

request  { "action": "cancel" }

response { "success": true, "data": { "id": "uuid", "status": "cancelled" } }

POST/api/public/v1/topups

Create a top up. QRIS returns a QR string, PayPal returns a checkout URL. Fees: 1% QRIS, 4.4% + $0.30 PayPal.

request  { "method": "qris", "amount": 100000 }

response { "success": true, "data": { "reference": "TOPXXXX", "amount": 100000, "fee": 1000, "qr_string": "000201...", "checkout_url": null } }

GET/api/public/v1/topups/{reference}

Check a top up. Returns paid as soon as the payment settles.

response { "success": true, "data": { "reference": "TOPXXXX", "status": "paid" } }

GET/api/public/v1/esim/products?destination=japan

eSIM catalog with your selling price. Optional destination filter matches the country name.

response { "success": true, "data": [ { "sku": "ESIMJP5", "name": "eSIM Japan 5GB 30D", "destination": "Japan", "stock": null, "price_idr": 95000, "price_usd": 5.83 } ] }

POST/api/public/v1/esim/orders

Buy an eSIM. Charged from the same balance as virtual numbers; failed orders are refunded automatically.

request  { "sku": "ESIMJP5", "customer_no": "you@example.com" }

response { "success": true, "data": { "id": "uuid", "ref_id": "NVE-XXXX", "status": "pending", "price": 95000, "sn": null } }

GET/api/public/v1/esim/orders/{id}

Poll an eSIM order. Once status is success, sn holds the activation code (LPA string).

response { "success": true, "data": { "id": "uuid", "status": "success", "sn": "LPA:1$rsp.truphone.com$KO-34W19H-XXXX" } }

Typical flow

1
Top up your balance (or call POST /topups).
2
Pick a country and service from the catalog endpoints.
3
POST /orders to get a number instantly.
4
Poll GET /orders/{id} until code is filled, then finish or cancel.

Rate limits are generous but abusive traffic can get a key revoked.