API Documentation - SMS-Cheap

Getting Started

This guide will get you all set up and ready to use the Activation API. We'll cover how to get started using one of our API clients and how to make your first API request. We'll also look at where to go next to find all the information you need to take full advantage of our powerful REST API.

Before you can make requests to the API, you will need to grab your API key from your dashboard. You find it under Settings » API Key.

Balance Check

Check your account balance and currency information.

Request

GET -


                    https://api.sms-cheap.com/v1/balance?api_key=$api_key

Parameters:
$api_key: YOUR_API_KEY

Response

{
    "status": "success",
    "balance": {
        "amount": "15.59",
        "currency": "USD"
    }
}

Services List

Get a list of all available services for SMS verification.

Request

GET -


                    https://api.sms-cheap.com/v1/services?api_key=$api_key

Parameters:
$api_key: YOUR_API_KEY

Response

{
    "status": "success",
    "services": [
        {
            "id": "wa",
            "name": "WhatsApp",
            "visible": 1
        },
        {
            "id": "tg",
            "name": "Telegram",
            "visible": 1
        },
        {
            ...
        }
    ]
}

You can check the active/inactive status of a service with Visible. You cannot create an order for services that are set to false (0).

Countries List

Get a list of all available countries for SMS verification.

Request

GET -


                    https://api.sms-cheap.com/v1/countries?api_key=$api_key

Parameters:
$api_key: YOUR_API_KEY

Response

{
    "status": "success",
    "countries": [
        {
            "id": "0",
            "name": "Russia",
            "visible": 1
        },
        {
            "id": "6",
            "name": "Indonesia",
            "visible": 1
        },
        {
            ...
        }
    ]
}

You can check the active/inactive status of a country with Visible. You cannot create an order for countries with a value of false (0).

Prices List

Get prices for all services and countries. You can filter by service and/or country. Optionally include detailed pricing options.

Request

GET -


                    https://api.sms-cheap.com/v1/prices?service=$service&country=$country&api_key=$api_key

Parameters:
$service: SERVICE_ID
$country: COUNTRY_ID
$options: TRUE (optional)
$api_key: YOUR_API_KEY

If service and country id values are not entered, all prices will be returned by default.

Set $options=TRUE to include detailed pricing options for each product.

Response

{
    "status": "success",
    "prices": {
        "wa": {
            "0": {
                "price": 0.56,
                "stock": 1232
            },
            // With options=true, the response will be like this:
            "6": {
                "price": 0.15,
                "stock": 5678,
                "options": {
                    "0.15": 5678,
                    "0.12": 12345,
                    "0.42": 45678,
                    "0.16": 23456
                }
            },
            ...
        },
        "tg": {
            "0": {
                "price": 0.05,
                "stock": 45678
            },
            ...
        }
    }
}

Create Order

Create a new SMS verification order. This will deduct the required amount from your balance. You can optionally specify a specific price from the available options.

Important Note

Don't forget to save the id from the response. You will need this order ID to check the status or cancel the order later. Use the options parameter in the prices list API to see available pricing options.

Request

GET -


                    https://api.sms-cheap.com/v1/order?service=$service&country=$country&api_key=$api_key

Parameters:
$service: SERVICE_ID
$country: COUNTRY_ID
$price: PRICE_VALUE (optional)
$api_key: YOUR_API_KEY

Response

{
    "status": "success",
    "order": {
        "id": "5124502796",
        "phone_number": "79110123456",
        "price": 0.16,
        "currency": "USD",
        "time": "2025-07-12 07:14:38"
    }
}

Order Status

Check the status of an existing order and get SMS code if available.

Request

GET -


                    https://api.sms-cheap.com/v1/order/$order_id/status?api_key=$api_key

Parameters:
$order_id: ORDER_ID
$api_key: YOUR_API_KEY

The $order_id is the id value from the create order response.

Response

{
    "status": "success",
    "order": {
        "id": "5124502796",
        "phone_number": "79110123456",
        "status": "completed",
        "message": "123456",
        "message_detail": "Your WhatsApp code is: 123456",
        "price": 0.16,
        "currency": "USD",
        "time": "2025-07-12 07:14:38",
        "expires_at": "2025-07-12 07:34:38"
    }
}

Cancel Order

Cancel an active order and get a refund. Orders can only be cancelled after 2 minutes from creation.

Request

GET -


                    https://api.sms-cheap.com/v1/order/$order_id/cancel?api_key=$api_key

Parameters:
$order_id: ORDER_ID
$api_key: YOUR_API_KEY

The $order_id is the id value from the create order response.

Response

{
    "status": "success",
    "message": "Order cancelled successfully",
    "order": {
        "id": "5124502796",
        "refund_amount": 0.16,
        "currency": "USD"
    }
}

Error Codes

In this guide, we will talk about what happens when something goes wrong while you work with the API. You can tell if your request was successful by checking the status code when receiving an API response. If a response comes back unsuccessful, you can use the error type and error message to figure out what has gone wrong.

Status Codes

Here is a list of the different categories of status codes returned by our API. Use these to understand if a request was successful.

2xx

Success

A 2xx status code indicates a successful response.

4xx

Client Error

A 4xx status code indicates a client error — this means it's a you problem.

5xx

Server Error

A 5xx status code indicates a server error — you won't be seeing these.

Common Error Codes

Here are the most common error codes you might encounter while using our API.

400

Bad Request

Insufficient balance

Your account balance is not enough for this operation

Invalid price

The specified price is not available for the selected service/country

Validation failed

Required parameters are missing or invalid

Wait at least 2 minutes before cancelling

Order cancellation time restriction

404

Not Found

Service or country not found

Invalid service or country ID

Product not available

No active product for the requested service/country

Order not found

Order ID does not exist or belongs to another user

500

Server Error

Operator not available

SMS provider service is temporarily unavailable

Failed to get number from operator

Operator could not provide a phone number

An error occurred

Unexpected server error

429

Too Many Requests

Rate limit exceeded

You have exceeded the rate limit

401

Unauthorized

API key is required

No API key provided in request headers or query parameters

Invalid API key

The provided API key is invalid or inactive

403

Forbidden

IP not whitelisted

Your IP address is not in the allowed IP whitelist. Configure IP whitelist in your API key settings

Before reaching out to support

Please be aware that 99% of all reported errors are, in fact, user errors. Therefore, please carefully check your code before contacting support.