Virtual Number API: Receive SMS Verification Codes via Temporary Numbers

What the Virtual Number API does and who it is for

The Virtual Number API solves a specific, narrow problem: getting an SMS verification code to a phone number you control programmatically, without owning a SIM card. Developers building automation tools, testing harnesses, or user-facing apps that guide people through account registrations on third-party platforms will find the surface area here deliberately small — three distinct endpoints, all read-only GET requests, no webhooks or write operations.

The API is listed as freemium, has attracted over 4,000 marketplace subscribers, and carries a popularity score of 9.9 out of 10, which suggests strong real-world adoption relative to its peer APIs. Average latency sits at 311 ms and the reported success rate is 99%, so response reliability is solid for a polling-based workflow.

One architectural fact shapes every decision around this API: the phone numbers it exposes are public. Any caller with an API key can read every SMS sent to any number the service provides. This is not a bug — it is the design. The numbers are shared infrastructure, not private allocations. That distinction matters enormously for what use cases are appropriate.

Endpoint walkthrough

The three functional endpoints form a linear workflow.

1. List available countries — GET /api/v1/e-sim/all-countries

Returns an array of country objects, each with a countryCode (used as the countryId parameter downstream) and a human-readable countryName. This is the starting point for every session. Because the set of supported countries can change, callers should not hardcode country codes; retrieve them fresh from this endpoint.

2. Get numbers for a country — GET /api/v1/e-sim/country-numbers?countryId={code}

Passes the countryCode from the previous step as the required countryId query parameter. The response is a plain array of phone number strings (e.g., ["+1234567890", "+1234567891"]). Your application picks one of these numbers to hand to a registration form on the target platform.

3. Read incoming SMS — GET /api/v1/e-sim/view-messages?countryId={code}&number={number}&page={n}

The core retrieval endpoint. Pass the same countryId and the specific number selected in step 2. Each message in the response includes:

• text — the raw SMS body (containing the OTP or verification code)
• serviceName — the platform that sent the message
• myNumber — the recipient number
• createdAt — how long ago the message arrived

The optional page parameter lets you page back through older messages, which is useful if a code was sent a few minutes before you poll. In practice, polling promptly after triggering the SMS is important because numbers rotate and old messages may not persist indefinitely.

The API uses standard HTTP status codes: 400 for malformed requests, 401 for a missing or invalid API key, 404 when a number or message is not found, and 500 for server-side faults.

Pricing breakdown

The BASIC tier's five requests per month is essentially an evaluation quota — enough to confirm that the endpoints respond and that you can parse the JSON, but not enough to support any real application usage. A single complete verification flow (list countries → get numbers → poll for message) can consume three requests by itself, leaving almost no room for retries or repeated sessions.

The PRO plan at $0.99/month opens up 50,000 monthly requests, which is sufficient for moderate automation workloads or a small-to-medium production feature. At a 1 request/second rate limit, you can comfortably run polling loops with a reasonable delay between checks.

ULTRA at $3.99/month quintuples the quota to 250,000 requests — appropriate if you are running many concurrent verification sessions or operating at higher user volumes. The per-request cost at ULTRA works out to a fraction of a cent, making it economical for high-throughput scenarios.

Practical use cases

• Automated account registration testing: QA pipelines that must create fresh accounts on platforms requiring phone verification can use the API to receive OTP codes without managing a pool of real SIM cards.
• User-facing verification helpers: An app that guides users through setting up accounts on third-party services can present a temporary number, trigger the SMS on the user's behalf, and auto-fill the retrieved code.
• Research and scraping workflows: Projects that need to register multiple accounts on platforms that gatekeep behind SMS can programmatically cycle through available numbers.

Limitations and things to check before integrating

Public number pool: Every number is shared. If two users pick the same number at the same time, both will see each other's incoming messages. Applications must not use these numbers for anything sensitive, and should never store or relay the received OTP in a context where secrecy matters.

Number rotation: Numbers are periodically replaced. There is no guarantee a number available today will exist tomorrow. Your integration should treat numbers as ephemeral and always fetch a fresh list rather than caching them.

Polling model only: The API has no webhook or push mechanism. You must poll the view-messages endpoint after triggering the SMS, which means building a loop with appropriate delays. At a 1 request/second rate limit on paid plans, tight polling is feasible but needs to stay within the constraint.

Country availability is dynamic: The list of countries and numbers reflects what is currently provisioned. If you need coverage in a specific country, verify its presence via the all-countries endpoint before committing to the integration.

Platform compatibility: Some services (banks, government portals) detect and reject numbers from virtual or shared pools. The API is best suited for consumer platforms like social networks and messaging apps that accept a broad range of numbers.

Getting started

Access requires an API key, which authenticates requests (a 401 is returned without it). The recommended integration path mirrors the documented workflow:

1. Call /api/v1/e-sim/all-countries and present or select a country.
2. Call /api/v1/e-sim/country-numbers?countryId={code} and pick an available number.
3. Submit that number to the target platform's registration form.
4. Begin polling /api/v1/e-sim/view-messages with the chosen number until the OTP message appears in the response.
5. Extract the code from the text field and use it for verification.

Given the 5-request BASIC cap, testing the full flow end-to-end should be done thoughtfully. Upgrading to PRO at $0.99/month removes the quota constraint for all practical development and light production use.