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.

Base URL 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

  1. Create an API key in the dashboard and copy it once.
  2. GET /balance to confirm authentication.
  3. GET /services for every service on the user dashboard.
  4. GET /countries?service=wa for every country of that service.
  5. GET /servers?service=wa&country=187 for every server (same list as the dashboard).
  6. POST /verifications with that id and an Idempotency-Key.
  7. GET /verifications/{id} until messages contains 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_DISABLED
  • RNVS_INSUFFICIENT_BALANCE
  • RNVS_INVALID_SERVICE, RNVS_SERVER_NOT_AVAILABLE, RNVS_NUMBER_NOT_AVAILABLE
  • RNVS_PROVIDER_UNAVAILABLE, RNVS_PROVIDER_TIMEOUT, RNVS_PROVIDER_ERROR
  • RNVS_ORDER_NOT_FOUND, RNVS_CANCEL_FAILED, RNVS_ORDER_ALREADY_COMPLETED
  • RNVS_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 secret
  • X-Webhook-Delivery — unique delivery id
  • X-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.

GET/api/v1/balance

Returns 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 }
}
GET/api/v1/services

Every 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"
GET/api/v1/countries

Every 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"
GET/api/v1/servers

Every 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"
GET/api/v1/catalog

Purchasable 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).
  • service only — every server in every country for that service. Read meta.total and follow page until you have them all.
  • No filters, or scope=all — every Grizzly and HeroSMS server for every service and country, paginated (page, limit up 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
}
GET/api/v1/verifications

Paginated history for the authenticated account. Query: page, limit, status, from, to.

POST/api/v1/verifications

Create 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())
POST/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"}
    ]
  }
}
GET/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.

GET/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 */ ]
  }
}
PATCH/api/v1/verifications/{id}/cancel

Cancels when platform rules allow (no OTP yet, cancel lock elapsed). Failures return RNVS_CANCEL_FAILED or RNVS_ORDER_ALREADY_COMPLETED.

PATCH/api/v1/verifications/{id}/reuse

When the original offer supports reuse/reorder, creates a new verification. Otherwise returns RNVS_INVALID_REQUEST.

POST/api/v1/renew

Renew 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 user
  • RNVS_INSUFFICIENT_BALANCE (402) — provider is not called when balance is too low
  • RENEW_UNSUPPORTED — provider/order cannot be renewed
  • RENEW_FAILED — provider unavailable or renew rejected; balance not charged
  • RNVS_INVALID_REQUEST — missing/invalid order_id

Safe retries: send the same Idempotency-Key. A successful renew returns meta.idempotent: true without a second charge.

GET/api/v1/verifications/statistics

Aggregated counts: total, completed, pending, cancelled, failed, expired.

Need a key? Open the API Dashboard. Explore interactively via Swagger.