smscheck - API Documentation

🚀 Getting Started

Welcome to the smscheck API! Our API allows you to programmatically access SMS verification services, manage phone number rentals, check SMS history, and integrate verification workflows into your applications.

📌 Base URL

All API requests should be made to: https://api.smscheck.net/

Quick Start Guide

Create a smscheck account and navigate to your settings page.

Get API Key

Generate your API key from the API section in your dashboard.

Make Requests

Use your API key in the Authorization header to start making requests.

Handle Responses

Process JSON responses and handle errors appropriately.

🔐 Authentication

smscheck uses API keys to authenticate requests. You can generate and manage your API keys from your account settings.

🔒 Security Notice

Keep your API keys secure! Do not share them in publicly accessible areas such as GitHub, client-side code, or in public repositories.

Authentication Method

Include your API key in the Authorization header of each request:

HTTP Header

Authorization: Bearer YOUR_API_KEY_HERE

Example Request

cURL

curl -X GET "https://api.smscheck.net/balance" \
     -H "Authorization: Bearer YOUR_API_KEY_HERE" \
     -H "Content-Type: application/json"

Python

import requests

headers = {
    "Authorization": "Bearer YOUR_API_KEY_HERE",
    "Content-Type": "application/json"
}

response = requests.get("https://api.smscheck.net/balance", headers=headers)
data = response.json()

JavaScript

const headers = {
    "Authorization": "Bearer YOUR_API_KEY_HERE",
    "Content-Type": "application/json"
};

fetch("https://api.smscheck.net/balance", { headers })
    .then(response => response.json())
    .then(data => console.log(data));

📡 API Endpoints

GET /balance

Retrieve your current account balance.

Response

JSON Response

{
    "status": "success",
    "data": {
        "balance": "125.50",
        "currency": "USD"
    }
}

GET /services

Get a list of all available services with pricing information.

Query Parameters

Parameter	Type	Required	Description
country	string	Optional	Filter services by country code (e.g., "US", "UK")

Response

JSON Response

{
    "status": "success",
    "services": [
        {
            "id": "whatsapp",
            "name": "WhatsApp",
            "category": "Messaging",
            "price": "0.50",
        },
        {
            "id": "telegram",
            "name": "Telegram",
            "category": "Messaging",
            "price": "0.35",
        }
    ]
}

POST /verifications

Create a new SMS verification request.

Request Body

Parameter	Type	Required	Description
service	string	Required	Service ID (e.g., "whatsapp", "telegram")
number	string	Optional	Preferred phone number

Request Example

JSON

{
    "service": "whatsapp",

}

Response

JSON Response

{
    "status": "success",
        "data": {
            "verification_id": 123,
            "phone_number": "+1234567890",
            "service": "whatsapp",
            "status": "pending",
            "cost": "0.50",
            "expires_at": "2025-11-18T12:30:00Z",
            "created_at": "2025-11-18T12:00:00Z"
        }
}

JSON Response

{
    "status": "error",
    "error": {
        "code": "insufficient_balance",
        "message": "Insufficient balance. Required: $0.50, Available: $0.25"
    }
}

GET /verifications/{verification_id}

Check the status of a verification request and retrieve SMS code if available.

Response

JSON Response - Pending

{
    "status": "success",
    "data": {
        "verification_id": 123,
        "phone_number": "+1234567890",
        "service": "whatsapp",
        "status": "pending",
        "sms_code": null,
        "sms_text": null,
        "cost": "0.50",
        "created_at": "2025-11-18T12:00:00Z",
        "expires_at": "2025-11-18T12:30:00Z"
    }
}

JSON Response - Completed

{
    "status": "success",
    "data": {
        "verification_id": 123,
        "phone_number": "+1234567890",
        "service": "whatsapp",
        "status": "completed",
        "sms_code": "123456",
        "sms_text": "Your WhatsApp verification code is: 123456",
        "cost": "0.50",
        "created_at": "2025-11-18T12:00:00Z",
        "expires_at": "2025-11-18T12:30:00Z"
    }
}

DELETE /verifications/{verification_id}

Cancel a pending verification and receive a refund if no SMS was received.

Response

JSON Response

{
    "status": "success",
    "data": {
        "verification_id": 123,
        "cancelled": true,
        "refunded": true,
        "refund_amount": "0.50"
    }
}

JSON Response

{
    "status": "error",
    "error": {
        "code": "cannot_cancel",
        "message": "Cannot cancel verification in status: completed"
    }
}

Phone Number Rental

GET /rentals

Get a list of all your phone number rentals.

Query Parameters

Parameter	Type	Required	Description
page	integer	Optional	Page number (default: 1).
page_size	integer	Optional	Items per page (default: 15, max: 100).
query	string	Optional	Search query to filter rentals.

Response

JSON Response

{
    "status": "success",
    "data": {
        "rentals": [
            {
                "rental_id": 123,
                "phone_number": "+1234567890",
                "country": "US",
                "service": "whatsapp",
                "status": "online",
                "cost": "15.00",
                "created_at": "2025-11-18T12:00:00Z",
                "expires_at": "2025-11-24T12:00:00Z",
                "days_left": 6,
                "till_change": 270,
                "autorenew": false
            }
        ],
        "pagination": {
            "page": 1,
            "page_size": 15,
            "total": 1,
            "has_more": false
        }
    }
}

