API Reference
Merchant API v1
Programmatically purchase SMS verification numbers, poll OTP status, manage cancellations, renew eligible numbers, and receive webhook events — using the same API keys from your dashboard.
https://realnonvoipusnumber.com/api/v1
Authentication
All protected endpoints require an API key created in the API Dashboard.
X-Api-Key: YOUR_API_KEY
Alternatively:
Authorization: Bearer YOUR_API_KEY
Production keys use the nvl_live_ prefix. Test keys use nvl_test_.
Quick Start
- Create an API key in the dashboard and copy it once.
GET /balanceto confirm authentication.GET /servicesfor every service on the user dashboard.GET /countries?service=wafor every country of that service.GET /servers?service=wa&country=187for every server (same list as the dashboard).POST /verificationswith that id and anIdempotency-Key.GET /verifications/{id}untilmessagescontains your OTP (or receive a webhook).
Errors
Every RealNonVoIPUSNumber API response is branded and includes a machine-readable error code:
{
"success": false,
"brand": "RealNonVoIPUSNumber",
"request_id": "rnvs_req_8f29c1a2b3c4",
"error": {
"code": "RNVS_INVALID_API_KEY",
"message": "The API key is invalid or missing.",
"retryable": false,
"request_id": "rnvs_req_8f29c1a2b3c4"
}
}
Use error.code in your client (do not parse message text). Common codes:
RNVS_INVALID_API_KEY,RNVS_API_KEY_DISABLEDRNVS_INSUFFICIENT_BALANCERNVS_INVALID_SERVICE,RNVS_SERVER_NOT_AVAILABLE,RNVS_NUMBER_NOT_AVAILABLERNVS_PROVIDER_UNAVAILABLE,RNVS_PROVIDER_TIMEOUT,RNVS_PROVIDER_ERRORRNVS_ORDER_NOT_FOUND,RNVS_CANCEL_FAILED,RNVS_ORDER_ALREADY_COMPLETEDRNVS_RATE_LIMITED,RNVS_INTERNAL_ERROR
Provider raw errors are never returned. Responses also include header X-Request-Id.
Rate Limits
Default limit: 300 requests per minute per API key.
One POST /orders/bulk counts as one request even when it queues hundreds of numbers.
Full catalog sync tip: call GET /catalog?limit=2000 and page through meta.totalPages. At the default rate limit this finishes well under a minute for ~110k offers.
Headers: X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset. Exceeded calls return 429 with Retry-After and branded code RNVS_RATE_LIMITED / legacy RATE_LIMIT_EXCEEDED.
Test Mode
Pass ?test=true or use a nvl_test_ key. Test mode never charges balance and never calls SMS providers. Catalog and create responses are deterministic mock data marked with "test": true.
Webhooks
Configure endpoints in the dashboard. Events include verification.created, verification.otp_received, verification.completed, verification.cancelled, verification.renewed.
Each delivery includes:
X-Webhook-Signature— HMAC-SHA256 hex digest of the raw body using your signing secretX-Webhook-Delivery— unique delivery idX-Webhook-Event— event name
import hmac, hashlib
sig = hmac.new(secret.encode(), body, hashlib.sha256).hexdigest()
Idempotency
Send Idempotency-Key: UNIQUE_REQUEST_ID on POST /verifications, POST /orders/bulk (required when quantity > 1), and POST /renew. Retries with the same key return the original result and do not create duplicate charges.
/api/v1/balanceReturns the authenticated account balance.
curl https://realnonvoipusnumber.com/api/v1/balance \
-H "X-Api-Key: YOUR_API_KEY"
{
"success": true,
"brand": "RealNonVoIPUSNumber",
"request_id": "rnvs_req_…",
"data": { "balance": 25.5, "currency": "USD" },
"meta": { "test": false }
}
/api/v1/servicesEvery service the user dashboard lists. data.services[].name is the readable service name (WhatsApp). data.services[].code is the code you pass as service (wa).
curl "https://realnonvoipusnumber.com/api/v1/services" \
-H "X-Api-Key: YOUR_API_KEY"
/api/v1/countriesEvery country for one service, including countries that are currently out of stock. Required query: service (dashboard service code).
curl "https://realnonvoipusnumber.com/api/v1/countries?service=wa" \
-H "X-Api-Key: YOUR_API_KEY"
/api/v1/serversEvery server the dashboard shows for that service and country: Grizzly, HeroSMS, NonVoIP, and VerifySMS when each is available. Required query: service and country (country id from /countries, United States is 187).
curl "https://realnonvoipusnumber.com/api/v1/servers?service=wa&country=187" \
-H "X-Api-Key: YOUR_API_KEY"
/api/v1/catalogPurchasable offers. Each item’s productServiceId (RNVS-P-…) is what you send to create a verification. This is the same inventory as the user dashboard, not one service per country.
service+country— every server for that pair (same as/servers).serviceonly — every server in every country for that service. Readmeta.totaland followpageuntil you have them all.- No filters, or
scope=all— every Grizzly and HeroSMS server for every service and country, paginated (page,limitup to 2000).
Query: service, country, page, limit (1–2000), scope=all, test.
meta includes total, totalPages, page, and limit. data is a JSON array of offer rows (not nested under offers).
Auth: send the full Production key (nvl_live_…) in X-Api-Key. The dashboard “Copy prefix” button is not a working key. Test keys never return live stock.
curl "https://realnonvoipusnumber.com/api/v1/catalog?limit=2000&page=1" \
-H "X-Api-Key: YOUR_API_KEY"
curl "https://realnonvoipusnumber.com/api/v1/catalog?service=wa&country=187" \
-H "X-Api-Key: YOUR_API_KEY"
Each row includes the readable service name and the serviceCode used to order:
{
"service": "WhatsApp",
"serviceCode": "wa",
"country": "United States",
"countryId": "187",
"server": "Server 1",
"serverName": "Server 1",
"productServiceId": "RNVS-P-…",
"price": 0.5,
"available": true
}
/api/v1/verificationsPaginated history for the authenticated account. Query: page, limit, status, from, to.
/api/v1/verificationsCreate a number order through the RealNonVoIPUSNumber stack. Selling price is always calculated server-side.
curl -X POST https://realnonvoipusnumber.com/api/v1/verifications \
-H "X-Api-Key: YOUR_API_KEY" \
-H "Idempotency-Key: UNIQUE_REQUEST_ID" \
-H "Content-Type: application/json" \
-d '{"productServiceId":"RNVS-P-…"}'
{
"success": true,
"brand": "RealNonVoIPUSNumber",
"request_id": "rnvs_req_…",
"data": {
"verificationId": "154785",
"orderId": "#24890552",
"numberId": "RNVS-N-000154785",
"phoneNumber": "+19703453333",
"status": "pending",
"lifecycle": "WAITING_FOR_SMS",
"productServiceId": "RNVS-P-…",
"service": "WhatsApp",
"server": "Server 2",
"price": 0.30,
"messages": []
},
"order": {
"order_id": "#24890552",
"number_id": "RNVS-N-000154785",
"service": "WhatsApp",
"country": "United States",
"phone_number": "+19703453333",
"server": "Server 2",
"price": "0.30",
"status": "WAITING_FOR_SMS"
}
}
JavaScript
const res = await fetch("https://realnonvoipusnumber.com/api/v1/verifications", {
method: "POST",
headers: {
"X-Api-Key": process.env.RNV_API_KEY,
"Idempotency-Key": crypto.randomUUID(),
"Content-Type": "application/json"
},
body: JSON.stringify({ productServiceId: "RNVS-P-…" })
});
Python
import os, requests, uuid
r = requests.post(
"https://realnonvoipusnumber.com/api/v1/verifications",
headers={
"X-Api-Key": os.environ["RNV_API_KEY"],
"Idempotency-Key": str(uuid.uuid4()),
},
json={"productServiceId": "RNVS-P-…"},
)
print(r.json())
/api/v1/orders/bulk
Queue many number purchases in one request. The API reserves the full wallet amount immediately,
returns order ids with status queued, and a background worker buys numbers.
The dashboard active-number cap stays 15. API and bulk orders may hold up to
50 numbers waiting for OTP; the rest stay queued until a slot frees.
service and country accept codes or names (wa / whatsapp,
187 / US / USA). Omit productServiceId to use the cheapest
available server from the same list as the dashboard. Header Idempotency-Key is required when
quantity > 1. Max quantity is 500. Partial provider failures mark that row
failed and refund that unit only; other rows continue.
Poll OTP with GET /verifications/{id}. Cancel one order with the existing cancel endpoint — that does not cancel the rest of the batch.
curl -X POST https://realnonvoipusnumber.com/api/v1/orders/bulk \
-H "X-Api-Key: YOUR_API_KEY" \
-H "Idempotency-Key: UNIQUE_BULK_REQUEST_ID" \
-H "Content-Type: application/json" \
-d '{"service":"wa","country":"187","quantity":300}'
{
"success": true,
"brand": "RealNonVoIPUSNumber",
"data": {
"batchId": 12,
"status": "accepted",
"totalRequested": 300,
"totalQueued": 300,
"totalFailed": 0,
"unitPrice": 0.5,
"reservedAmount": 150.0,
"orders": [
{"orderId": "#24890552", "verificationId": "154785", "status": "queued"}
]
}
}
/api/v1/orders/bulk/{batchId}Paginated orders for that batch, using the same verification serializer as the list endpoint. Another account cannot read your batch.
/api/v1/verifications/{id}
Poll status and OTP. data.otp is the latest code (backwards compatible).
data.messages lists all unique SMS/OTP events for the order (Grizzly and HeroSMS
support multiple messages during the active window).
While the order is still inside its active multi-OTP window (≈20 minutes for Grizzly/HeroSMS),
status stays pending / lifecycle OTP_RECEIVED or
WAITING_FOR_SMS even after the first code — keep polling to receive additional messages.
After the window ends (or single-OTP providers complete), status becomes completed.
{
"success": true,
"brand": "RealNonVoIPUSNumber",
"data": {
"otp": "917442",
"status": "pending",
"lifecycle": "OTP_RECEIVED",
"expiresAt": "2026-10-08T12:20:00+00:00",
"messages": [
{
"id": 12,
"code": "482193",
"text": "Your verification code is 482193",
"receivedAt": "2026-10-08T12:01:04+00:00"
},
{
"id": 15,
"code": "917442",
"text": "Your verification code is 917442",
"receivedAt": "2026-10-08T12:05:18+00:00"
}
]
},
"order": {
"order_id": "#24890552",
"status": "WAITING_FOR_SMS",
"phone_number": "+19703453333",
"otp": "917442",
"messages": [ /* same history */ ]
}
}
/api/v1/verifications/{id}/cancelCancels when platform rules allow (no OTP yet, cancel lock elapsed). Failures return RNVS_CANCEL_FAILED or RNVS_ORDER_ALREADY_COMPLETED.
/api/v1/verifications/{id}/reuseWhen the original offer supports reuse/reorder, creates a new verification. Otherwise returns RNVS_INVALID_REQUEST.
/api/v1/renewRenew an existing verification when the provider and order state allow it. Uses the same renewal service, pricing engine, and wallet hold/capture as the dashboard Renew button. Provider renewal success is confirmed before any balance charge.
Eligibility: Renew is available only when the order is renewable (for example NonVoIP reuse / HeroSMS reactivation windows). Grizzly and VerifySMS orders are not renewable via API. If renew is unavailable, the API returns RENEW_UNSUPPORTED or RENEW_FAILED and does not charge.
Headers
X-Api-Key: YOUR_API_KEY
Idempotency-Key: unique-renewal-request-id
Body
{
"order_id": "#24890552"
}
order_id is the dashboard order id returned by create, list, and get: #24890552 or 24890552. The numeric verificationId is also accepted. Do not send price, provider, or cost — the backend calculates sell price with the existing markup engine.
After the order is completed, data.renewable is true only for HeroSMS and NonVoIP orders that can be renewed. Grizzly and VerifySMS stay false. Call renew only when renewable is true.
cURL
curl -X POST https://realnonvoipusnumber.com/api/v1/renew \
-H "X-Api-Key: YOUR_API_KEY" \
-H "Idempotency-Key: renew-$(date +%s)-$RANDOM" \
-H "Content-Type: application/json" \
-d '{"order_id": "#24890552"}'
JavaScript
const res = await fetch("https://realnonvoipusnumber.com/api/v1/renew", {
method: "POST",
headers: {
"X-Api-Key": "YOUR_API_KEY",
"Idempotency-Key": crypto.randomUUID(),
"Content-Type": "application/json"
},
body: JSON.stringify({ order_id: "#24890552" })
});
const json = await res.json();
Python
import uuid, requests
r = requests.post(
"https://realnonvoipusnumber.com/api/v1/renew",
headers={
"X-Api-Key": "YOUR_API_KEY",
"Idempotency-Key": str(uuid.uuid4()),
},
json={"order_id": "#24890552"},
timeout=60,
)
print(r.json())
Success response
{
"success": true,
"brand": "RealNonVoIPUSNumber",
"request_id": "rnvs_req_…",
"data": { /* verification object */ },
"order": {
"order_id": "#248928997",
"status": "PENDING",
"phone_number": "+1…",
"otp": null
},
"meta": {
"renewed": true,
"renewal_price": "0.24",
"idempotent": false,
"expires_at": "2026-10-01T12:34:56+00:00"
}
}
Errors (use error.code)
RNVS_ORDER_NOT_FOUND— unknown id or not owned by the API key userRNVS_INSUFFICIENT_BALANCE(402) — provider is not called when balance is too lowRENEW_UNSUPPORTED— provider/order cannot be renewedRENEW_FAILED— provider unavailable or renew rejected; balance not chargedRNVS_INVALID_REQUEST— missing/invalidorder_id
Safe retries: send the same Idempotency-Key. A successful renew returns meta.idempotent: true without a second charge.
/api/v1/verifications/statisticsAggregated counts: total, completed, pending, cancelled, failed, expired.
Need a key? Open the API Dashboard. Explore interactively via Swagger.