iSMScode API Documentation

Simple & Fast Virtual Numbers for SMS Verification.

Welcome to the iSMScode API. Our API is intentionally designed to be extremely simple, allowing you to integrate virtual numbers and receive SMS verifications in minutes. You only need to know 3 main endpoints to get a number and read its messages.

The base URL for all API requests is:

https://ismscode.com/api/v3

Authentication

All requests to the iSMScode API require an API key. You can get your API key from your dashboard, Key will be available after the first balance top up.

We support two methods of passing your API key in the headers. You can use either one:

Option 1: Bearer Token

Authorization: Bearer YOUR_API_KEY

Option 2: Custom Header

API-Key: YOUR_API_KEY

Keep your API key secure! Do not expose it in client-side code (like frontend JavaScript). Always make requests from your secure backend server.

Quick Start (60 Seconds)

Here is a quick example of how to request a phone number and check for SMS messages.

1. Request a US number for WhatsApp

curl -X POST https://ismscode.com/api/v3/numbers/request \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"country": "US", "service": "whatsapp"}'

2. Check for SMS messages (using the returned number id)

curl -X GET https://ismscode.com/api/v3/numbers/num_abc123xyz/sms \
  -H "Authorization: Bearer YOUR_API_KEY"

1. Request a number & check for SMS

const API_KEY = 'YOUR_API_KEY';
const BASE_URL = 'https://ismscode.com/api/v3';

async function getWhatsAppCode() {
  // 1. Request a number
  const reqRes = await fetch(`${BASE_URL}/numbers/request`, {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${API_KEY}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({ country: 'US', service: 'whatsapp' })
  });
  
  const reqData = await reqRes.json();
  if (reqData.status !== 'success') throw new Error(reqData.message);
  
  const numberId = reqData.number.id;
  console.log(`Got number: ${reqData.number.phone}`);

  // 2. Wait and check for SMS
  setTimeout(async () => {
    const smsRes = await fetch(`${BASE_URL}/numbers/${numberId}/sms`, {
      headers: { 'Authorization': `Bearer ${API_KEY}` }
    });
    const smsData = await smsRes.json();
    console.log(smsData.sms);
  }, 15000); // Check after 15 seconds
}

Endpoints

GET /countries

Returns a list of all supported countries available for renting numbers.

Response Example

{
  "status": "success",
  "countries": [
    {"code": "US", "name": "United States", "prefix": "+1"},
    {"code": "GB", "name": "United Kingdom", "prefix": "+44"},
    {"code": "CA", "name": "Canada", "prefix": "+1"}
  ]
}

GET /services

Returns a list of all supported service slugs that you can request numbers for.

Response Example

{
  "status": "success",
  "services": [
    "whatsapp", 
    "telegram", 
    "google", 
    "facebook", 
    "instagram", 
    "twitter", 
    "amazon"
  ]
}

POST /numbers/request

Requests a new virtual phone number for a specific country and service. This will reserve the number for your account for a limited time (typically 15-20 minutes).

Request Body (JSON)

Parameter	Type	Description
country	string	2-letter ISO country code (e.g., `"US"`, `"GB"`).
service	string	Lowercase service slug (e.g., `"whatsapp"`).

Success Response

{
  "status": "success",
  "number": {
    "id": "num_abc123xyz",
    "phone": "+12025550123",
    "country": "US",
    "service": "whatsapp",
    "expires_at": "2026-03-21T20:15:00Z"
  }
}

Error Response

{
  "status": "error",
  "code": "insufficient_balance",
  "message": "Not enough balance to request this number."
}

GET /numbers/:number_id/sms

Retrieves all SMS messages received by the specified number. You should poll this endpoint (e.g., every 5-10 seconds) until the SMS arrives.

Path Parameters

number_id: The unique ID returned from the number request endpoint (e.g., num_abc123xyz).

Response Example

{
  "status": "success",
  "sms": [
    {
      "from": "+447123456789",
      "text": "Your WhatsApp code: 583920",
      "received_at": "2026-03-21T19:58:42Z"
    }
  ]
}

Error Codes

The API uses standard HTTP status codes to indicate the success or failure of an API request. The response body will contain an error object with details.

Status Code	String Code	Description
400 Bad Request	invalid_service / invalid_country	The provided parameters are missing or invalid. Check the `message` field for details.
401 Unauthorized	unauthorized	No valid API key provided. Check your Authorization header.
402 Payment Required	insufficient_balance	Your account balance is too low to complete this request.
404 Not Found	no_numbers_available	Currently out of stock for the requested country/service combination. Try again later.
429 Too Many Requests	rate_limit_exceeded	You have exceeded the rate limits.

Rate Limits

To ensure system stability, we enforce rate limiting on all API endpoints. The standard rate limit is:

60 requests per minute per API key

If you exceed this limit, you will receive a 429 Too Many Requests response. When polling for SMS (GET /numbers/:number_id/sms), we recommend polling no more than once every 5 seconds.