Getting Started with the VerifyNumber API
Use the VerifyNumber rentals API to choose a duration, check wallet balance and read SMS. Includes current endpoints, scopes, curl and Node.js examples.
The VerifyNumber API rents a phone number for a chosen period, then exposes messages received during that rental. The current base URL is https://app.verifynumber.io/api/v1. Create rentals with POST /rentals; the current product no longer requires choosing a platform-specific service.
This guide follows the API Documentation in the VerifyNumber app, reviewed on October 23, 2026. Examples below were checked against that documentation, not executed against a paid account.
TL;DR
- Use a server-side bearer API key with only the scopes your integration needs.
- Review your wallet and the live rental price before making a paid request.
- Send
period: "TEN_MINUTES"orperiod: "ONE_MONTH"to/rentals; do not select a destination service.- Read the returned rental ID and expiry, then request that rental’s messages. Keep secrets and verification codes out of logs.
Why Start With the Rental Lifecycle?
An integration needs to track more than the first code. It must know which number belongs to a rental, when access ends, whether a request succeeded, and how to handle a message that has not arrived. Treating the API as a time-bound resource avoids confusing a paid number reservation with guaranteed platform verification.
A number can receive messages from different apps while active. Each destination still controls its own eligibility and sending behavior. For the receiving-side distinction, read our SMS troubleshooting guide.
Step 1: Access Your Account and Prepare a Scoped Key
Sign in to VerifyNumber, open API & Webhooks, and consult Documentation before creating or changing credentials. Store any key in a server-side secret manager or environment variable, never in browser code, a public repository or a screenshot.
The documented scopes needed here are NUMBERS_CREATE for rentals, RENTALS_READ for rentals and messages, and WALLET_READ for balance. Do not add webhook-management permissions unless your integration needs them. The docs state that newly created keys are shown once; follow your team’s secure credential-handling process.
Step 2: Check Your Wallet Before a Paid Request
Rentals debit the wallet at creation. In the app, Top up wallet is the funding entry point. Review the actual amount and terms before adding funds.

Current app header, captured October 23, 2026. No payment or account balance is shown.
With a key that has WALLET_READ, the documented read-only request is:
curl --fail-with-body https://app.verifynumber.io/api/v1/wallet \
-H "Authorization: Bearer $VERIFYNUMBER_API_KEY"
The documented response includes balance and currency. Review current pricing in the app or the documented GET /services response. That endpoint currently represents a single OTP service; it is not a platform catalog. Its quoted price is for the short rental, so do not assume it prices every period.
Step 3: Create a Rental for the Required Period
The app’s New Verification screen reflects the same choice: a 10-minute or one-month rental, with no platform picker.

Actual rental selector, October 23, 2026. Displayed prices are dated examples. The API request below creates a paid rental; this guide did not execute it.
This request charges the wallet and assigns a number. Run it only when ready to use the rental:
curl --fail-with-body -X POST https://app.verifynumber.io/api/v1/rentals \
-H "Authorization: Bearer $VERIFYNUMBER_API_KEY" \
-H "Content-Type: application/json" \
-d '{"period":"TEN_MINUTES"}'
The documented period values are TEN_MINUTES and ONE_MONTH; omitting it defaults to TEN_MINUTES. Older integrations may send serviceSlug, but the current reference says it is ignored. New code should express the intended duration directly.
On creation, retain the returned id, phoneNumber, status and expiresAt. Do not treat documentation example IDs or numbers as usable credentials. After an ambiguous timeout, inspect your recent rentals before issuing another paid creation request; the reference does not establish an idempotency-key contract for this endpoint.
Step 4: Read Messages for That Rental
Use the ID returned by creation. The following Node.js example makes one read request; it does not rent another number or run an unbounded polling loop:
const apiKey = process.env.VERIFYNUMBER_API_KEY;
const rentalId = process.env.VERIFYNUMBER_RENTAL_ID;
if (!apiKey || !rentalId) throw new Error("Missing server-side configuration");
const response = await fetch(
`https://app.verifynumber.io/api/v1/rentals/${encodeURIComponent(rentalId)}/messages`,
{
headers: { Authorization: `Bearer ${apiKey}` },
signal: AbortSignal.timeout(10000),
}
);
if (!response.ok) throw new Error(`Message request failed: ${response.status}`);
const payload = await response.json();
if (!Array.isArray(payload.data)) throw new Error("Unexpected messages response");
const messages = payload.data;
// Process the relevant message securely. Never log message bodies or codes.
The documented list response uses data, with message fields including id, sender, body and receivedAt. It does not document a separate messages[0].code property. Match messages to your intended flow; do not assume the first message belongs to the app currently being verified.
Access to earlier messages and the ability to receive new ones are different. The reference describes a limited post-rental message-access window and a 410 response after that window ends. Inspect smsAccessExpiresAt when available and consult current documentation rather than assuming indefinite retention.
Step 5: Handle Errors and Optional Webhooks
| Response | What to review |
|---|---|
| 400 | Request JSON and required values |
| 401 / 403 | Key validity and required permission scope |
| 402 | Wallet balance before another paid request |
| 404 | Rental ID and endpoint path |
| 410 | Expired message access |
| 422 | Availability or another stated business-rule failure |
| 429 / transient server failure | Bounded backoff; reconcile paid mutations before repeating them |
The reference also documents paid extensions for active rentals. Review the charge and eligibility before using one; an extension should not be assumed to reclaim an already expired number.
For webhooks, follow the current reference’s event and signature sections. Verify the signature against the raw request bytes, check timestamp freshness, and deduplicate by delivery ID before acting. Keep the signing secret server-side. This quickstart does not create a webhook or publish an endpoint on your behalf.
Manual Access Compared With API Automation
| Route | When it fits | Responsibility |
|---|---|---|
| App interface | Reviewing a rental and its messages manually | Check the live duration, cost and status |
| API integration | Your software needs rental and message access | Secure keys, handle errors, track expiry and avoid duplicate charges |
| Public SMS inbox | Shared messages visible to visitors | Unsuitable for private verification codes or controlled integration access |
Neither an API response nor an eSIM label guarantees destination acceptance. Our eSIM versus VoIP guide explains the separate questions of number capability and platform eligibility.
What VerifyNumber Makes Available to Your Integration
A duration-based rental resource. Track the number and expiry without a platform-specific order.
Scoped access. Request only the permissions required for the operations your server performs.
Messages and event options. Choose a bounded read workflow or implement verified webhooks using the current documentation, with secure handling of message content.
Wrapping Up
Start with the current rental contract, secure credentials, and read-only wallet checks. Create a paid rental only when the integration is ready, then track its status and messages without assuming permanent access or universal acceptance.
Build from the current reference: Open VerifyNumber API Documentation and review the required scopes, live pricing and response fields before connecting production code.
Need more help? Visit VerifyNumber Support or email support@verifynumber.io. If something goes wrong with your rental, our team will review the issue and help you work through the next steps. Share the rental ID and relevant error, never your password or verification code.