NOVA SMS API v1

Buy temporary numbers and read SMS programmatically. REST over HTTPS, JSON responses. Your API key is created automatically for every account — find it under Profile → API access.

Authentication

Send your key in the Authorization header on every request. All requests must use HTTPS.

Authorization: Bearer YOUR_API_KEY

Base URL: https://nova-sms.com/api/v1 · Rate limit applies per key. Responses are { "ok": true, "data": {…} } or { "ok": false, "error": {…} }.

Endpoints

GET/balance

Your company balance.

{ "ok": true, "data": { "balance": 14.0912, "currency": "USD" } }

GET/services GET/countries

Catalog of available services (codes like tg, wa) and countries (numeric ids).

GET/prices?service=tg&country=6

Current price and availability for a service in a country.

{ "ok": true, "data": { "service": "tg", "country": 6, "price": 0.50, "available": 240, "in_stock": true } }

POST/activations

Buy a number. Body: service_code, country_id, optional operator.

curl -X POST -H "Authorization: Bearer YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"service_code":"tg","country_id":6}' \
  https://nova-sms.com/api/v1/activations

{ "ok": true, "data": { "activation": {
  "id": 123, "type": "sms", "number": "+1202...", "service": "tg",
  "country": 6, "price": 0.50, "status": "waiting",
  "code": null, "expires_at": "2026-06-02 10:20:00" } } }

GET/activations/{id}

Poll for the SMS code. status becomes sms_received and code is filled when a message arrives.

{ "ok": true, "data": { "activation": { "id": 123, "status": "sms_received", "code": "123456", "text": "Your code is 123456" } } }

GET/activations?limit=20&offset=0&status=waiting

List your activations (owners see the whole company, members see their own).

POST/activations/{id}/cancel POST/activations/{id}/complete

Cancel (refunds to your balance; allowed while waiting, min 3 min after purchase) or complete (after an SMS was received).

Error codes

unauthorized (401) — missing/invalid key

rate_limited (429) — too many requests

insufficient_balance (402) — top up on the website

out_of_stock (409) — no numbers for that service/country

not_found (404) — activation not visible to your key

invalid_state / too_early (409) — action not allowed in current state

NOVA SMS API v1

Authentication

Endpoints

Error codes

How was your experience?