SMS Villa API Documentation

Back

Getting Started

Welcome to the SMS Verification API. This REST API allows you to programmatically rent phone numbers and receive OTP codes in real-time for verification purposes.

Base URL

https://smsvilla.com/api/v1

✨ Features

  • • Real-time OTP delivery
  • • Webhook notifications
  • • Multiple carriers supported
  • • 99.9% uptime SLA

📊 Rate Limits

  • • 100 requests/minute
  • • 5000 requests/day
  • • Webhooks unlimited

Authentication

All API requests require authentication using Bearer tokens. Include your API key in the Authorization header. 

Authorization: Bearer YOUR_API_KEY

⚠️ Security: Never expose your API key in client-side code. Keep it secure on your backend.

API Endpoints Overview

Account Management

GET /balance
View →

Service Information

GET /services
View →

Number Rentals

POST /rent
View →
GET /status
View →
GET /get-sms
View →
POST /cancel
View →
GET

Get Account Balance

Retrieve your current account balance and credit information.

Endpoint

GET /api/v1/balance

Success Response (200 OK)

{
  "status": "success",
  "balance": 2919.2,
  "currency": "NGN"
}

cURL Example

curl -X GET https://smsvilla.com/api/v1/balance \
  -H "Authorization: Bearer YOUR_API_KEY"
GET

List Available Services

Get a list of all available services and their current pricing information.

Endpoint

GET /api/v1/services

Success Response (200 OK)

{
  "status": "success",
  "services": [
    {
      "code": "gmail",
      "name": "Gmail",
      "price": 600,
      "ttl": 420,
      "count": 100
    },
    {
      "code": "whatsapp",
      "name": "WhatsApp",
      "price": 500,
      "ttl": 420,
      "count": 100
    },
    {
      "code": "telegram",
      "name": "Telegram",
      "price": 800,
      "ttl": 600,
      "count": 100,
    }
  ]
}

cURL Example

curl -X GET https://smsvilla.com/api/v1/services \
  -H "Authorization: Bearer YOUR_API_KEY"
POST

Rent a Number

Request a new phone number for SMS verification. The number will be reserved for your use until the OTP is received or the rental expires.

Request Body

{
  "service_code": "gmail",
  "area_code": "234",
  "carrier": "vz",
  "phone_number": null
}

Parameters

Field Type Required
service_code string Yes
area_code string No
carrier string No
phone_number string No

Scroll horizontally to see all columns

Success Response (200 OK)

{
  "status": "success",
  "rental": {
    "activation_id": 123456,
    "phone_number": "+1234567890",
    "status": "waiting",
    "service": "gmail",
    "expires_at": "2025-01-12T10:30:00Z"
  }
}

cURL Example

curl -X POST https://smsvilla.com/api/v1/rent \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "service_code": "gmail",
    "area_code": "234",
    "carrier": "vz"
  }'
GET

Get SMS Messages

Retrieve all SMS messages received for a specific activation.

Endpoint

GET /api/v1/get-sms?activation_id=123456

Query Parameters

Parameter Type Description
activation_id integer ID from /rent response

Success Response (200 OK)

{
  "status": "success",
  "messages": [
    {
      "id": 778899,
      "text": "Your Gmail verification code is 543210",
      "code": "543210",
      "created_at": "2025-01-12T10:15:20Z"
    }
  ]
}

cURL Example

curl -X GET "https://smsvilla.com/api/v1/get-sms?activation_id=123456" \
  -H "Authorization: Bearer YOUR_API_KEY"
POST

Cancel Rental

Cancel an active rental and release the phone number. This will refund the unused portion if no SMS was received.

Request Body

{
  "activation_id": 123456
}

Parameters

Field Type Required
activation_id integer Yes

Success Response (200 OK)

{
  "status": "success",
  "message": "Rental canceled and refund queued"
}

⚠️ Note: Refunds are only issued if no SMS has been received for this activation.

cURL Example

curl -X POST https://smsvilla.com/api/v1/cancel \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "activation_id": 123456
  }'
GET

Check SMS Status

Poll this endpoint to check if an SMS has been received for your rental.

Endpoint

GET /api/v1/status?activation_id=123456

Query Parameters

Parameter Type Description
activation_id integer ID from /rent response

Success Response (200 OK)

{
  "status": "received",
  "code": "543210",
  "text": "Your OTP is 543210",
  "received_at": "2025-01-12T10:15:20Z"
}

💡 Tip: Status will be "waiting" until an SMS is received. Poll every 2-3 seconds.

cURL Example

curl -X GET "https://smsvilla.com/api/v1/status?activation_id=123456" \
  -H "Authorization: Bearer YOUR_API_KEY"
POST

Webhook Events

Instead of polling, configure a webhook URL to receive real-time notifications when SMS messages arrive.

✅ Recommended: Webhooks provide instant delivery and eliminate the need for polling.

Webhook Payload

{
  "activationId": 123456,
  "messageId": 778899,
  "service": "gmail",
  "code": "543210",
  "text": "Your Gmail code is 543210",
  "receivedAt": "2025-01-12T10:15:20Z"
}

Expected Response

Your webhook endpoint must respond with a 200 status code:

{ "status": "ok" }

Error Codes

400 Bad Request

Invalid request parameters or missing required fields

401 Unauthorized

Invalid or missing API key

404 Not Found

Activation ID not found or expired

429 Too Many Requests

Rate limit exceeded

500 Server Error

Internal server error - contact support