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"

📡 API Endpoints

GET /balance

Retrieve your current account balance.

Request Example

cURL

curl -X GET "https://api.smscheck.net/balance" \
     -H "Authorization: Bearer YOUR_API_KEY"

Response

JSON Response

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

GET /services

Get a list of all available services with pricing information. Each service appears once: one_time is the price of a one-time USA verification (null if the service has no USA option), while three_day and thirty_day are long-term rental prices (null for services without long-term rental).

Routing is country-driven. has_usa tells you the service can be bought for the USA (use name as the service when creating a verification). has_non_usa: true means the service is available for other countries via the non-USA pool: use pool_code with GET /services/countries and GET /services/offers to discover countries and prices, and non_usa_from is the cheapest non-USA "from" price. A service with has_usa: false is sold only outside the USA and has id: null and one_time: null.

Request Example

cURL

curl -X GET "https://api.smscheck.net/services" \
     -H "Authorization: Bearer YOUR_API_KEY"

Response

JSON Response

{
    "status": "success",
    "data": {
        "services": [
            {
                "id": 42,
                "name": "whatsapp",
                "display_name": "WhatsApp",
                "slug": "whatsapp",
                "pool_code": "wa",
                "has_usa": true,
                "has_non_usa": true,
                "non_usa_from": "0.30",
                "pricing": {
                    "one_time": "0.50",
                    "three_day": "3.00",
                    "thirty_day": "15.00"
                }
            },
            {
                "id": 57,
                "name": "telegram",
                "display_name": "Telegram",
                "slug": "telegram",
                "pool_code": "",
                "has_usa": true,
                "has_non_usa": false,
                "non_usa_from": null,
                "pricing": {
                    "one_time": null,
                    "three_day": "3.50",
                    "thirty_day": "18.00"
                }
            },
            {
                "id": null,
                "name": "signal",
                "display_name": "Signal",
                "slug": "signal",
                "pool_code": "sg",
                "has_usa": false,
                "has_non_usa": true,
                "non_usa_from": "0.25",
                "pricing": {
                    "one_time": null,
                    "three_day": null,
                    "thirty_day": null
                }
            }
        ],
        "count": 3
    }
}

GET /services/countries

List the non-USA countries that offer a service, ranked by popularity. The USA itself is not listed here — it is fulfilled separately (see the service's one_time price). Use the pool_code from a /services entry as the service parameter.

Query Parameters

Parameter	Type	Required	Description
service	string	Required	Non-USA service code (the `pool_code` from `/services`).

Request Example

cURL

curl -X GET "https://api.smscheck.net/services/countries?service=wa" \
     -H "Authorization: Bearer YOUR_API_KEY"

Response

JSON Response

{
    "status": "success",
    "data": {
        "countries": [
            {
                "id": 1,
                "name": "Ukraine",
                "price": 0.3,
                "count": 84
            },
            {
                "id": 7,
                "name": "Poland",
                "price": 0.42,
                "count": 20
            }
        ]
    }
}

GET /services/offers

List the price offers (pools) for a service in a specific non-USA country. Pick an offer and pass its max_price to POST /verifications as the price ceiling. Offers are sorted cheapest first; charged_price is what you pay.

Query Parameters

Parameter	Type	Required	Description
service	string	Required	Non-USA service code (the `pool_code` from `/services`).
country	integer	Required	Country id from `/services/countries`.

Request Example

cURL

curl -X GET "https://api.smscheck.net/services/offers?service=wa&country=1" \
     -H "Authorization: Bearer YOUR_API_KEY"

Response

JSON Response

{
    "status": "success",
    "data": {
        "default_price": 0.3,
        "offers": [
            {
                "provider_price": 0.25,
                "charged_price": 0.3,
                "count": 84,
                "max_price": 0.25
            }
        ]
    }
}

POST /verifications

Create a new SMS verification request. Routing is country-driven: omit country (or send US) for a USA number — pass the service's name as service. For any other country pass the pool_code as service, a numeric country id, and a max_price ceiling (an offer's max_price from /services/offers). A missing max_price for a non-USA country returns 400; an unknown service returns 404.

Request Body

Parameter	Type	Required	Description
service	string	Required	For USA: the service `name` (e.g., "whatsapp"). For a non-USA country: the `pool_code` from `/services`.
country	string	Optional	Omit or `US` for a USA number. A numeric country id (from `/services/countries`) routes to that country.
max_price	string	Optional	Required for non-USA countries: the chosen offer's `max_price` from `/services/offers`. Caps what you can be charged. Ignored for USA.
country_name	string	Optional	Display label stored with the order (non-USA). Resolved automatically if omitted.

Request Example — USA

cURL

curl -X POST "https://api.smscheck.net/verifications" \
     -H "Authorization: Bearer YOUR_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{"service": "whatsapp"}'

Request Example — non-USA

cURL

curl -X POST "https://api.smscheck.net/verifications" \
     -H "Authorization: Bearer YOUR_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{"service": "wa", "country": "1", "max_price": "0.25"}'

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"
    }
}

GET /verifications/{verification_id}

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

Request Example

cURL

curl -X GET "https://api.smscheck.net/verifications/123" \
     -H "Authorization: Bearer YOUR_API_KEY"

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

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

Request Example

cURL

curl -X DELETE "https://api.smscheck.net/verifications/123/cancel" \
     -H "Authorization: Bearer YOUR_API_KEY"

Response

JSON Response

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

Phone Number Rental

GET /rentals

Get a list of all your phone number rentals.

Request Example

cURL

curl -X GET "https://api.smscheck.net/rentals?page=1&page_size=15" \
     -H "Authorization: Bearer YOUR_API_KEY"

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

cURL

curl -X POST "https://api.smscheck.net/rentals/create" \
     -H "Authorization: Bearer YOUR_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{"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.

Request Example

cURL

curl -X GET "https://api.smscheck.net/rentals/123/messages" \
     -H "Authorization: Bearer YOUR_API_KEY"

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.

Request Example

cURL

curl -X DELETE "https://api.smscheck.net/rentals/123" \
     -H "Authorization: Bearer YOUR_API_KEY"

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.

Request Example

cURL

curl -X POST "https://api.smscheck.net/rentals/123/activate" \
     -H "Authorization: Bearer YOUR_API_KEY"

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.

Request Example

cURL

curl -X POST "https://api.smscheck.net/rentals/123/autorenew" \
     -H "Authorization: Bearer YOUR_API_KEY"

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
405	Method Not Allowed	Wrong HTTP method for this endpoint
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"
        }
    }
}

💬 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

Request Example

Response

Request Example

Response

Query Parameters

Request Example

Response

Query Parameters

Request Example

Response

Request Body

Request Example — USA

Request Example — non-USA

Response

Request Example

Response

Request Example

Response

Phone Number Rental

Request Example

Query Parameters

Response

Request Body

Request Example

Response

Request Example

Query Parameters

Response

Request Example

Response

Request Example

Response

Request Example

Response

🔔 Webhooks

Webhook Payload for Incoming SMS

⚠️ Error Handling

HTTP Status Codes

Error Response Format

💬 Support & Resources