Virtual Number API
for Resellers
Provision dedicated monthly and yearly virtual phone numbers programmatically, set your own resale price, and build your own SMS-verification brand — without owning a single SIM.
Why build on the VRNUM API instead of your own carrier deals
Sourcing real mobile carrier numbers directly means SIM contracts, hardware, compliance overhead, and months of lead time before you can sell a single verification. The VRNUM API skips all of that.
You get instant access to a live inventory of monthly and yearly virtual numbers across 50+ countries, with your own margin baked into every price the API returns. Your customers only ever see your brand and your price.
From API key to your first sale
Four steps to a working reseller integration.
Generate an API key
Create a free VRNUM account and generate a key from the Developers tab. One active key per account.
Fund your wallet
Top up with crypto. Every order is deducted from your balance — no invoices, no manual billing.
Read the catalog
Call GET /catalog for live countries, subscription terms, and prices. Add your markup before you display them.
Provision on demand
POST /numbers with an Idempotency-Key to assign a number instantly, then poll or use webhooks for delivery.
Provision a number in one request
clientReference is your own opaque ID — attach it to reconcile orders against your internal customer records.
curl -X POST https://vrnum.com/api/v1/numbers \
-H "Authorization: Bearer vrnum_live_..." \
-H "Content-Type: application/json" \
-H "Idempotency-Key: order-8841" \
-d '{
"route": "<from catalog>",
"countryCode": "US",
"subscriptionOption": "month",
"clientReference": "order-8841"
}'Everything you need to run the full order lifecycle
Catalog, provisioning, SMS retrieval, renewal, auto-renew, and webhooks — one consistent JSON API.
/api/v1/catalog/api/v1/numbers/api/v1/numbers/api/v1/numbers/:id/api/v1/numbers/:id/sms/api/v1/numbers/:id/renew/api/v1/numbers/:id/autorenew/api/v1/webhook/api/v1/balanceFull request/response docs and your keys live in your dashboard after you sign in.
Who builds on the virtual number API
Any business that needs a supply of real phone numbers without owning telecom infrastructure.
Telecom resellers
Launch your own numbers-as-a-service brand on top of live carrier inventory without a single SIM contract.
SaaS & app founders
Add phone-number provisioning to your product's onboarding or verification flow with a few API calls.
Dev agencies
Ship number-provisioning features for client apps without negotiating your own carrier agreements.
QA & automation teams
Provision disposable-but-real numbers on demand for automated registration and verification test suites.
Built for production, not a demo
Idempotency keys
Retry safely on timeouts — the same Idempotency-Key always returns the original order, never a duplicate.
Signed webhooks
number.provisioned, number.provisioning_failed, and sms.received events, signed with X-VRNUM-Signature (HMAC-SHA256).
Automatic retries
Failed webhook deliveries retry on a backoff schedule (5min, 30min, 2h, 6h, 24h) before we give up.
Transparent rate limits
60 requests/minute per key with X-RateLimit-* headers on every response, so you can back off predictably.
Wallet-funded billing
No invoices or subscriptions for API access — orders deduct from your balance the instant they succeed.
Stable error codes
Every error returns a normalized JSON code your integration can switch on reliably, not just an HTTP status.
Frequently asked questions
Can I resell VRNUM virtual numbers under my own brand?
Yes. The API returns your resale price only — your customers never see VRNUM's internal cost or the underlying carrier source. You set your own markup per country and service.
How do I get access to the virtual number API?
Create a free VRNUM account, open the Developers tab, and generate an API key. No approval wait, no monthly API fee — you only pay from your wallet balance when you provision a number.
What authentication does the API use?
Bearer token authentication. Send your API key as an Authorization: Bearer header or an X-API-Key header on every request.
Are duplicate orders a risk if a request times out?
No. Every purchase endpoint accepts an Idempotency-Key header — retry the same request with the same key and you get back the original order instead of a duplicate charge.
How do I get notified when a number is ready or SMS arrives?
Register a webhook URL from the Developers tab. VRNUM POSTs signed events (number.provisioned, number.provisioning_failed, sms.received) to your endpoint, retrying failed deliveries automatically.
What are the API rate limits?
60 requests per key per minute. Every response includes X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset headers so you can back off cleanly.
Start reselling virtual numbers today
Create a free account, generate your API key, and provision your first virtual number in minutes.