Merchant API v1

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 }
}

Purchasable offers from synchronized inventory. Each item’s productServiceId (RNVS-P-…) is used to create a verification.

Query: service, country, page, limit, scope=all (full multi-country catalog), test

Default scope is USA-focused for payload size. Use scope=all for every synced service/country/server combination (paginated).

curl "https://realnonvoipusnumber.com/api/v1/catalog?service=whatsapp&country=187" \
  -H "X-Api-Key: YOUR_API_KEY"

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

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())

Poll status and OTP. When a code arrives, data.otp / data.messages and order.status=COMPLETED are populated.

{
  "success": true,
  "brand": "RealNonVoIPUSNumber",
  "order": {
    "order_id": "#24890552",
    "status": "COMPLETED",
    "phone_number": "+19703453333",
    "otp": "193680"
  }
}

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

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

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": 248928997
}

order_id is the numeric verification / order id returned by create/list/get (same integer as in the dashboard). Do not send price, provider, or cost — the backend calculates sell price with the existing markup engine.

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": 248928997}'

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: 248928997 })
});
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": 248928997},
    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

• VERIFICATION_NOT_FOUND — unknown id or not owned by the API key user
• 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
• INVALID_REQUEST — missing/invalid order_id

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

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