For developers
Virtual number API: provision numbers from your own code
A REST API over the same real-carrier numbers sold on the site — permanent and OTP alike. Buy, renew, and read SMS programmatically, wallet-funded and idempotent.
How it's built
Bearer key auth
One API key per account, sent as an Authorization: Bearer header or X-API-Key.
Wallet-funded
Every call spends from a balance you top up in crypto — no separate API billing.
Idempotent by key
Purchases and renewals accept an Idempotency-Key header so a retried request never double-charges.
Signed webhooks
Register a URL and get real-time, signed events instead of polling.
Rate-limited
Every response carries rate-limit headers so you can back off cleanly.
Renew and auto-renew
Renew a number manually or flip on auto-renew from your balance.
Endpoints
| Method | Path | What it does |
|---|---|---|
| GET | /api/v1/balance | Read your current wallet balance |
| GET | /api/v1/catalog | List countries, plans and your resale price for each |
| POST | /api/v1/numbers | Buy a number for a country and plan, charged from your balance |
| GET | /api/v1/numbers | List the numbers on your account, with status and expiry |
| GET | /api/v1/numbers/{id} | Get one number's details and status |
| GET | /api/v1/numbers/{id}/sms | List messages received on a number |
| POST | /api/v1/numbers/{id}/renew | Renew a number for another plan period |
| POST | /api/v1/numbers/{id}/autorenew | Turn auto-renew on or off for a number |
| GET / PUT | /api/v1/webhook | Read or set your webhook URL for real-time events |
| GET | /api/v1/otp-catalog | List OTP services, countries and your resale price for each |
| POST | /api/v1/otp-numbers | Buy a single-use OTP number, charged from your balance |
| GET | /api/v1/otp-numbers | List your OTP activations, with status |
| GET | /api/v1/otp-numbers/{id} | Get one activation's live status and SMS code |
| POST | /api/v1/otp-numbers/{id}/resend | Request an SMS resend, where the upstream route supports it |
| POST | /api/v1/otp-numbers/{id}/cancel | Cancel a waiting activation for a full refund |
Full request and response fields, headers and error codes are in your dashboard's developer section once you have a key.
Quick example
curl https://vnumbr.com/api/v1/numbers \
-X POST \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Idempotency-Key: order-8f21" \
-H "Content-Type: application/json" \
-d '{"countryCode":"US","subscriptionOption":"month"}'API questions
How do I get an API key?
Create a free account, open the developer section of your dashboard, and generate a key. There is no approval wait and no monthly fee — you pay only from your wallet balance when you buy or renew a number.
How does authentication work?
Send your key as an Authorization: Bearer header, or as an X-API-Key header, on every request.
What happens if a request times out and I retry it?
Purchase and renewal endpoints accept an Idempotency-Key header. Retry the same request with the same key and you get back the original result instead of a duplicate charge.
How do I find out when a number is ready or a message arrives?
Set a webhook URL with PUT /api/v1/webhook. We POST signed JSON events to it (for example number.provisioned and sms.received) with a signature header you can verify.
What are the rate limits?
Each response includes rate-limit headers so you can see your remaining quota and back off cleanly if you are close to the limit.
Can I resell numbers under my own brand?
Yes. The catalog endpoint returns your own resale price only — your customers never see the underlying cost.
Does the API cover OTP numbers too?
Yes. Alongside the permanent-number endpoints, a parallel set of otp-numbers endpoints lets you buy, check, resend and cancel single-use OTP activations the same way.
Where do I get help with the API?
Use the Support page in your dashboard, or email [email protected].
Ready to integrate?
Create a free account and generate a key in minutes.