Guide

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 Team · Updated • 7 min read
Share mail
Getting Started with the VerifyNumber API

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" or period: "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.

VerifyNumber account header with the Top up wallet control.

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.

VerifyNumber duration selector showing 10 minutes, 1 month and Get Number.

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

ResponseWhat to review
400Request JSON and required values
401 / 403Key validity and required permission scope
402Wallet balance before another paid request
404Rental ID and endpoint path
410Expired message access
422Availability or another stated business-rule failure
429 / transient server failureBounded 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

RouteWhen it fitsResponsibility
App interfaceReviewing a rental and its messages manuallyCheck the live duration, cost and status
API integrationYour software needs rental and message accessSecure keys, handle errors, track expiry and avoid duplicate charges
Public SMS inboxShared messages visible to visitorsUnsuitable 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.

Share mail

Keep reading.

More from the same world.

Test your first number today.

Get a test number for $1, call it from any line and read the quality report the moment the call ends. Numbers for SMS verification are in the same account.

Keep your personal number separate. Plan how you will recover your account later.