POST /rentals/create

Rent a phone number for a specified duration.

Request Body

Parameter	Type	Required	Description
service	string	Required	Service name for the rental.
duration	integer	Required	Rental duration in days (3 or 30).
number	string	Optional	Specific phone number to rent, if available.

Request Example

JSON

{
    "service": "whatsapp",
    "duration": 3
}

Response

JSON Response

{
    "status": "success",
    "data": {
        "rental_id": 123,
        "phone_number": "+1234567890",
        "service": "whatsapp",
        "status": "online",
        "cost": "15.00",
        "duration_days": 3,
        "expires_at": "2025-11-21T12:00:00Z",
        "created_at": "2025-11-18T12:00:00Z",
        "autorenew": false
    }
}

GET /rentals/{rental_id}/messages

Retrieve all SMS messages received on a rented number.

Query Parameters

Parameter	Type	Required	Description
page	integer	Optional	Page number (default: 1).
page_size	integer	Optional	Items per page (default: 10, max: 100).

Response

JSON Response

{
    "status": "success",
    "data": {
        "rental_id": 123,
        "messages": [
            {
                "message_id": 1,
                "sender": "WhatsApp",
                "code": "123456",
                "text": "Your verification code is 123456",
                "received_at": "2025-11-18T11:30:00Z"
            },
            {
                "message_id": 2,
                "sender": "Telegram",
                "code": "654321",
                "text": "Your Telegram code is 654321",
                "received_at": "2025-11-18T11:45:00Z"
            }
        ],
        "pagination": {
            "page": 1,
            "page_size": 10,
            "total": 2,
            "has_more": false
        }
    }
}

DELETE /rentals/{rental_id}

Cancel a rental and receive a refund if eligible.

Response

JSON Response

{
    "status": "success",
    "data": {
        "rental_id": 123,
        "cancelled": true,
        "refunded": true,
        "refund_amount": "15.00"
    }
}

POST /rentals/{rental_id}/activate

Activate a rented number to receive SMS messages.

Response

JSON Response

{
    "status": "success",
    "data": {
        "rental_id": 123,
        "status": "online",
        "till_change": 270,
        "message": "Activated successfully"
    }
}

POST /rentals/{rental_id}/autorenew

Toggle the autorenew status for a rental.

Response

JSON Response

{
    "status": "success",
    "data": {
        "rental_id": 123,
        "autorenew": true,
        "message": "Autorenew has been turned ON"
    }
}

🔔 Webhooks

Webhooks allow you to receive real-time notifications when SMS messages are received. You need to add your webhook endpoint URL in the Settings section of your account to start receiving notifications.

💡 How it works

When an SMS is received, we'll send a POST request to your configured webhook URL with the message details.

⚙️ Configuration Required

Before you can receive webhook notifications, you must configure your webhook endpoint URL in your account Settings. Make sure your endpoint is publicly accessible and can handle POST requests.

Webhook Payload for Incoming SMS

JSON Payload

{
    "event": "incoming_message",
    "order_id": 12345,
    "from": "Service",
    "to": "+1234567890",
    "code": "123456",
    "text": "Your verification code is 123456"
}

⚠️ Error Handling

smscheck uses conventional HTTP response codes to indicate the success or failure of an API request.

HTTP Status Codes

Status Code	Meaning	Description
200	OK	Request succeeded
201	Created	Resource was created successfully
400	Bad Request	Invalid request parameters
401	Unauthorized	Invalid or missing API key
402	Payment Required	Insufficient balance
404	Not Found	Resource not found
429	Too Many Requests	Rate limit exceeded
500	Internal Server Error	Something went wrong on our end

Error Response Format

JSON Error Response

{
    "status": "error",
    "error": {
        "code": "insufficient_balance",
        "message": "Your account balance is too low to complete this request",
        "details": {
            "current_balance": "0.25",
            "required_balance": "0.50"
        }
    }
}

⏱️ Rate Limits

To ensure fair usage and system stability, API requests are rate-limited based on your account tier.

100

Requests per minute

5,000

Requests per hour

50,000

Requests per day

⚡ Rate Limit Headers

Each API response includes headers showing your current rate limit status:

X-RateLimit-Limit - Maximum requests allowed
X-RateLimit-Remaining - Requests remaining
X-RateLimit-Reset - Time when the limit resets

💬 Support & Resources

Need help? We're here for you!

📧

Email Support

support@smscheck.net

📖

Documentation

Comprehensive guides and tutorials

API Documentation

Quick Navigation

🚀 Getting Started

Quick Start Guide

🔐 Authentication

Authentication Method

Example Request

📡 API Endpoints

Response

Query Parameters

Response

Request Body

Request Example

Response

Response

Response

Phone Number Rental

Query Parameters

Response

Request Body

Request Example

Response

Query Parameters

Response

Response

Response

Response

🔔 Webhooks

Webhook Payload for Incoming SMS

⚠️ Error Handling

HTTP Status Codes

Error Response Format

⏱️ Rate Limits

💬 Support & Resources