You need disposable virtual numbers to receive one-time SMS for sign-up flows, QA, or onboarding tests, and you need it working this week. By the end of this guide you’ll list supported countries, fetch available numbers for a country, and read SMS history for a specific number—using curl first, then a compact Node.js script you can drop into your service.
What the Virtual Phone Number Generator API does
The Virtual Phone Number Generator API provides:
- A list of currently available countries you can source virtual numbers from.
- Available phone numbers for a selected country code.
- SMS history for a given phone number and country code (so you can read received verification codes).
Typical uses include automated account testing, multi-region onboarding flows, or building internal tools to programmatically pick a number and read inbound SMS. You can access it with the single Zyla API Hub key you use across the marketplace.
Zyla API Hub aggregates more than 10,000 public APIs behind one account, one API key, and one subscription model. Explore the marketplace at zylalabs.com.
Getting started on Zyla API Hub
Open the Virtual Phone Number Generator API page on Zyla API Hub and click Subscribe. Zyla uses a subscription + quota model (not pay-per-call). For this API, the first subscription offers a 7‑day trial or 50 requests. There is no Free Plan. Check the API page for current access options and pricing.
After subscribing, you’ll get an API key. All requests use the Authorization header: Authorization: Bearer YOUR_API_KEY
If you don’t have an account yet, you can create one here: Register.
Endpoints you’ll use
All requests go to Zyla’s Hub URLs. Do not call origin vendor domains. Pass your key in the Authorization header.
1) Get Countries
Returns the list of currently available countries.
- Method: GET
- URL: https://zylalabs.com/api/1813/virtual-phone-number-generator-api/1466/get-countries
- Params: none documented
curl:
curl -s -X GET "https://zylalabs.com/api/1813/virtual-phone-number-generator-api/1466/get-countries" \
-H "Authorization: Bearer YOUR_API_KEY"Official sample response:
{
"status": 200,
"success": true,
"message": "",
"data": [
{
"countryCode": "1",
"countryName": "United States\n "
},
{
"countryCode": "1",
"countryName": "Canada\n "
},
{
"countryCode": "44",
"countryName": "United Kingdom\n "
},
{
"countryCode": "34",
"countryName": "Spain\n "
},
{
"countryCode": "972",
"countryName": "Israel\n "
},
{
"countryCode": "230",
"countryName": "Mauritius\n "
},
{
"countryCode": "91",
"countryName": "India\n "
},
{
"countryCode": "385",
"countryName": "Croatia\n "
},
{
"countryCode": "351",
"countryName": "Portugal\n "
},
{
"countryCode": "381",
"countryName": "Serbia\n "
},
{
"countryCode": "52",
"countryName": "Mexico\n "
},
{
"countryCode": "55",
"countryName": "Brazil\n "
},
{
"countryCode": "234",
"countryName": "Nigeria\n "
}
]
}What to read:
- status and success: basic request status.
- data: array of countries. Each item includes:
- countryCode: string international dialing prefix (for example, "44").
- countryName: string country name; note that it includes trailing whitespace/newlines—trim it in your code.
2) Get Number by Country Id
Returns the currently available numbers for a given country code. Numbers from this endpoint can be used with the Check SMS history endpoint.
- Method: GET
- URL: https://zylalabs.com/api/1813/virtual-phone-number-generator-api/1467/get-number-by-country-id
- Required query param:
- countryCode (string): e.g., 44
curl:
Example response:
What to read:
- data: array of phone numbers as strings. For Check SMS history, you may need to remove the country code prefix before sending the number (see the note under the SMS history endpoint).
3) Check SMS history
Returns SMS messages received by the specified phone number and country code.
- Method: GET
- URL: https://zylalabs.com/api/1813/virtual-phone-number-generator-api/1469/check-sms-history
- Required query params:
- countryCode (string): e.g., 1
- phoneNumber (string): e.g., 8578329806
Important note from the API: If you use a phone number returned by Get Number by Country ID, remove the country code before passing it here. For most countries, remove the first 2 digits from the full number. Always ensure you pass just the local number part along with the correct countryCode.
curl:
The endpoint returns the SMS history for that number. The exact response fields are not documented here; log the raw JSON and parse the message content and timestamps as needed for your workflow.
Node.js quickstart (fetch + minimal parsing)
The following Node.js example walks through the usual flow: list countries, choose a country code, fetch available numbers, normalize the number for SMS history, then fetch the inbox. It uses the exact endpoints and headers described above.
/**
* Node.js 18+ (global fetch). Set YOUR_API_KEY via env or replace inline.
* This script:
* 1) Lists countries
* 2) Fetches numbers for a selected country code
* 3) Normalizes the number for SMS history
* 4) Fetches SMS history JSON and prints it
*/
const API_KEY = process.env.ZYLA_API_KEY || 'YOUR_API_KEY';
const BASE = 'https://zylalabs.com/api/1813/virtual-phone-number-generator-api';
async function getCountries() {
const res = await fetch(`${BASE}/1466/get-countries`, {
headers: { Authorization: `Bearer ${API_KEY}` }
});
if (!res.ok) throw new Error(`get-countries failed: ${res.status}`);
const json = await res.json();
return json;
}
async function getNumbersByCountryCode(countryCode) {
const url = `${BASE}/1467/get-number-by-country-id?countryCode=${encodeURIComponent(countryCode)}`;
const res = await fetch(url, { headers: { Authorization: `Bearer ${API_KEY}` } });
if (!res.ok) throw new Error(`get-number-by-country-id failed: ${res.status}`);
const json = await res.json();
return json;
}
async function checkSmsHistory(countryCode, phoneNumber) {
const url = `${BASE}/1469/check-sms-history?countryCode=${encodeURIComponent(countryCode)}&phoneNumber=${encodeURIComponent(phoneNumber)}`;
const res = await fetch(url, { headers: { Authorization: `Bearer ${API_KEY}` } });
if (!res.ok) throw new Error(`check-sms-history failed: ${res.status}`);
const json = await res.json();
return json;
}
// Remove country code prefix from a full E.164-like string when required.
// The API notes: For most countries, remove the first 2 digits.
// Behavior can vary; double-check your target country.
function stripCountryCode(fullNumber, countryCode) {
const cc = String(countryCode);
return fullNumber.startsWith(cc) ? fullNumber.slice(cc.length) : fullNumber;
}
function trimCountryName(name) {
return String(name).trim();
}
(async () => {
// 1) Countries
const countries = await getCountries();
console.log('Countries raw:', countries);
// Choose a country code (example: use United Kingdom "44" if available)
const uk = (countries.data || []).find(c => trimCountryName(c.countryName) === 'United Kingdom');
const countryCode = uk ? uk.countryCode : '44';
console.log('Using countryCode:', countryCode);
// 2) Numbers for that country
const numbers = await getNumbersByCountryCode(countryCode);
console.log('Numbers raw:', numbers);
if (!numbers.data || numbers.data.length === 0) {
console.log('No numbers available for countryCode', countryCode);
return;
}
const fullNumber = numbers.data[0];
// 3) Normalize for SMS history as per API guidance
const localNumber = stripCountryCode(fullNumber, countryCode);
console.log('Full number:', fullNumber, 'Local for history:', localNumber);
// 4) SMS history
const inbox = await checkSmsHistory(countryCode, localNumber);
console.log('SMS history raw:', inbox);
// Because the response shape is not documented here,
// process the payload based on your observed structure.
})();First calls with curl
Developers often start with curl to validate auth and response shapes. These three commands cover the common path.
- List countries:
- Get UK numbers (countryCode=44): Expected shape:
- Check SMS history (example with US code 1 and local number 8578329806):
Practical integration notes
- Auth header: Always send Authorization: Bearer YOUR_API_KEY. Do not send keys as query params.
- Country names: countryName values may include trailing whitespace or newline characters. Trim before comparing or displaying.
- Number normalization: When you get a number from Get Number by Country ID, remove the country code before calling Check SMS history. For most countries, remove the first 2 digits. Validate with test requests for your target region.
- Caching: The list of countries typically changes less frequently than inbox data. Cache Get Countries for minutes to hours depending on your use case and quota strategy.
- Quotas: Zyla APIs run on a subscription + quota model. For this API, the first subscription includes a 7‑day trial or 50 requests. Monitor usage in your Zyla dashboard.
- Error handling: Check HTTP status codes and the JSON status/success fields. Log raw responses during development to understand any validation errors.
- Environments: Use separate keys for development and production projects to isolate quotas and logs.
Common workflows
Automated test account creation
- Call Get Countries and select the country where your product’s onboarding must be tested.
- Fetch a number with Get Number by Country Id.
- Trigger your target app to send an SMS to that number.
- Call Check SMS history with countryCode + local number to read the verification code.
Multi-region onboarding
- Preload an allowlist of country codes from Get Countries.
- For each region, rotate through available numbers from Get Number by Country Id.
- Fetch and parse SMS content via Check SMS history to unblock cross-border flows.
Internal tooling
- Build a small dashboard that wraps the three endpoints with your team’s SSO.
- Show per-country availability from Get Countries and Get Number by Country Id.
- Provide a “read latest SMS” button per number using Check SMS history.
Call this API from an AI agent via MCP
You can also access this API from MCP-compatible tools (Claude Code, Cursor, Windsurf, etc.). Point your agent to the MCP gateway:
Endpoint: https://mcp.zylalabs.com/mcp?apikey=YOUR_API_KEY
Once configured, instruct the agent to perform the same sequence you used above: list countries, choose a countryCode, fetch numbers, strip the country code from the chosen number, then call the SMS history endpoint with the local number. For background on MCP access, see the MCP page.
Where to explore and next steps
Start from the API listing and test the curl samples right on the Hub console: Virtual Phone Number Generator API. Browse other categories on zylalabs.com—there are more than 10,000 public APIs under one account and one API key.
FAQ
How do I authenticate requests?
Send an HTTP header: Authorization: Bearer YOUR_API_KEY on every request to the Zyla Hub URLs.
Which country code should I pass to Get Number by Country Id?
Use the countryCode value returned by Get Countries (e.g., "44" for United Kingdom). It’s a string; keep it as-is in your query param.
Why does Check SMS history not work with the full number from Get Number by Country Id?
Per the API note, remove the country code when passing phoneNumber to Check SMS history. For most countries, that means dropping the first two digits. Keep countryCode as the separate query param.
Is there a free plan?
No Free Plan. The first subscription offers a 7‑day trial or 50 requests. Check the API page for current access options and pricing.
Can I call these APIs from an AI coding assistant?
Yes. Use the MCP endpoint at https://mcp.zylalabs.com/mcp?apikey=YOUR_API_KEY in an MCP-compatible client and issue the same endpoint calls via the agent.
Ready to ship your integration? Create your account, subscribe, and get your key now: Register. Then open the Virtual Phone Number Generator API to make your first request.
